graphile-bulk-mutations 0.2.0

package/plugins/BulkUpsertPlugin.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkUpsertPlugin = void 0;
+require("../augmentations");
+const pg_1 = require("@dataplan/pg");
+const sql_builder_1 = require("../utils/sql-builder");
+const version = '0.1.0';
+/**
+ * BulkUpsertPlugin
+ *
+ * Registers `bulkUpsertX` mutation fields for each resource with the
+ * `bulkUpsert` behavior. Uses INSERT ... ON CONFLICT DO UPDATE SET.
+ *
+ * Uses `RETURNING <pk_columns>` (not `RETURNING *`) + follow-up SELECT
+ * to respect column-level SELECT grants.
+ */
+exports.BulkUpsertPlugin = {
+    name: 'BulkUpsertPlugin',
+    version,
+    description: 'Adds bulk upsert (bulkUpsertX) mutations',
+    after: ['BulkTypesPlugin'],
+    schema: {
+        hooks: {
+            GraphQLObjectType_fields(fields, build, context) {
+                const { scope: { isRootMutation } } = context;
+                if (!isRootMutation)
+                    return fields;
+                const { inflection, sql, graphql: { GraphQLNonNull }, options: { bulkUpsert: enableUpsert = true, bulkMaxRows = 1000 } } = build;
+                if (!enableUpsert)
+                    return fields;
+                const pgRegistry = build.input.pgRegistry;
+                for (const [resourceName, resource] of Object.entries(pgRegistry.pgResources)) {
+                    if (resource.parameters)
+                        continue;
+                    if (!resource.codec.attributes)
+                        continue;
+                    if (resource.codec.polymorphism)
+                        continue;
+                    if (resource.codec.isAnonymous)
+                        continue;
+                    if (!resource.uniques?.length)
+                        continue;
+                    if (!build.behavior.pgResourceMatches(resource, 'bulkUpsert'))
+                        continue;
+                    const typeName = inflection.tableType(resource.codec);
+                    const fieldName = inflection.bulkUpsertField(resourceName);
+                    const inputTypeName = inflection.bulkUpsertInputType(typeName);
+                    const payloadTypeName = inflection.bulkUpsertPayloadType(typeName);
+                    const inputType = build.getTypeByName(inputTypeName);
+                    const payloadType = build.getTypeByName(payloadTypeName);
+                    if (!inputType || !payloadType)
+                        continue;
+                    const columnSpecs = [];
+                    const fieldToAttr = {};
+                    for (const [attrName, attr] of Object.entries(resource.codec.attributes)) {
+                        if (attr.extensions?.isInsertable === false)
+                            continue;
+                        const gqlFieldName = inflection.attribute({
+                            attributeName: attrName,
+                            codec: resource.codec
+                        });
+                        fieldToAttr[gqlFieldName] = attrName;
+                        columnSpecs.push({
+                            name: attrName,
+                            sqlType: sql.compile(attr.codec.sqlType).text
+                        });
+                    }
+                    // Collect unique constraint attributes for excluding from updateColumns
+                    const uniqueAttrs = new Set();
+                    for (const unique of resource.uniques) {
+                        for (const attr of unique.attributes) {
+                            uniqueAttrs.add(attr);
+                        }
+                    }
+                    // Extract primary key columns for RETURNING clause
+                    const primaryUnique = resource.uniques.find((u) => u.isPrimary) ?? resource.uniques[0];
+                    const pkColumns = primaryUnique.attributes;
+                    const compiledFrom = sql.compile(resource.from).text;
+                    // Capture for plan closure
+                    const executor = resource.executor;
+                    const maxRows = bulkMaxRows;
+                    fields = build.extend(fields, {
+                        [fieldName]: context.fieldWithHooks({ fieldName }, {
+                            description: `Bulk upsert rows into ${typeName}. Requires an ON CONFLICT constraint.`,
+                            type: payloadType,
+                            args: {
+                                input: {
+                                    type: new GraphQLNonNull(inputType)
+                                }
+                            },
+                            plan(_$root, args) {
+                                const $input = args.getRaw('input');
+                                const $result = (0, pg_1.sideEffectWithPgClient)(executor, $input, async (pgClient, input) => {
+                                    const values = input.values;
+                                    if (!values || !Array.isArray(values) || values.length === 0) {
+                                        return { affectedCount: 0, returning: [] };
+                                    }
+                                    if (values.length > maxRows) {
+                                        throw new Error(`Bulk upsert exceeds maximum of ${maxRows} rows (got ${values.length})`);
+                                    }
+                                    if (!input.onConflict?.constraint) {
+                                        throw new Error('bulkUpsert requires onConflict.constraint');
+                                    }
+                                    const rows = values.map((row) => {
+                                        const mapped = {};
+                                        for (const [key, val] of Object.entries(row)) {
+                                            const attrName = fieldToAttr[key];
+                                            if (attrName) {
+                                                mapped[attrName] = val;
+                                            }
+                                        }
+                                        return mapped;
+                                    });
+                                    // Determine which columns to update
+                                    let updateColumns;
+                                    if (input.onConflict.updateColumns &&
+                                        input.onConflict.updateColumns.length > 0) {
+                                        updateColumns = input.onConflict.updateColumns;
+                                    }
+                                    else {
+                                        // Default: all non-key columns
+                                        updateColumns = columnSpecs
+                                            .map((c) => c.name)
+                                            .filter((n) => !uniqueAttrs.has(n));
+                                    }
+                                    const batches = (0, sql_builder_1.buildBulkInsertSQL)(compiledFrom, columnSpecs, rows, pkColumns, {
+                                        conflictColumns: input.onConflict.constraint.split(','),
+                                        action: 'UPDATE',
+                                        updateColumns
+                                    });
+                                    let totalAffected = 0;
+                                    const allPkRows = [];
+                                    for (const batch of batches) {
+                                        const result = await pgClient.query(batch.text, batch.values);
+                                        totalAffected += result.rowCount ?? 0;
+                                        if (result.rows) {
+                                            allPkRows.push(...result.rows);
+                                        }
+                                    }
+                                    // Follow-up SELECT using PKs to respect column-level grants
+                                    let returning = [];
+                                    if (allPkRows.length > 0) {
+                                        const pkConditions = allPkRows.map((pkRow, rowIdx) => {
+                                            return pkColumns.map((col, colIdx) => {
+                                                const paramIdx = rowIdx * pkColumns.length + colIdx + 1;
+                                                return `"${col}" = $${paramIdx}`;
+                                            }).join(' AND ');
+                                        });
+                                        const whereClause = pkConditions.map((c) => `(${c})`).join(' OR ');
+                                        const selectParams = allPkRows.flatMap((pkRow) => pkColumns.map((col) => pkRow[col]));
+                                        const selectResult = await pgClient.query(`SELECT * FROM ${compiledFrom} WHERE ${whereClause}`, selectParams);
+                                        returning = selectResult.rows || [];
+                                    }
+                                    return {
+                                        affectedCount: totalAffected,
+                                        returning
+                                    };
+                                });
+                                return $result;
+                            }
+                        })
+                    }, `Adding bulk upsert field for ${typeName}`);
+                }
+                return fields;
+            }
+        }
+    }
+};

package/plugins/index.d.ts

@@ -0,0 +1,7 @@
+export { BulkDeletePlugin } from './BulkDeletePlugin';
+export { BulkInflectionPlugin } from './BulkInflectionPlugin';
+export { BulkInsertPlugin } from './BulkInsertPlugin';
+export { BulkRelationalPlugin } from './BulkRelationalPlugin';
+export { BulkTypesPlugin } from './BulkTypesPlugin';
+export { BulkUpdatePlugin } from './BulkUpdatePlugin';
+export { BulkUpsertPlugin } from './BulkUpsertPlugin';

package/plugins/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkUpsertPlugin = exports.BulkUpdatePlugin = exports.BulkTypesPlugin = exports.BulkRelationalPlugin = exports.BulkInsertPlugin = exports.BulkInflectionPlugin = exports.BulkDeletePlugin = void 0;
+var BulkDeletePlugin_1 = require("./BulkDeletePlugin");
+Object.defineProperty(exports, "BulkDeletePlugin", { enumerable: true, get: function () { return BulkDeletePlugin_1.BulkDeletePlugin; } });
+var BulkInflectionPlugin_1 = require("./BulkInflectionPlugin");
+Object.defineProperty(exports, "BulkInflectionPlugin", { enumerable: true, get: function () { return BulkInflectionPlugin_1.BulkInflectionPlugin; } });
+var BulkInsertPlugin_1 = require("./BulkInsertPlugin");
+Object.defineProperty(exports, "BulkInsertPlugin", { enumerable: true, get: function () { return BulkInsertPlugin_1.BulkInsertPlugin; } });
+var BulkRelationalPlugin_1 = require("./BulkRelationalPlugin");
+Object.defineProperty(exports, "BulkRelationalPlugin", { enumerable: true, get: function () { return BulkRelationalPlugin_1.BulkRelationalPlugin; } });
+var BulkTypesPlugin_1 = require("./BulkTypesPlugin");
+Object.defineProperty(exports, "BulkTypesPlugin", { enumerable: true, get: function () { return BulkTypesPlugin_1.BulkTypesPlugin; } });
+var BulkUpdatePlugin_1 = require("./BulkUpdatePlugin");
+Object.defineProperty(exports, "BulkUpdatePlugin", { enumerable: true, get: function () { return BulkUpdatePlugin_1.BulkUpdatePlugin; } });
+var BulkUpsertPlugin_1 = require("./BulkUpsertPlugin");
+Object.defineProperty(exports, "BulkUpsertPlugin", { enumerable: true, get: function () { return BulkUpsertPlugin_1.BulkUpsertPlugin; } });

package/preset.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bulk Mutations Preset
+ *
+ * Provides a convenient preset factory for including bulk mutations
+ * in PostGraphile v5.
+ *
+ * @example
+ * ```typescript
+ * import { BulkMutationPreset } from 'graphile-bulk-mutations';
+ *
+ * const preset = {
+ *   extends: [
+ *     BulkMutationPreset(),
+ *     // or with options:
+ *     BulkMutationPreset({
+ *       bulkNaming: 'pluralized',
+ *       bulkRelational: true,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+import './augmentations';
+import type { GraphileConfig } from 'graphile-config';
+import type { BulkMutationOptions } from './types';
+/**
+ * Creates a preset that includes the bulk mutation plugins with the given options.
+ *
+ * Behavior is OFF by default for all tables. Tables must opt in via smart tags:
+ *   COMMENT ON TABLE users IS E'@behavior +bulkInsert +bulkUpsert';
+ *
+ * The `enable_bulk` database setting must also be true for the plugin to load.
+ */
+export declare function BulkMutationPreset(options?: BulkMutationOptions): GraphileConfig.Preset;
+export default BulkMutationPreset;

package/preset.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Bulk Mutations Preset
+ *
+ * Provides a convenient preset factory for including bulk mutations
+ * in PostGraphile v5.
+ *
+ * @example
+ * ```typescript
+ * import { BulkMutationPreset } from 'graphile-bulk-mutations';
+ *
+ * const preset = {
+ *   extends: [
+ *     BulkMutationPreset(),
+ *     // or with options:
+ *     BulkMutationPreset({
+ *       bulkNaming: 'pluralized',
+ *       bulkRelational: true,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BulkMutationPreset = BulkMutationPreset;
+require("./augmentations");
+const plugins_1 = require("./plugins");
+/**
+ * Default schema options for bulk mutations.
+ */
+const defaultSchemaOptions = {
+    bulkNaming: 'bulk',
+    bulkInsert: true,
+    bulkUpsert: true,
+    bulkUpdate: true,
+    bulkDelete: true,
+    bulkRelational: false,
+    bulkReturning: true,
+    bulkMaxRows: 1000,
+    bulkMaxNestingDepth: 3,
+    bulkRequireWhere: true
+};
+/**
+ * Creates a preset that includes the bulk mutation plugins with the given options.
+ *
+ * Behavior is OFF by default for all tables. Tables must opt in via smart tags:
+ *   COMMENT ON TABLE users IS E'@behavior +bulkInsert +bulkUpsert';
+ *
+ * The `enable_bulk` database setting must also be true for the plugin to load.
+ */
+function BulkMutationPreset(options = {}) {
+    const mergedOptions = { ...defaultSchemaOptions, ...options };
+    const plugins = [
+        plugins_1.BulkInflectionPlugin,
+        plugins_1.BulkTypesPlugin
+    ];
+    if (mergedOptions.bulkInsert) {
+        plugins.push(plugins_1.BulkInsertPlugin);
+    }
+    if (mergedOptions.bulkUpsert) {
+        plugins.push(plugins_1.BulkUpsertPlugin);
+    }
+    if (mergedOptions.bulkUpdate) {
+        plugins.push(plugins_1.BulkUpdatePlugin);
+    }
+    if (mergedOptions.bulkDelete) {
+        plugins.push(plugins_1.BulkDeletePlugin);
+    }
+    if (mergedOptions.bulkRelational) {
+        plugins.push(plugins_1.BulkRelationalPlugin);
+    }
+    return {
+        plugins,
+        schema: mergedOptions
+    };
+}
+exports.default = BulkMutationPreset;

package/types.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Configuration options and shared types for graphile-bulk-mutations.
+ */
+/**
+ * Naming strategy for bulk mutation fields.
+ *
+ * - 'bulk': bulkCreateUser, bulkUpsertUser, bulkUpdateUser, bulkDeleteUser
+ * - 'pluralized': createUsers, upsertUsers, updateUsers, deleteUsers
+ * - 'many': createManyUsers, upsertManyUsers, updateManyUsers, deleteManyUsers
+ */
+export type BulkNamingStrategy = 'bulk' | 'pluralized' | 'many';
+/**
+ * Configuration options for the bulk mutations preset.
+ */
+export interface BulkMutationOptions {
+    /** Naming strategy for bulk mutation fields. Default: 'bulk' */
+    bulkNaming?: BulkNamingStrategy;
+    /** Enable bulk insert mutations. Default: true */
+    bulkInsert?: boolean;
+    /** Enable bulk upsert mutations. Default: true */
+    bulkUpsert?: boolean;
+    /** Enable bulk update mutations. Default: true */
+    bulkUpdate?: boolean;
+    /** Enable bulk delete mutations. Default: true */
+    bulkDelete?: boolean;
+    /** Enable relational/nested inserts on bulk create. Default: false */
+    bulkRelational?: boolean;
+    /** Include returning rows in payload. Default: true */
+    bulkReturning?: boolean;
+    /** Max items in values array (insert/upsert). Default: 1000 */
+    bulkMaxRows?: number;
+    /** Max nesting depth for relational inserts. Default: 3 */
+    bulkMaxNestingDepth?: number;
+    /** Require non-empty where on bulk update/delete. Default: true */
+    bulkRequireWhere?: boolean;
+}
+/**
+ * Max PostgreSQL parameters per query. Auto-batch splits at this limit.
+ */
+export declare const PG_MAX_PARAMS = 32000;

package/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Configuration options and shared types for graphile-bulk-mutations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PG_MAX_PARAMS = void 0;
+/**
+ * Max PostgreSQL parameters per query. Auto-batch splits at this limit.
+ */
+exports.PG_MAX_PARAMS = 32_000;

package/utils/index.d.ts

@@ -0,0 +1,4 @@
+export type { NestedRelationInfo } from './relations';
+export { discoverNestedRelations } from './relations';
+export type { ColumnSpec, InsertBatch } from './sql-builder';
+export { buildBulkDeleteSQL, buildBulkInsertSQL, buildBulkUpdateSQL } from './sql-builder';

package/utils/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildBulkUpdateSQL = exports.buildBulkInsertSQL = exports.buildBulkDeleteSQL = exports.discoverNestedRelations = void 0;
+var relations_1 = require("./relations");
+Object.defineProperty(exports, "discoverNestedRelations", { enumerable: true, get: function () { return relations_1.discoverNestedRelations; } });
+var sql_builder_1 = require("./sql-builder");
+Object.defineProperty(exports, "buildBulkDeleteSQL", { enumerable: true, get: function () { return sql_builder_1.buildBulkDeleteSQL; } });
+Object.defineProperty(exports, "buildBulkInsertSQL", { enumerable: true, get: function () { return sql_builder_1.buildBulkInsertSQL; } });
+Object.defineProperty(exports, "buildBulkUpdateSQL", { enumerable: true, get: function () { return sql_builder_1.buildBulkUpdateSQL; } });

package/utils/relations.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Relation discovery utilities for bulk relational/nested inserts.
+ *
+ * Inspects the PostGraphile registry to find "has many" (isReferencee)
+ * relations for a given resource. For each qualifying relation, computes
+ * column metadata needed to build child INSERT statements.
+ */
+import type { ColumnSpec } from './sql-builder';
+/**
+ * Metadata for a single "has many" relation eligible for nested inserts.
+ */
+export interface NestedRelationInfo {
+    /** Registry key of the relation (e.g. "productsByCategoryId") */
+    relationName: string;
+    /** GraphQL field name on the parent values item type */
+    fieldName: string;
+    /** The remote (child) PgResource */
+    remoteResource: any;
+    /** Registry key of the remote resource */
+    remoteResourceName: string;
+    /** PK columns on the parent that the FK references */
+    localAttributes: string[];
+    /** FK columns on the child table */
+    remoteAttributes: string[];
+    /** GraphQL field name → SQL column name for child */
+    childFieldToAttr: Record<string, string>;
+    /** Column specs for building child INSERT SQL */
+    childColumnSpecs: ColumnSpec[];
+    /** Compiled SQL table name for the child */
+    childCompiledFrom: string;
+    /** PK columns on the child table */
+    childPkColumns: string[];
+}
+/**
+ * Discover "has many" relations for a resource that qualify for nested
+ * inserts. A relation qualifies when:
+ *
+ * 1. isReferencee is true (the remote table references the local table)
+ * 2. isUnique is false (one-to-many, not one-to-one)
+ * 3. The remote resource is a regular table (has attributes, uniques, etc.)
+ */
+export declare function discoverNestedRelations(resource: any, pgRegistry: any, inflection: any, sql: any): NestedRelationInfo[];

package/utils/relations.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Relation discovery utilities for bulk relational/nested inserts.
+ *
+ * Inspects the PostGraphile registry to find "has many" (isReferencee)
+ * relations for a given resource. For each qualifying relation, computes
+ * column metadata needed to build child INSERT statements.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverNestedRelations = discoverNestedRelations;
+/**
+ * Discover "has many" relations for a resource that qualify for nested
+ * inserts. A relation qualifies when:
+ *
+ * 1. isReferencee is true (the remote table references the local table)
+ * 2. isUnique is false (one-to-many, not one-to-one)
+ * 3. The remote resource is a regular table (has attributes, uniques, etc.)
+ */
+function discoverNestedRelations(resource, pgRegistry, inflection, sql) {
+    const codecName = resource.codec.name;
+    const relations = pgRegistry.pgRelations[codecName];
+    if (!relations)
+        return [];
+    const result = [];
+    for (const [relationName, relation] of Object.entries(relations)) {
+        // Only reverse relations (child references parent)
+        if (!relation.isReferencee)
+            continue;
+        // Only one-to-many (skip one-to-one)
+        if (relation.isUnique)
+            continue;
+        const remoteResource = relation.remoteResource;
+        if (!remoteResource?.codec?.attributes)
+            continue;
+        if (remoteResource.codec.polymorphism)
+            continue;
+        if (remoteResource.codec.isAnonymous)
+            continue;
+        if (!remoteResource.uniques?.length)
+            continue;
+        // Build child column metadata (all insertable columns)
+        const childFieldToAttr = {};
+        const childColumnSpecs = [];
+        for (const [attrName, attr] of Object.entries(remoteResource.codec.attributes)) {
+            if (attr.extensions?.isInsertable === false)
+                continue;
+            const gqlFieldName = inflection.attribute({
+                attributeName: attrName,
+                codec: remoteResource.codec
+            });
+            childFieldToAttr[gqlFieldName] = attrName;
+            childColumnSpecs.push({
+                name: attrName,
+                sqlType: sql.compile(attr.codec.sqlType).text
+            });
+        }
+        // Find PK columns for child
+        const childPrimaryUnique = remoteResource.uniques.find((u) => u.isPrimary) ??
+            remoteResource.uniques[0];
+        const childPkColumns = [...childPrimaryUnique.attributes];
+        const childCompiledFrom = sql.compile(remoteResource.from).text;
+        // Find the registry key of the remote resource
+        let remoteResourceName = '';
+        for (const [name, res] of Object.entries(pgRegistry.pgResources)) {
+            if (res === remoteResource) {
+                remoteResourceName = name;
+                break;
+            }
+        }
+        // Derive a clean GraphQL field name from the remote resource name
+        const fieldName = inflection.camelCase(remoteResourceName);
+        result.push({
+            relationName,
+            fieldName,
+            remoteResource,
+            remoteResourceName,
+            localAttributes: [...relation.localAttributes],
+            remoteAttributes: [...relation.remoteAttributes],
+            childFieldToAttr,
+            childColumnSpecs,
+            childCompiledFrom,
+            childPkColumns
+        });
+    }
+    return result;
+}

package/utils/sql-builder.d.ts

@@ -0,0 +1,56 @@
+/**
+ * SQL builder utilities for bulk mutations.
+ *
+ * Provides parameterized SQL generation for VALUES clauses, ON CONFLICT
+ * clauses, and SET patches. Handles auto-batching when the parameter
+ * count would exceed PostgreSQL's 32K limit.
+ *
+ * IMPORTANT: All mutation queries use `RETURNING <pk_columns>` instead of
+ * `RETURNING *` to respect column-level SELECT grants. The caller is
+ * responsible for doing a follow-up SELECT using the returned PKs to
+ * resolve the full row through PostGraphile's grant-aware query pipeline.
+ * See: https://github.com/pyramation/graphile-column-privileges-mutations
+ */
+export interface ColumnSpec {
+    name: string;
+    sqlType: string;
+}
+export interface InsertBatch {
+    text: string;
+    values: unknown[];
+}
+/**
+ * Builds parameterized INSERT ... VALUES SQL with optional ON CONFLICT clause.
+ * Auto-splits into multiple batches when parameter count exceeds PG_MAX_PARAMS.
+ *
+ * Uses `RETURNING <returningColumns>` (typically primary key columns) instead
+ * of `RETURNING *` to avoid permission errors with column-level SELECT grants.
+ */
+export declare function buildBulkInsertSQL(tableName: string, columns: ColumnSpec[], rows: Record<string, unknown>[], returningColumns: string[], onConflict?: {
+    conflictColumns?: string[];
+    action: 'IGNORE';
+} | {
+    conflictColumns: string[];
+    action: 'UPDATE';
+    updateColumns?: string[];
+}): InsertBatch[];
+/**
+ * Builds a parameterized UPDATE ... SET ... WHERE SQL statement.
+ *
+ * Uses `RETURNING <returningColumns>` (typically primary key columns) instead
+ * of `RETURNING *` to avoid permission errors with column-level SELECT grants.
+ */
+export declare function buildBulkUpdateSQL(tableName: string, patch: Record<string, unknown>, columns: ColumnSpec[], returningColumns: string[], whereClause: string, whereParams: unknown[]): {
+    text: string;
+    values: unknown[];
+};
+/**
+ * Builds a parameterized DELETE ... WHERE SQL statement.
+ *
+ * Uses `RETURNING <returningColumns>` (typically primary key columns) instead
+ * of `RETURNING *` to avoid permission errors with column-level SELECT grants.
+ */
+export declare function buildBulkDeleteSQL(tableName: string, returningColumns: string[], whereClause: string, whereParams: unknown[]): {
+    text: string;
+    values: unknown[];
+};