test: validate Supabase compatibility and add a test harness

[aparajon]

Why

Validate that pg-sprite can work with Supabase and establish a repeatable test harness. As pg-sprite evolves, this harness will help us verify and expand Supabase support.

The initial coverage exercises supported schema changes, checks that unsupported changes are safely refused, and verifies that Supabase's access policies, API, and live subscriptions keep working.

What

• Verify supported schema changes against real local Supabase services, including tenant isolation and Realtime delivery
• Verify unsupported table rewrites are refused before changing schema or data
• Exercise failure paths and check exactly what remains in the database
• Make these checks required in CI so compatibility is tested as pg-sprite grows
• Give users and coding agents a setup, preview, apply, and verification walkthrough, with support claims linked to tests

How

Go tests call pg-sprite's public APIs against pinned Supabase PostgreSQL, Auth, PostgREST, Supavisor, and Realtime containers. Each DDL case has its own named test with the complete SQL visible. Tests inspect database state and exercise application access, rather than relying only on a successful verdict.

Risk

No production engine behavior changes. This validates the local fixture; hosted Supabase projects and successful copy-and-swap changes still need validation.

Testing

Ran the guide's CLI preview, apply, and verification commands against local Supabase. The results matched the documented examples.

Bigger picture

Extend the harness as new engine capabilities land, so each expansion of Supabase support comes with automated evidence. Hosted validation and broader declarative workflows are the next milestones.

Generated with Codex (GPT-6)

[JashLal]

🤖 Automated review

This is a well-scoped, test-only PR that validates pg-sprite against Supabase and establishes a repeatable harness. No production engine behavior changes.

What it does

• Adds a pinned, localhost-only compose fixture (compose/supabase.yml) with the real Supabase Postgres 17.6 image plus opt-in services/realtime profiles (PostgREST, Supavisor, GoTrue, Realtime), all digest-pinned.
• Adds an integration/supabase Go suite: DDL matrix (supported changes execute, unsupported rewrites are refused before touching schema/data), failure-path state inspection, RLS/tenant-isolation continuity, PostgREST schema-cache refresh, Supavisor session vs. transaction pooling boundaries, and Realtime event delivery during a column add + concurrent index build under live writes.
• Makes the checks required in CI, and documents the walkthrough in docs/supabase.md with support claims linked to tests.

Strengths

• Tests assert observable behavior, not just verdicts: e.g. TestNativeChangesPreserveRowSecurity verifies actual tenant visibility via SET LOCAL ROLE, correctly noting an owner-only SELECT can't prove RLS enforcement.
• The transaction-pooling test requires the typed ErrNoSessionAffinity error, so an unrelated connection failure can't pass it — nice guard.
• Good iteration history: the interim Python/Node scripts were consolidated into Go tests (patches 04), reducing toolchain requirements to Go + Docker.
• Honest boundary documentation: hosted projects, TLS, Auth signup/login, and copy-and-swap remain explicitly out of scope rather than implied-supported.
• Disposable credentials are clearly marked and the fixture binds only to 127.0.0.1; fixed local DSNs prevent pointing destructive tests at a real project.

Observations / minor suggestions (non-blocking)

• The Realtime test's dependence on restarting the Realtime service before subscribing (publication OID caching) is well-documented, but it's the most timing-sensitive piece — worth watching for CI flakiness, especially the 30s convergence windows and 100k-row seed.
• The required CI job pulls several pinned images; consider a cache or a periodic image-refresh chore so digest pins don't rot silently.
• compose/supabase/pooler.exs is adapted from an Apache-2.0 upstream file and attributed — good; keep the version reference in sync when bumping Supavisor.

Approving — test-only change with clear boundaries and strong evidence discipline.

[JashLal]

🤖 Approved by automated review.

[aparajon]

🤖 Addressed the maintenance suggestions:

• Realtime reliability: linked the repository’s existing flake-handling rules: investigate the failure, fix the root cause, and verify the fix with scripts/test-flaky.sh. Normal CI runs each test once, without automatic retries or extra repetitions. Timeouts are unchanged. This adds guidance; it does not claim to fix a newly identified flake. (Changes, remove repetitions)
• Image maintenance: documented a monthly maintainer review of upstream releases, version/digest pins, compatibility results, and support documentation. This is a manual procedure. (Changes)
• Pooler provenance: added an immutable upstream source link and the validated Supavisor version, with instructions to review both when upgrading. (Changes)

[aparajon]

🤖 Addressed the maintenance suggestions:

• Realtime reliability: linked the repository’s existing flake-handling rules: investigate the failure, fix the root cause, and verify the fix with scripts/test-flaky.sh. Normal CI runs each test once, without automatic retries or extra repetitions. Timeouts are unchanged. This adds guidance; it does not claim to fix a newly identified flake. (Changes, remove repetitions)
• Image maintenance: replaced the monthly manual chore with an AGENTS.md instruction to check upstream releases during Supabase work, flag major-version drift, and propose a separate update PR with compatibility risks and validation. (Changes)
• Pooler provenance: added an immutable upstream source link and the validated Supavisor version, with instructions to review both when upgrading. (Changes)

[aparajon]

🤖 Updated the image-maintenance approach: instead of a monthly manual chore, AGENTS.md now directs agents working on Supabase fixtures, tests, or docs to check upstream releases, explicitly flag major-version drift, and propose a separate update PR.

The proposal should include current and candidate versions, release-note links, compatibility risks, and required validation. Image upgrades retain version/digest pins and update the pooler attribution and tested-version documentation together. If upstream release information is unavailable, the agent must report the check as incomplete.

Changes: 3021f68 and 74aa994