Skip to main content
Version: 1.1.0
Last Updated: 2026-06-02
Status: DECISION RECORDED — Supabase Branching disabled for the development workflow; in-repo migration gates retained. See the Decision below. The spike Options/Recommendation are kept for reference if Branching-first promotion is revisited.

​
Decision (2026-06-02): disable Branching, keep the in-repo migration gates

Context. The Supabase Preview (Branching) GitHub check began failing on every migration-touching PR with out of shared memory (SQLSTATE 53200). Root cause: Branching’s reset/replay drops the whole schema in a single transaction, and this database now has ~1,300 public objects — past the preview branch’s max_locks_per_transaction lock-table budget on Micro compute. Resetting the branch reproduced the identical error, so it is not a stale-history issue. Findings.
  • Supabase Preview is not a required check anywhere — development does not require it and production is unprotected.
  • No CI job consumes preview-branch credentials (no supabase branches get, no POSTGRES_URL_NON_POOLING): the preview environment is unused; only its migrate check ran.
  • Branching here was always a deferred spike (this doc), scoped to production-promotion PRs, never operationalized.
  • Migration validation is already covered by in-repo gates that are stricter and run on our own runners.
Decision. Disable the Supabase Branching GitHub integration on the parent projects (aximlomrwfuhctxjhrsf / aximlomrwfuhctxjhrsf). Do not raise max_locks_per_transaction to chase it — that is per-project config on ephemeral Micro branches and would need re-chasing as the schema grows. Migration gates we keep (the real coverage): If preview environments are wanted later (the spike’s real goal — e.g. Vercel preview ↔ branch DB): re-enable Branching scoped to production-promotion PRs only, then raise max_locks_per_transaction (e.g. 64 → 512) on that project via supabase postgres-config update (requires a restart) so the reset can drop the full schema. Cleanup done. The orphaned failed HR-44 preview branch was deleted (disposable, no data).

​
Goal

Pick one supported integration path to:
  1. Resolve the preview branch (or migration apply status) for a prod → production PR on project aximlomrwfuhctxjhrsf.
  2. Surface “what will run in prod” in GitHub (check run body, PR comment, or artifact) without leaking secrets.

​
Option A — Supabase CLI in GitHub Actions (current baseline)

Auth: SUPABASE_ACCESS_TOKEN + supabase link --project-ref … --password … (already used in deploy workflows). Useful commands (verify flags with npx supabase <cmd> --help on the pinned CLI version):
  • supabase migration list --linked — local vs remote migration filenames (post-link in scripts/supabase/deploy-preflight.ts).
  • supabase db diff --linked — requires Docker on the runner; compares linked remote to local migration state (used for dev drift gate).
  • Branch-specific subcommands evolve by CLI version; re-check Supabase CLI reference before building “link to preview DB” automation.
Limits: CI may not get a stable per-PR preview connection string without Dashboard or Management API support; linking always targets the primary linked project, not ephemeral preview DBs.

​
Option B — Supabase Management API

  • Branches: Supabase API docs (branch list, merge status — endpoints and auth scopes change with product releases).
  • Typical need: personal access token / org token with permission to read branch metadata for project aximlomrwfuhctxjhrsf.
Limits: Rate limits; token storage in GitHub secrets; response shape must be pinned or schema-checked in CI.

​
Option C — GitHub Check + Dashboard (lowest automation)

Limits: No embedded live SQL diff from the preview DB without Option A/B.

​
Recommendation (until spike is re-run on current product)

  1. Require Supabase Preview check on production PRs (branch protection).
  2. Use git-based summaries + Dashboard links in CI (supabase-deploy-prod.yml).
  3. Re-spike Option B when implementing “real Branching diff” comments; keep db push reconcile documented as break-glass in deploy workflow inputs.