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

1postgraphile --append-plugins postgraphile-plugin-nested-mutations

See here for more information about loading plugins with PostGraphile.

Library

1const express = require('express');
2const { postgraphile } = require('postgraphile');
3const PostGraphileNestedMutations = require('postgraphile-plugin-nested-mutations');
4
5const app = express();
6
7app.use(
8  postgraphile(pgConfig, schema, {
9    appendPlugins: [
10      PostGraphileNestedMutations,
11    ],
12  })
13);
14
15app.listen(5000);

Plugin Options

When using PostGraphile as a library, the following plugin options can be passed via graphileBuildOptions:

1postgraphile(pgConfig, schema, {
2  graphileBuildOptions: {
3    nestedMutationsSimpleFieldNames: true,
4  }
5});

1postgraphile(pgConfig, schema, {
2  graphileBuildOptions: {
3    nestedMutationsDeleteOthers: false,
4  }
5});

1postgraphile(pgConfig, schema, {
2  graphileBuildOptions: {
3    nestedMutationsOldUniqueFields: false,
4  }
5});

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<K>

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<K>

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<K>

Update a record using any readable primary key or unique constraint on the nested table.

Example

1create table parent (
2  id serial primary key,
3  name text not null
4);
5
6create table child (
7  id serial primary key,
8  parent_id integer,
9  name text not null,
10  constraint child_parent_fkey foreign key (parent_id)
11    references p.parent (id)
12);

A nested mutation against this schema, using Parent as the base mutation would look like this:

1mutation {
2  createParent(input: {
3    parent: {
4      name: "Parent 1"
5      childrenUsingId: {
6        connectById: [{
7          id: 1
8        }]
9        create: [{
10          name: "Child 1"
11        }, {
12          name: "Child 2"
13        }]
14      }
15    }
16  }) {
17    parent {
18      id
19      name
20      childrenByParentId {
21        nodes {
22          id
23          name
24        }
25      }
26    }
27  }
28}

Or using Child as the base mutation:

1mutation {
2  createChild(input: {
3    child: {
4      name: "Child 1"
5      parentToParentId: {
6        create: {
7          name: "Parent of Child 1"
8        }
9      }
10    },
11  }) {
12    child {
13      id
14      name
15      parentByParentId {
16        id
17        name
18      }
19    }
20  }
21}

Smart Comments

Smart comments are supported for renaming the nested mutation fields.

1comment on constraint child_parent_fkey on child is
2  E'@fieldName parent\n@foreignFieldName children';