docs: add --use-shadow-db documentation to test db command

Document the --use-shadow-db flag in the CLI man page with usage details, shadow port config, and CI guidance. Add a shadow-db example to examples.yaml and fix the stale shadow_port comment in testdata/config.toml to match the production template.

Author: lightstrike

docs/supabase/test/db.md

@@ -7,3 +7,16 @@ Requires the local development stack to be started by running `supabase start`.
 Runs `pg_prove` in a container with unit test files volume mounted from `supabase/tests` directory. The test file can be suffixed by either `.sql` or `.pg` extension.
 
 Since each test is wrapped in its own transaction, it will be individually rolled back regardless of success or failure.
+
+## Running tests against a shadow database
+
+Pass `--use-shadow-db` to run tests against an ephemeral shadow database instead of the local dev database. When this flag is set, the CLI:
+
+1. Spins up a temporary Postgres container
+2. Replays all local migrations from `supabase/migrations`
+3. Runs the pgTAP tests against this clean database
+4. Destroys the container when finished
+
+Your local dev database is never touched, making this ideal for CI pipelines and ensuring tests always run against a clean, migration-defined schema.
+
+The shadow database uses the `shadow_port` configured in `config.toml` (default `54320`) — the same port used by `db diff`. Because they share this port, you cannot run `db diff` and `db test --use-shadow-db` simultaneously.

docs/templates/examples.yaml

@@ -295,6 +295,17 @@ supabase-test-db:
       All tests successful.
       Files=2, Tests=2,  6 wallclock secs ( 0.03 usr  0.01 sys +  0.05 cusr  0.02 csys =  0.11 CPU)
       Result: PASS
+  - id: shadow-db
+    name: Run tests against an isolated shadow database
+    code: supabase test db --use-shadow-db
+    response: |
+      Creating shadow database...
+      Applying migration 20220810154537_create_employees_table.sql...
+      /tmp/supabase/tests/nested/order_test.pg .. ok
+      /tmp/supabase/tests/pet_test.sql .......... ok
+      All tests successful.
+      Files=2, Tests=2,  6 wallclock secs ( 0.03 usr  0.01 sys +  0.05 cusr  0.02 csys =  0.11 CPU)
+      Result: PASS
 # TODO: use actual cli response for sso commands
 supabase-sso-show:
   - id: basic-usage

pkg/config/testdata/config.toml

@@ -27,7 +27,7 @@ key_path = "../certs/my-key.pem"
 [db]
 # Port to use for the local database URL.
 port = 54322
-# Port used by db diff command to initialize the shadow database.
+# Port used by db diff and test db commands to initialize the shadow database.
 shadow_port = 54320
 # Maximum amount of time to wait for health check when starting the local database.
 health_timeout = "2m"