# postgraphile-plugin-nested-mutations
> Nested mutations plugin for PostGraphile
Latest version **1.1.0** (published 2021-03-26) · MIT license · 0 weekly downloads
## Install
```sh
npm install postgraphile-plugin-nested-mutations
pnpm add postgraphile-plugin-nested-mutations
yarn add postgraphile-plugin-nested-mutations
bun add postgraphile-plugin-nested-mutations
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 1.1.0 |
| Published | 2021-03-26 |
| First published | 2018-07-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 74.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 82 |
| Author | Mark Lipscombe |
| Maintainers | mlipscombe |
## Links
- npm: https://www.npmjs.com/package/postgraphile-plugin-nested-mutations
- Repository: https://github.com/mlipscombe/postgraphile-plugin-nested-mutations
- Homepage: https://github.com/mlipscombe/postgraphile-plugin-nested-mutations#readme
- Issues: https://github.com/mlipscombe/postgraphile-plugin-nested-mutations/issues
- npm.io page: https://npm.io/package/postgraphile-plugin-nested-mutations
## Dependencies (1)
- [graphile-build-pg](https://npm.io/package/graphile-build-pg.md) ^4.11.2
## Recent versions
- 1.1.0 (latest) — 2021-03-26
- 1.0.1 — 2019-08-11
- 1.0.0 — 2019-07-24
- 1.0.0-alpha.23 — 2019-02-12
- 1.0.0-alpha.22 — 2019-02-08
- 1.0.0-alpha.21 — 2019-01-22
- 1.0.0-alpha.20 — 2019-01-19
- 1.0.0-alpha.19 — 2019-01-16
- 1.0.0-alpha.18 — 2019-01-15
- 1.0.0-alpha.17 — 2019-01-14
- 1.0.0-alpha.16 — 2019-01-14
- 1.0.0-alpha.15 — 2019-01-10
- 1.0.0-alpha.14 — 2019-01-08
- 1.0.0-alpha.13 — 2019-01-03
- 1.0.0-alpha.12 — 2018-12-31
- … 11 more at https://npm.io/package/postgraphile-plugin-nested-mutations/versions
## README
[](https://www.npmjs.com/package/postgraphile-plugin-nested-mutations)
[](https://circleci.com/gh/mlipscombe/postgraphile-plugin-nested-mutations/tree/master)
# postgraphile-plugin-nested-mutations
This plugin implements nested mutations based on both forward and reverse foreign
key relationships in PostGraphile v4. Nested mutations can be of infinite depth.
## Getting Started
### CLI
``` bash
postgraphile --append-plugins postgraphile-plugin-nested-mutations
```
See [here](https://www.graphile.org/postgraphile/extending/#loading-additional-plugins) for
more information about loading plugins with PostGraphile.
### Library
``` js
const express = require('express');
const { postgraphile } = require('postgraphile');
const PostGraphileNestedMutations = require('postgraphile-plugin-nested-mutations');
const app = express();
app.use(
postgraphile(pgConfig, schema, {
appendPlugins: [
PostGraphileNestedMutations,
],
})
);
app.listen(5000);
```
### Plugin Options
When using PostGraphile as a library, the following plugin options can be passed
via `graphileBuildOptions`:
nestedMutationsSimpleFieldNames
Use simple field names for nested mutations. Instead of names suffixed with
`tableBy` and `tableUsing`, tables with a single foreign key relationship
between them will have their nested relation fields named `table`. Defaults to
`false`.
```js
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
nestedMutationsSimpleFieldNames: true,
}
});
```
nestedMutationsDeleteOthers
Controls whether the `deleteOthers` field is available on nested mutations. Defaults
to `true`.
```js
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
nestedMutationsDeleteOthers: false,
}
});
```
nestedMutationsOldUniqueFields
If enabled, plural names for one-to-one relations will be used. For backwards
compatibility. Defaults to `false`.
```js
postgraphile(pgConfig, schema, {
graphileBuildOptions: {
nestedMutationsOldUniqueFields: false,
}
});
```
## Usage
This plugin creates an additional field on each GraphQL `Input` type for every forward
and reverse foreign key relationship on a table, with the same name as the foreign table.
Each nested mutation field will have the following fields. They will accept an array if
the relationship is a one-to-many relationship, or a single input if they are one-to-one.
### Connect to Existing Record
#### `connectByNodeId`
Connect using a `nodeId` from the nested table.
#### `connectBy`
Connect using any readable primary key or unique constraint on the nested table.
### Creating New Records
#### `create`
Create a new record in the nested table.
### Delete existing Record
#### `deleteByNodeId`
Delete using a `nodeId` from the nested table.
#### `deleteBy`
Delete using any readable primary key or unique constraint on the nested table.
### Updating Records
#### `updateByNodeId`
Update a record using a `nodeId` from the nested table.
#### `updatedBy`
Update a record using any readable primary key or unique constraint on the nested table.
## Example
```sql
create table parent (
id serial primary key,
name text not null
);
create table child (
id serial primary key,
parent_id integer,
name text not null,
constraint child_parent_fkey foreign key (parent_id)
references p.parent (id)
);
```
A nested mutation against this schema, using `Parent` as the base mutation
would look like this:
``` graphql
mutation {
createParent(input: {
parent: {
name: "Parent 1"
childrenUsingId: {
connectById: [{
id: 1
}]
create: [{
name: "Child 1"
}, {
name: "Child 2"
}]
}
}
}) {
parent {
id
name
childrenByParentId {
nodes {
id
name
}
}
}
}
}
```
Or using `Child` as the base mutation:
``` graphql
mutation {
createChild(input: {
child: {
name: "Child 1"
parentToParentId: {
create: {
name: "Parent of Child 1"
}
}
},
}) {
child {
id
name
parentByParentId {
id
name
}
}
}
}
```
## Smart Comments
[Smart comments](https://www.graphile.org/postgraphile/smart-comments/) are supported for
renaming the nested mutation fields.
```sql
comment on constraint child_parent_fkey on child is
E'@fieldName parent\n@foreignFieldName children';
```
---
_Source: https://npm.io/package/postgraphile-plugin-nested-mutations · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._