Skip to content

Add opt-in schema-scoped PostgreSQL introspection - #2

Draft
Zetazzz wants to merge 8 commits into
mainfrom
agent/scoped-introspection
Draft

Add opt-in schema-scoped PostgreSQL introspection#2
Zetazzz wants to merge 8 commits into
mainfrom
agent/scoped-introspection

Conversation

@Zetazzz

@Zetazzz Zetazzz commented Aug 19, 2026

Copy link
Copy Markdown

Summary

Add opt-in schema-scoped PostgreSQL introspection while preserving the exact
stock query and all existing parsing, caching, watch, registry, and entity-event
lifecycles.

  • configure scoped introspection per PostgreSQL service
  • take root schemas from pgService.schemas
  • retain transitive relation, function, type, index, inheritance, and extension
    dependencies
  • keep services on stock introspection unless explicitly enabled
  • fail on configuration for unknown services or incomplete scoped results

Ownership boundary

pg-introspection owns all PostgreSQL-specific behaviour:

  • scoped CTE and parameter construction
  • normalized schema, catalog-type, and capability-extension scope
  • SchemaScopedIntrospectionPlan, which carries both the query and validation
    scope
  • required-root and dependency-closure integrity validation
  • internal typeById lookup handling

graphile-build-pg has no separate scoped-introspection adapter module. The
small amount of Graphile-specific configuration, service validation, and
stock/scoped plan selection lives directly inside the existing
PgIntrospectionPlugin. It executes the selected query, validates the parsed
result with the same plan, and adds the PostgreSQL service name to validation
errors. It does not rebuild scope information or contain catalog traversal
logic.

This direct-integration design intentionally does not add a generic query hook
or an independent scoped plugin. The remaining trade-off is that the stock
plugin still knows the scoped configuration and selection policy.

Configuration

pgScopedIntrospection is keyed by service name. true uses defaults, false
keeps stock introspection, and an object accepts catalogTypes and
capabilityExtensions. Dependency schemas are discovered transitively; there
is no dependency-schema allowlist.

Validation

  • pg-introspection: package build passed; 46/46 tests passed
  • stock SQL golden hash remains
    c0ed817b912f78e1ea68c70d89ff4b7f9cb4c02d88112a69ac4109d5b996e4c5
  • owner tests cover normalized plans, missing roots, missing function
    dependencies, dangling column types, and internal lookup-retained types
  • graphile-build-pg: package build passed; 23/23 tests passed
  • configuration tests exercise the real gather/plugin path rather than
    exported adapter helpers
  • real PostgreSQL stock/scoped schema and runtime equivalence passed
  • dependency closure fixture covers cross-schema enum, domain, composite,
    range/multirange, functions, foreign keys, inheritance, ordinary indexes,
    and pg_trgm GIN/GiST indexes
  • affected ESLint and Prettier checks passed
  • git diff --check passed; no lockfile, default-behaviour, or format-only
    changes

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