Registry / database / postgraphile-upsert-plugin

postgraphile-upsert-plugin

JSON →
library3.3.0jsnpmunverified

A Plugin for PostGraphile that adds Postgres upsert mutations (INSERT … ON CONFLICT DO UPDATE) to your GraphQL API. Current stable version is 3.3.0, released under semantic-release cadence. Supports single and multi-column unique indexes via an optional `where` clause, and allows omitting columns from the update set using `@omit updateOnConflict` smart tags. Differentiates from the original generator-based plugin by being fully TypeScript-typed and following modern PostGraphile plugin conventions. Requires PostGraphile v4 or later.

database
npm install postgraphile-upsert-plugin
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · POSTGRAPHILE-UPSER
P
postgraphile-upsert-plugin
databasejavascriptv3.3.0
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PgMutationUpsertPlugin
✓ import PgMutationUpsertPlugin from 'postgraphile-upsert-plugin'
✗ const PgMutationUpsertPlugin = require('postgraphile-upsert-plugin')
Default export; does NOT named export. The package ships TypeScript types so default import works with ES module interop.
withPgClient, makePluginByCombiningPlugins
✓ import { withPgClient } from 'postgraphile'; import { makePluginByCombiningPlugins } from 'graphile-build'
✗ import { withPgClient } from 'postgraphile-upsert-plugin'
These symbols are from PostGraphile core or graphile-build, NOT from this plugin.
Plugin loading via CLI
✓ postgraphile --append-plugins postgraphile-upsert-plugin:PgMutationUpsertPlugin
✗ postgraphile --plugins postgraphile-upsert-plugin
CLI arguments must be separated by colon for path and exported symbol. Using the wrong argument (--plugins vs --append-plugins) will not load the plugin correctly.
postgraphile function options
✓ postgraphile(pgConfig, schema, { appendPlugins: [PgMutationUpsertPlugin] })
✗ postgraphile(pgConfig, schema, { plugins: [PgMutationUpsertPlugin] })
The option key is 'appendPlugins', not 'plugins', or 'prependPlugins'.

Shows how to install the plugin in a PostGraphile server using Express and the appendPlugins configuration.

import express from 'express'; import { postgraphile } from 'postgraphile'; import PgMutationUpsertPlugin from 'postgraphile-upsert-plugin'; const app = express(); app.use( postgraphile('postgres://localhost/my_db', 'public', { appendPlugins: [PgMutationUpsertPlugin], }) ); app.listen(5000, () => console.log('Server running on port 5000'));
Debug
Known issues
gotchaThe upsert mutation requires that the table has at least one unique constraint, otherwise GraphQL schema generation will fail.
fix
Ensure your Postgres table has a primary key or a unique index on the columns used in the 'where' argument.
affects: >=1.0.0
gotchaAll columns that are part of the unique constraint must be provided in the 'input' (even if not updating) otherwise the mutation may attempt an insert and violate the constraint.
fix
Include all columns from the unique constraint in the input object.
affects: >=1.0.0
breakingVersion 2.0.0 changed the plugin's export from a named export to a default export.
fix
Use import PgMutationUpsertPlugin from 'postgraphile-upsert-plugin' instead of import { PgMutationUpsertPlugin } from 'postgraphile-upsert-plugin'.
affects: >=2.0.0 <3.0.0
gotchaThe @omit updateOnConflict smart tag works only on columns, not on comments attached to constraints.
fix
Place the smart tag on the specific column comment, not on the constraint comment.
affects: >=1.0.0
Errors
Common errors & fixes
Error: upsert mutations require a unique constraint on the table
The target table lacks a primary key or unique index.
fix
Add a primary key or unique constraint to the table.
Cannot find module 'postgraphile-upsert-plugin'
Package not installed or import path is incorrect.
fix
Run 'npm install postgraphile-upsert-plugin' and ensure the import path matches the package name.
TypeError: (0 , postgraphile_upsert_plugin_1.default) is not a function
CommonJS require does not work with default exports in TypeScript-friendly packages.
fix
Use import PgMutationUpsertPlugin from 'postgraphile-upsert-plugin' instead of const PgMutationUpsertPlugin = require('postgraphile-upsert-plugin').default.
Upgrade
Version history
3.3.0latest on npm
Audit
Dependencies
postgraphilerequiredRequired peer dependency – this plugin extends PostGraphile's mutation system
Agent activity
4 hits · last 30 days
node
4
Resources
githubhttps://github.com/cdaringe/postgraphile-upsert ↗
packagepostgraphile-upsert-plugin ↗
homepagehttps://github.com/cdaringe/postgraphile-upsert#readme ↗
postgraphile-upsert-plugin — npm install postgraphile-upsert-plugin · libregistry