feat: add pg-schema-diff namespace FK PoC

[turip]

Summary

• generate additive composite namespace foreign keys from existing Ent foreign-key descriptors
• add a pg-schema-diff library command that compares migration history with Ent, the namespace-FK overlay, and Ent-managed views in disposable databases
• replay-validate the plan and render migration-style SQL without public schema qualification or the schema_om state table
• add Make targets, generated SQL, focused tests, and usage documentation

Why

Existing ID-only foreign keys do not enforce that the referencing and referenced rows belong to the same namespace. This allowed billing configuration to reference resources from another namespace. The POC explores an open-source workflow for deriving additive (namespace, foreign_id) -> (namespace, id) constraints without Atlas Pro.

POC limitations

• the command emits a review-only plan and does not add a versioned up/down migration or update atlas.sum
• the configured development PostgreSQL role must be able to create disposable databases
• the current generated plan also surfaces pre-existing Ent naming drift: 40 foreign keys and 7 indexes are replaced because historical PostgreSQL-truncated names differ from current hash-shortened Ent names

Validation

• make check-namespace-fks
• go test ./tools/migrate/pgschemadiff ./tools/migrate/cmd/pgschemadiff ./tools/migrate/viewgen ./tools/migrate/namespacefks ./tools/migrate/cmd/namespacefks
• direnv exec . make lint-go-fast
• PG_SCHEMA_DIFF_OUTPUT=/tmp/openmeter-pgschema-diff-pr.sql direnv exec . make pgschema-diff-poc
  • replay validation passed
  • emitted all 13 namespace guard constraints
  • emitted no public schema qualification, schema_om, existing check constraints, or spurious table creation

Greptile Summary

The PR adds a proof-of-concept migration workflow that derives namespace-aware composite foreign keys from Ent metadata and uses disposable PostgreSQL databases to compare migration history with the desired schema.

• Adds namespace foreign-key generation, checked-in generated SQL, and focused database tests.
• Adds pg-schema-diff planning, replay validation, migration-style SQL rendering, CLI commands, Make targets, and documentation.
• Extends view generation with destructive recreation support for disposable desired-state databases.

Confidence Score: 5/5

The PR appears safe to merge, with no concrete blocking or independently actionable non-blocking defects identified.

The generated namespace constraints preserve existing relationship lifecycle behavior, and the schema-diff workflow operates on disposable databases with replay validation before rendering its review-only SQL.

Important Files Changed

Filename	Overview
tools/migrate/namespacefks/generator.go	Generates deterministic composite namespace foreign keys and supporting unique indexes from validated Ent descriptors.
tools/migrate/pgschemadiff/pgschemadiff.go	Builds disposable current and desired databases, generates and validates their schema plan, and renders migration-style SQL.
tools/migrate/viewgen/viewgen.go	Refactors view loading and adds reverse-order drop/recreate SQL for disposable desired-state reconciliation.
tools/migrate/schema/namespace_foreign_keys.sql	Contains the generated namespace guard overlay for thirteen billing relationships and one supporting unique index.
tools/migrate/cmd/pgschemadiff/main.go	Exposes schema planning and replay validation through a developer-oriented CLI with configurable output.
go.mod	Adds pg-schema-diff and its transitive PostgreSQL dependencies for the new migration tool.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  M[Migration history] --> C[Current disposable database]
  M --> D[Desired disposable database]
  E[Ent schema] --> D
  F[Generated namespace FKs] --> D
  V[Ent-managed views] --> D
  C --> P[pg-schema-diff plan]
  D --> P
  P --> R[Replay validation]
  R --> S[Migration-style SQL]

Loading

_{Reviews (1): Last reviewed commit: "feat: add pg-schema-diff namespace FK Po..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Data layer: ent schema, migrations, and generated client

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: edf9fe6c-dcb1-461f-803f-02a93cb18dba

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[aikido-pr-checks]

2 Open source vulnerabilities detected - critical severity
Aikido detected 2 vulnerabilities across 2 packages, it includes 1 critical and 1 high vulnerabilities.

Details

Remediation:

• github.com/jackc/pgx/v4 — 1 CVE (critical) — no fix version available
• github.com/jackc/pgproto3/v2 — 1 CVE (high) — no fix version available

_{Reply @AikidoSec ignore: [REASON] to ignore this issue.
More info}