Exciting release!Introducing "safe npm". Learn more
Log inDemoInstall


Package Overview
File Explorer

Advanced tools


Postgraphile plugin to enable mutation atomicty with GraphQL requests containing multiple mutations


Version published
Weekly downloads
decreased by-47.78%

Weekly downloads



[1.0.4] - 2020-06-01


  • Fixed an error when operationName is set to null - Thanks hansallis.
  • Fixed an error which was caused by Subscription websocket messages.




npm package license

This Postgraphile plugin allows you to enable mutation atomicity with GraphQL requests containing multiple mutations.

It's ideal if you would like to have client request repeatability when at least one mutation in the GraphQL request fails. This would guarantee that either all the mutations in the request are committed when successful, or all are rolled back if at least one is erroneous.


yarn add postgraphile-plugin-atomic-mutations npm install postgraphile-plugin-atomic-mutations

Usage as Library

import { AtomicMutationsPlugin, getMutationAtomicityContext, } from 'postgraphile-plugin-atomic-mutations'; const app = express(); app.use( postgraphile(pgConfig, schema, { // Append the plugin to the array. appendPlugins: [AtomicMutationsPlugin], async additionalGraphQLContextFromRequest(req, res) { return { // Additional context needed by the plugin mutationAtomicityContext: getMutationAtomicityContext(req), }; }, }), ); app.listen(5000); const getMutationAtomicityContext = ( req, enablePluginByDefault = false, ): MutationAtomicityContext;

This function will extract the HTTP headers from the req object passed as the 1st argument to determine if the mutation atomicity behavior will be enabled or not. See Usage from Client for more details.

The 2nd argument enablePluginByDefault will determine plugin behavior when the HTTP header is not set (defaults to false).

Usage from Client

The plugin allows the client to decide when the mutation atomicity should be applied per GraphQL request, using a custom HTTP header 'X-Mutation-Atomicity', which can be set to either 'on' or 'off'.

mutation MultipleMutationOperation { # Mutation 1 - Successful createTenant(input: {tenant: {name: "New Tenant"}}) { tenant { id } } # Mutation 2 - Erroneous updateTenant(input: {patch: {name: "Updated Tenant Name"}, id: "dd0f6631-3905-4cc0-bc75-6c7b1dcafa89"}) { tenant { name } } # Mutation 3 - Successful deleteTenant(input: {id: "761aa030-6965-4cfe-90cf-00d2dec41c61"}) { tenant { name } } }

In the above example of a multiple mutation request, if we didn't use the plugin at all, the outcome would be that Mutations #1 & #3 will be committed to the database, while #2 will be rolled back due to its hypothetical error. But if the same request is sent again from the client, there will be new exceptions caused by mutations #1 & #3 (possibly for duplicate key violation, and no matching criteria).

Now instead if we use the plugin, and the same request is made with the 'X-Mutation-Atomicity: on' HTTP header set by the client, the Mutations #1 & #3 will never be committed to the database since Mutation #2 caused an error, thus, guaranteeing atomicity for the set of Mutations. If the client decides to re-run the same request again, the outcome will be the same.


  • If there already exists plugins which are used in postgraphile options, AtomicMutationsPlugin must be appended after them - i.e. appendPlugins: [SomePlugin, AnotherPlugin, AtomicMutationsPlugin].

  • As with any transaction management mechanism, the individual mutations must not contain any explicit commit or rollback commands.

  • Postgraphile v4 has an experimental feature enableQueryBatching which is currently not supported by the plugin.


  • Improve tests to have more code coverage.


This project uses yarn as the package manager, so make sure that pre-requisite is installed.

npm install -g yarn

Then clone & run yarn



Last updated on 01 Jun 2020

Did you know?

Socket installs a Github app to automatically flag issues on every pull request and report the health of your dependencies. Find out what is inside your node modules and prevent malicious activity before you update the dependencies.

Install Socket
support@socket.devSocket SOC 2 Logo


  • Package Issues
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc