feat(db): add --use-shadow-db flag to test db command

[lightstrike]

Runs pgTAP tests against an ephemeral shadow database built from migrations, keeping the local dev database untouched. Reuses the existing CreateShadowDatabase/MigrateShadowDatabase machinery from db diff. Uses host networking so pg_prove can reach the shadow container via 127.0.0.1:<shadow_port>.

What kind of change does this PR introduce?

Feature — adds a new --use-shadow-db flag to both supabase db test and supabase test db.

What is the current behavior?

supabase db test (and supabase test db) always runs pgTAP tests against the local development database. This means:

• Tests that write data or alter schema pollute the dev environment.
• There is no built-in way to run tests against a clean, migration-derived database.
• Developers must manually reset their local DB after destructive test runs.

What is the new behavior?

When --use-shadow-db is passed, the CLI:

1. Spins up an ephemeral shadow container via CreateShadowDatabase (same machinery used by db diff).
2. Applies all migrations with MigrateShadowDatabase.
3. Overrides the pg_prove connection to point at the shadow container using host networking (127.0.0.1:<shadow_port>).
4. Runs pgTAP tests against the shadow database.
5. Tears down the shadow container when finished (via defer DockerRemove).

The local dev database is never touched.

Files changed (5):

• cmd/db.go — flag wiring on dbTestCmd
• cmd/test.go — mirror flag on testDbCmd
• internal/db/test/test.go — shadow DB lifecycle + host networking
• internal/db/test/test_test.go — updated call sites with false param
• pkg/config/templates/config.toml — updated shadow_port doc comment

Additional context

Prior art: ephemeral test databases in other frameworks

Using a dedicated, disposable database for test runs is a well-established pattern across mature frameworks:

Framework	Approach
Django	Automatically creates a test_<dbname> database, applies all migrations, runs tests inside transactions for per-test isolation, and destroys the DB afterward (docs).
Rails	Maintains a permanent test environment with its own database defined in database.yml. The schema is loaded from db/schema.rb (or structure.sql) before each test run, and each test is wrapped in a transaction that rolls back (guide).
Laravel	Supports SQLite :memory: databases or a dedicated MySQL/Postgres test DB. The RefreshDatabase trait migrates or transaction-wraps each test automatically (docs).
Prisma	Has an explicit shadow database concept — a temporary DB created/destroyed during prisma migrate dev to detect schema drift and validate migrations. For integration tests, Prisma recommends Docker-based ephemeral databases (docs).

The --use-shadow-db flag brings the Supabase CLI in line with this industry-standard practice: tests run against a clean, ephemeral database built from migrations, leaving development data untouched.

Why a flag (not the default)?

The flag is opt-in to ensure safe backwards compatibility — existing workflows that expect tests to run against the local dev database continue to work unchanged. Once the shadow DB path has been validated in real-world usage and deemed stable, we recommend making it the default behavior (with an opt-out flag if needed).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Summary by CodeRabbit

Release Notes

• New Features

  • Added --use-shadow-db flag to the test command, enabling tests to run against a temporary, isolated database created from your migrations.
  • Shadow database is automatically created, used for testing, and destroyed after tests complete, keeping your local development database untouched.
  • Ideal for CI environments to ensure tests run against a clean, migration-defined schema.

• Documentation

  • Added guidance on running tests against isolated shadow databases.

Walkthrough

This PR introduces shadow database support to the test command. A new --use-shadow-db flag enables users to run database tests against an isolated temporary PostgreSQL container rather than a live database. When enabled, the system creates a shadow database from migrations, waits for it to be healthy, migrates it, runs tests, and then removes the container. The feature keeps the local development database untouched and is suitable for CI environments.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as CLI Handler
    participant Runner as Test Runner
    participant Diff as Shadow DB Setup
    participant Health as Health Check
    participant Docker as Docker Container
    participant TestEngine as Test Engine

    User->>CLI: test db --use-shadow-db
    CLI->>Runner: Run(ctx, testFiles, config, useShadowDb=true, fs)
    
    rect rgba(100, 150, 200, 0.5)
    Note over Runner,Docker: Shadow Database Initialization
    Runner->>Diff: CreateShadowDatabase()
    Diff->>Docker: Create container
    Docker-->>Diff: Container created
    Diff-->>Runner: Shadow DB ready
    
    Runner->>Health: WaitForHealthyService()
    Health->>Docker: Check health status
    Docker-->>Health: Healthy
    Health-->>Runner: Service ready
    
    Runner->>Diff: MigrateShadowDatabase()
    Diff->>Docker: Apply migrations
    Docker-->>Diff: Migrations complete
    Diff-->>Runner: Migrations applied
    end
    
    rect rgba(200, 150, 100, 0.5)
    Note over Runner,TestEngine: Test Execution
    Runner->>TestEngine: Run tests against shadow DB
    TestEngine-->>Runner: Tests complete
    end
    
    rect rgba(150, 100, 200, 0.5)
    Note over Runner,Docker: Cleanup
    Runner->>Docker: DockerRemove()
    Docker-->>Runner: Container removed
    Runner-->>User: Results
    end

Loading

---

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

[coveralls]

Pull Request Test Coverage Report for Build 22208754227

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 5 of 32 (15.63%) changed or added relevant lines in 3 files are covered.
• 60 unchanged lines in 3 files lost coverage.
• Overall coverage decreased (-0.1%) to 61.657%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
cmd/test.go	0	1	0.0%
cmd/db.go	0	3	0.0%
internal/db/test/test.go	5	28	17.86%

Files with Coverage Reduction	New Missed Lines	%
cmd/db.go	1	0.0%
internal/utils/git.go	5	57.14%
internal/start/start.go	54	65.94%

Totals
Change from base Build 22142437948:	-0.1%
Covered Lines:	7709
Relevant Lines:	12503

---

💛 - Coveralls