Database migrations
All seven migrations apply automatically during the upgrade. Two want something from you first: one needsWEBAPP_URL set if you use MCP OAuth, and one deserves a step of its own on large instances. So here
is the full list rather than a summary:
Build the response index before you upgrade
The migration creates its index onlyIF NOT EXISTS, so an index you build beforehand makes it a no-op. Built
with CONCURRENTLY, the index takes longer but never locks out writes, and the instance keeps running v5.3
while it builds. It does add disk and WAL load, so some writes can slow down while it runs. On a large table the
build can take a while, so run it from a session that survives a dropped connection, such as tmux or screen:
- One-Click / Docker Compose
- Kubernetes
From the directory that contains your
docker-compose.yml (formbricks for One-Click installs):psql as the user that owns the Formbricks
tables, connected directly to the primary rather than through a transaction-pooling connection pooler such as
PgBouncer. A pooler can run the SET and the CREATE on different server connections. Any other SQL client must
run the CREATE INDEX statement on its own, outside a transaction, because CONCURRENTLY cannot run inside one.
The two SET lines keep a timeout configured on the server, the database or your user from cancelling the
build: lock_timeout also limits how long the build waits for other transactions to finish. On PostgreSQL 17 or
later, if SHOW transaction_timeout; returns anything other than 0, add SET transaction_timeout = 0; before
the CREATE line too.
Then read the indisvalid result:
t: the index is ready. Upgrade as usual; the migration finds the index and skips the build.f: the index exists but is not usable yet. Do not upgrade over it, because the migration would see the name, skip the build, and leaveResponsewith an index PostgreSQL never uses. See below.- No row: the
CREATEfailed before it started, for example under the wrong user or on a read-only replica. Fix the error it printed and run the commands again. - No result at all:
psqllost its connection, or never got one, before the check ran. Read on underf.
f, or no result at all, means the build is still running or stopped part-way. If the CREATE printed an
error, it stopped: fix that cause (often a timeout), drop the index as below, and run the commands again. If your
session dropped instead, the build can still be running on the server, so first check, the same way and as the
same user as above:
indisvalid again. A waiting for writers phase is
waiting for transactions that wrote to Response. waiting for old snapshots waits for every older transaction
in this database that still holds a snapshot, on any table, so a long report or a pg_dump backup counts too.
Either way, current_locker_pid is the session it waits for, which you can look up in pg_stat_activity. If the
query returns nothing, the build has ended: check indisvalid again. t means it finished after all, so upgrade
as usual. Still f means it was interrupted: drop the index the same way, with the same SET lines first, since
a concurrent drop waits under lock_timeout too:
SET transaction_timeout = 0; here too if you needed it for the build. Then run the commands above again.
An extra index is harmless to v5.3, so building it early needs no rollback plan of its own.
Recovery across 5.4
The seven application migrations are additive from the perspective of v5.3. v5.3 reads none of the new columns and tables, and the twoNOT NULL columns added to existing tables both carry a database default, so a v5.3 instance keeps
writing to those tables exactly as before. Rolling the application images / Helm values back to v5.3 is
possible for these application changes without reversing the schema. Check Hub/dependency changes and new writes separately; the coordinated recovery procedure still applies.
Coming back forward has one catch, and only if accounts were created while you were rolled back.
Account.issuer does not exist in v5.3, so any account signed up or linked on that version is written
without one — and both issuer backfills are already recorded as applied, so rolling forward does not
re-run them. Better Auth 1.7 keys accounts on (issuer, accountId), which makes those rows invisible to
password sign-in and password reset. SSO accounts repair themselves on the next successful sign-in;
password accounts have no such path. If anyone signed up during the rollback window, re-run the repair
after rolling forward. This is the statement the repair_account_issuer migration runs, and it is
idempotent — it matches the providers v5.4 ships, so if you have since enabled one that is not listed
here, take the current mapping from that migration rather than this copy: