Migration Index
All schema migrations live in server/migrations/ as plain SQL files.
sqlx applies them at server startup in
ascending numeric-version order (it parses each filename’s integer prefix as the
migration version); a migration is never re-applied once its checksum is recorded.
File naming
Section titled “File naming”NNN_description.sqlNNN is a zero-padded decimal integer. sqlx parses this prefix as an i64 version
and applies migrations in ascending order of that integer value (zero-padding keeps
the on-disk filename order matching, but the authoritative ordering is the parsed
integer, not the string).
The shared-namespace rule
Section titled “The shared-namespace rule”Migration numbers form a shared namespace across all parallel worktrees and
branches. Two PRs that each add migration 170 will conflict on merge.
The highest sequential migration on main is 226 as of 2026-06-15.
A new migration goes to 227 or higher.
To add a migration, see the Add a database migration how-to.
Reading the sequence
Section titled “Reading the sequence”The sequence is mostly contiguous but has documented gaps and two numbering patterns to be aware of.
Some number ranges were reserved or intentionally left open:
| Gap | Reason |
|---|---|
| 76–80 | Reserved/unused |
| 121, 128–129 | Unused slots between parallel feature branches |
| 137–139 | Reserved during org-tenancy work |
| 161–163 | Reserved during credential-scope consolidation |
sqlx tracks migrations by filename, so gaps are harmless — it does not require a contiguous sequence.
Out-of-sequence files
Section titled “Out-of-sequence files”Two migrations carry an extra issue-number word after their numeric prefix instead of a plain feature description:
| File | Purpose |
|---|---|
100_issue_207_runs_filter_indexes.sql |
Covering indexes for runs filter queries (Issue #207) |
118_issue224_audit_indexes.sql |
Covering indexes for audit queries (Issue #224) |
Despite the longer names these files sort and apply in their normal numeric
positions — 100 right after 099, and 118 between 117 and 119. They
do not run last; the extra word is simply a naming convention that embeds the
originating issue number for traceability.
Key migration milestones
Section titled “Key migration milestones”The table below maps significant schema epochs to their migration numbers.
Consult server/migrations/ for the exact SQL.
| Range | Feature area |
|---|---|
| 001–044 | Core schema, auth, OAuth, scheduling |
| 045–075 | Workflows, runs, resources, apps, billing |
| 076–119 | Marketplace catalog, runners, MCP, Telegram, agent profiles |
| 120–134 | Auth overhaul (email verification, magic link, BYO-OIDC, TOTP), chat platform accounts, repo-sync auto-push |
| 140–153 | Organization tenancy — orgs, seats, invites, notifications, BYO-OIDC org re-key |
| 154–160 | Marketplace connector nodes, per-kind fees, credential org scope, item reviews/ratings, connector runner dispatch |
| 164–165 | Credential scope consolidation (locked + org RLS, per-org tracker OAuth client) |
| 166–169 | Auto-developer backlog schema, agent-profile execution mode, tenant rename teams → workspaces (ADR 0040) |
| 170–173 | Repo-sync resource kind/sync-mode, app deployment subdomain + API token (ADR 0041 / Issue #410) |
| 174–187 | Marketplace ledger uniqueness, credential scope hardening, budget reservations, MCP cap reservations, FinTS/Seafile resource kinds |
| 188–207 | Archival flags, resource last-test, performance indexes (audit events, tasks, runs, sessions), task-outcome tokens |
| 208–220 | Autonomous Delivery Engine (ADR 0045) — foundation, spend ledger, backlog/quiet-hours/automations, provider quota, routing learning, task-tool approvals, autonomy slider, safety/seat-overage/operability/governor workstreams, runs event-sequence counter |
| 221–226 | v0.2.2 — engine digest config, per-arm automation workflow id, workspace system-LLM credential pin, legacy auto-developer cutover, repo-sync memory kind, backlog item scope |
Tooling
Section titled “Tooling”sqlx runs migrations automatically on server startup. There is no separate migration CLI invocation in normal development — start the server against a fresh database and all pending migrations apply.
For test databases the harness clones a pre-migrated template (supacloud_test_template)
so individual test runs do not re-apply the full migration chain.
See server/tests/ for the test support helpers.