feat: add relational/nested insert support and DataBulk node type for graphile-bulk-mutations

[pyramation]

Summary

Extends the graphile-bulk-mutations plugin (from PR #1140) with two major features:

1. Relational/Nested Inserts (BulkRelationalPlugin)

Supports nested create fields on bulk insert mutations, so you can create parent + child rows in a single GraphQL mutation:

mutation {
  bulkCreateOrders(input: {
    values: [{
      customerName: "Alice"
      orderItems: [
        { productName: "Widget", quantity: 2, unitPrice: "9.99" }
        { productName: "Gadget", quantity: 1, unitPrice: "19.99" }
      ]
    }]
  }) {
    affectedCount
    returning { id customerName }
  }
}

How it works:

• Discovers one-to-many FK relations via pgRegistry.pgRelations (isReferencee: true)
• Registers nested input types with FK columns excluded (auto-populated from parent PKs)
• Layered execution within a single transaction: parent INSERT → child INSERTs with FK auto-fill
• Validates that onConflict cannot coexist with nested inserts
• Opt-in via preset: bulkRelational: true

2. Returning Field Fix

Fixed type resolution for the returning field across all bulk mutation payloads:

• Uses pgSelectFromRecords + access from grafast/@dataplan/pg to properly wrap raw SQL results into PgSelectStep instances
• Previously returned raw JS objects that PostGraphile's plan system couldn't resolve fields from

3. DataBulk Node Type (node-type-registry)

New DataBulk node type for blueprint provisioning:

• Per-operation flags: insert, upsert, update, delete
• Auto-generates @behavior +bulkInsert +bulkUpsert etc. smart tags during provisioning
• Located at packages/node-type-registry/src/data/data-bulk.ts

Files Changed

• New: src/plugins/BulkRelationalPlugin.ts — relation discovery + nested input type registration
• New: src/utils/relations.ts — discoverNestedRelations() utility
• New: packages/node-type-registry/src/data/data-bulk.ts — DataBulk node type
• Modified: BulkInsertPlugin.ts — layered nested insert execution
• Modified: BulkTypesPlugin.ts — pgSelectFromRecords plan for returning field
• Modified: augmentations.ts, preset.ts, index.ts — new plugin/type exports

Review & Testing Checklist for Human

• Verify nested insert SQL correctness — Check that FK columns are properly auto-populated from parent PKs and child rows are correctly linked. Run the bulkCreateOrders mutation with nested orderItems against a real database.
• Test ON CONFLICT + nested insert validation — Confirm that passing both onConflict and nested children throws an appropriate error.
• Test returning field resolution — Verify that returning { id customerName } works correctly on all bulk mutation types (insert, upsert, update, delete), especially with column-level SELECT grants.
• Verify DataBulk node type — Check that DataBulk appears in the node type registry exports and has the correct parameter schema.
• Test empty nested arrays — Confirm that orderItems: [] is a no-op (no child inserts executed).

Notes

• Builds on PR feat: add graphile-bulk-mutations plugin #1140 (core bulk mutations plugin). This PR targets main and includes all changes from feat: add graphile-bulk-mutations plugin #1140 plus the relational/nested insert support and DataBulk node type.
• The blueprint-types.generated.ts file was NOT regenerated in this PR — running pnpm run generate:types in node-type-registry would pick up DataBulk, but the codegen has pre-existing issues with Check* types that are unrelated to this PR.
• Related planning issue: https://github.com/constructive-io/constructive-planning/issues/844

Link to Devin session: https://app.devin.ai/sessions/b5701e74c8b44bbf89db370f3323acf2
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​pgpm/​metaschema-schema@​0.18.0
	@​pgpm/​metaschema-modules@​0.21.1
	@​pgpm/​database-jobs@​0.18.0
	@​pgpm/​inflection@​0.18.0
	@​pgpm/​types@​0.18.0
	@​pgpm/​verify@​0.18.0
	@​launchql/​styled-email@​0.1.0
	@​pgpm/​services@​0.18.0
	@​jest/​test-sequencer@​30.3.0
	@​launchql/​mjml@​0.1.1
	@​constructive-io/​fetch@​1.0.0
	@​types/​babel__generator@​7.27.0
	@​agentic-kit/​ollama@​1.0.3
	@​inquirerer/​utils@​3.3.5
	@​inquirerer/​test@​1.4.1
	@​dataplan/​json@​1.0.0
	@​constructive-io/​noble-hashes@​0.2.1
	@​0no-co/​graphql.web@​1.2.0
	@​dataplan/​pg@​1.0.0
	@​aws-sdk/​lib-storage@​3.1009.0
	@​pgsql/​traverse@​17.2.5
	@​graphile-contrib/​pg-many-to-many@​2.0.0-rc.2
	@​testing-library/​react@​11.2.5
	@​tanstack/​react-query@​5.90.21
	@​testing-library/​jest-dom@​5.11.10
	@​graphile/​simplify-inflection@​8.0.0
	@​pgsql/​utils@​17.8.15
	@​aws-sdk/​client-s3@​3.1009.0
	@​aws-sdk/​s3-request-presigner@​3.1017.0
	@​playwright/​test@​1.58.2

View full report