postgraphile-plugin-many-create-update-delete/README.md

Postgraphile plugin that enables many create, update, & delete mutations in a single transaction.

# postgraphile-plugin-batch-create-update-delete

![npm](https://img.shields.io/npm/v/postgraphile-plugin-many-create-update-delete)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)

This plugin implements mutations that allow many creates, updates, and deletes in a single transaction.

To support, Please 🌟 if you used / like this library.

## Roadmap
Here's the plan:

- [ ] Add a test suite, CI, and better test example in the readme.
- [ ] Update smart comments with better functionality to include individual create, update, or  delete mutations vs. including them all together.
- [ ] Add plugin options that allow conflict handling for inserts. This would allow updates (upsert), no action, failures (current default) based off the constraints or further options.
- [ ] Add input types for the many updates and delete mutations, to show required constraints vs. using the table patch types that do not.
- [ ] Add better returned payload options, preferably to return a list of modified records.
- [ ] Add support for node id based updates and deletes.

## Getting Started

View the [postgraphile docs](https://www.graphile.org/postgraphile/extending/#loading-additional-plugins) for information about loading the plugin via the CLI or as a NodeJS library.

## Plugin Options

This plugin respects the default option to disable mutations all together via ```graphileBuildOptions```.

```js
postgraphile(pgConfig, schema, {
  graphileBuildOptions: {
    pgDisableDefaultMutations: true
  }
});
```

## Smart Comments

You must use smart comments to enable the many create, update, and delete mutations for a table, since they are not enabled by default to prevent crowding with the other autogenerated postgraphile default mutations. The single tag ```@mncud``` is all that's needed.

```sql
comment on table public."Test" is
  E'@mncud\n The test table is just for showing this example with comments.';
```

## Usage

The plugin creates new mutations that allow you to batch create, update, and delete items from a given table. It works with primary keys for updates and deletes using the input patch that postgraphile generates. All creates, updates, and deletes have scoped names with "mn" in front of the mutation name to prevent conflicts with other mutations.

### Creates
```mnCreateTest``` would be an example mutation name, and we'll say it has attributes of test1 (a boolean), and name (a varchar). You'll see the required input has the clientMutationId and also a field called ```mnTest```, where ```mnTest``` will take an array of items that use the table input type. Since it uses the table input type, the required items are all listed as expected. When creating records, any attributes left off will have their values set to ```default```.

### Updates
```mnUpdateTestByName``` would be the update example name, assuming the name is the primary key. Updates have a required input with the clientMutatationId and a patch. The patch field accepts an array of table patch items. You ***MUST*** provide the primary key within the patch items b/c that is what's used in the where clause to update the correct row(s). Attributes that are not provided in the list of provided values, will not be updated. With that said, you can update different attributes in one record and leave them off in another and it will update both as expected.

### Deletes
```mnDeleteTestByName``` would be the delete example name. Deletes have a required input with the clientMutationId and a patch. The patch field accepts an array of table patch items, but only the primary key items are used. You ***MUST*** provide the primary key(s) within the patch items b/c that is what's used in the where clause to delete the correct row(s).

## Contribute

1. Fork it and create your feature branch: `git checkout -b my-new-feature`
2. Commit your changes: `git commit -am "Add some feature"`
3. Push to the branch: `git push origin my-new-feature`
4. Submit a pull request.

## License

MIT