fix(db): retry the migration connection on transient slot exhaustion

[waleedlatif1]

Summary

Migrations fail their deploy whenever the production/staging database is momentarily at its connection cap. The migration opens its session on the first query (the advisory-lock acquire); if every non-superuser slot is taken, that connect throws 53300 — "remaining connection slots are reserved for roles with the SUPERUSER attribute" — and the whole migrate step errors out, even though the spike clears within seconds.

This adds a bounded connection retry before the lock is acquired.

Why this approach (investigated via PlanetScale)

The "give the migration role reserved slots" route is not available from here: on the prod cluster, max_connections (200), superuser_reserved_connections (3), and reserved_connections (0) are all context = postmaster — they only change with a database restart and are managed by PlanetScale's cluster sizing, not ALTER SYSTEM. The only online levers (capping the app role's connection limit, or granting pg_use_reserved_connections while reserved_connections = 0) are either ineffective or risk shifting the outage onto the app.

The saturation is transient (the DB sits around ~30 connections and briefly spikes), and the migration is a single short-lived session — so retrying the connect is the correct, low-risk fix.

Change

• connectWithRetry() runs SELECT 1 before acquireMigrationLock(), retrying 53300, the 08xxx connection_exception class, and the postgres-js transport codes with jittered backoff (10 attempts, ~90s ceiling). Non-transient errors (auth, bad host/db) still fail fast. Reuses the existing backoffWithJitter / getPostgresErrorCode helpers.

Durable capacity follow-up (platform, not in this PR)

The root cause is the app saturating ~all 200 slots at peak. Options for the owner to weigh: scale the cluster (raises max_connections), contain the app's pool / route through the pooler, or have PlanetScale set reserved_connections + grant the migration role pg_use_reserved_connections (and revoke it from the app role, which currently holds it). All require platform/cluster action.

Type of Change

• Bug fix (deploy reliability)

Testing

• biome + typecheck clean. Logic exercises on the next migration-bearing deploy; non-transient failures still surface immediately.

Checklist

• Self-reviewed
• No secrets added or exposed
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 26, 2026 7:17pm

[cursor]

PR Summary

Low Risk
Deploy-only reliability change in the migration script; no schema or app runtime behavior changes, with bounded retries and fail-fast on non-transient errors.

Overview
Deploy migrations no longer fail immediately when the database is briefly at its non-superuser connection limit (e.g. Postgres 53300).

packages/db/scripts/migrate.ts now calls connectWithRetry() before acquireMigrationLock(), probing the session with SELECT 1 and retrying transient failures—53300/53400, SQLSTATE 08xxx, and common postgres-js/network codes—with jittered backoff (up to 10 attempts, ~90s ceiling). Auth, bad config, and other non-transient errors still fail on the first throw. Existing backoffWithJitter / getPostgresErrorCode helpers are reused; migration DDL lock-timeout retries are unchanged.

^{Reviewed by Cursor Bugbot for commit ac8eeed. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds a bounded retry before database migrations acquire their lock. The main changes are:

• Adds transient connection error detection for Postgres and postgres-js transport codes.
• Runs a SELECT 1 connection check before taking the migration advisory lock.
• Retries transient connection failures with jittered backoff before failing the migrate step.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
packages/db/scripts/migrate.ts	Adds a pre-lock database connection retry for transient migration startup failures.

_{Reviews (2): Last reviewed commit: "ci: drop the migration paths-filter gate..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ac8eeed. Configure here.}