Skip to content

Add CNC-owned scoped PostgreSQL introspection - #1719

Draft
Zetazzz wants to merge 1 commit into
test/performance-harness-corefrom
feat/cnc-scoped-introspection
Draft

Add CNC-owned scoped PostgreSQL introspection#1719
Zetazzz wants to merge 1 commit into
test/performance-harness-corefrom
feat/cnc-scoped-introspection

Conversation

@Zetazzz

@Zetazzz Zetazzz commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Stack

  1. Add a reusable Graphile performance harness #1716 — generic performance harness
  2. This PR — CNC-owned scoped introspection
  3. build-state retirement (follow-up)

Base: test/performance-harness-core

Architecture boundary

This PR implements schema-scoped PostgreSQL introspection entirely on the CNC side.

  • ConstructivePgIntrospectionPlugin is a replacement built from the public PgIntrospectionPlugin export.
  • The replacement creates new plugin/gather/helper objects; it does not mutate Graphile's exported singleton.
  • ScopedIntrospectionPreset disables the upstream plugin and installs the replacement atomically.
  • ConstructivePreset opts into that preset explicitly.
  • Stock-only configuration delegates to the upstream implementation.
  • Mixed stock/scoped services are supported per service.

The only pnpm patches are:

  • pg-introspection@1.0.1: parameterized scoped query generation and direct range lookup.
  • @dataplan/pg@1.1.1: exact introspection-client destruction support.

There is deliberately no graphile-build-pg patch and no build-state retirement behavior in this PR.

Lifecycle and safety

  • Strict schema-name validation and namespace policies.
  • Optional catalog-type dependency closure with deterministic failure for unsatisfied closure.
  • Reuses upstream cache, watch invalidation, gather-state and hook lifecycle semantics.
  • Concurrent gathers share the same in-flight state.
  • Failed introspection is not cached.
  • Raw scoped introspection text is released after parse.
  • Scoped clients are destroyed exactly; caller-owned clients cannot be destroyed.
  • Runtime schema behavior is verified after introspection.

About 178 lines (including local boundary comments) mirror/rewrite upstream private gather/cache flow because the public plugin does not expose that control surface. This is intentionally isolated in one file so it can be deleted when upstream progressive introspection is available.

Harness extension

Extends #1716 with fresh-process stock and scoped cases without loading ConstructivePreset. It preserves schema-hash, runtime-validation, PID, lifecycle and secret-redaction output contracts.

Validation

  • graphile-settings: 12 suites / 112 tests passed.
  • @constructive-io/perf-harness: 6 suites / 8 tests passed.
  • CJS and ESM builds passed for both affected packages (in dependency order).
  • ESLint passed with zero errors; four existing unrelated warnings remain in graphile-settings.
  • Prettier and git diff --check passed.
  • pnpm install --frozen-lockfile --offline passed.
  • Real PostgreSQL 18.4 stock/scoped smoke passed in unique fresh processes:
    • distinct PIDs: 90201, 90202
    • identical schema SHA-256: 3b9dab5243611a57da1c0721ea3bc1aba455051124e43549e3c326178b3e97c1
    • runtime verification passed for both
    • report contained no database URL or credentials

Upstream migration

This is a CNC-owned interim implementation. Once Graphile progressive introspection provides equivalent behavior, remove the replacement plugin and the two scoped-introspection patches while keeping the harness as the migration/equivalence gate.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant