Migrations
Migrations are SQL files that change the project database's structure. vastframe applies them for you and records which ones ran, so every deploy brings the database to the shape the code expects.
Ship migrations with your code
Put .sql files in db/migrations/ in the folder you deploy:
my-app/
├── db/
│ └── migrations/
│ ├── 001_purchase_requests.sql
│ └── 002_receipts.sql
├── package.json
└── server.js
On each deploy, before the new version starts:
- Files are applied in name order, as the database owner.
- Each file runs once. Applied migrations are recorded in the
tc.migrationstable by name (the file name without.sql), and skipped next time. - The build log shows
Migration 001_purchase_requests.sql: appliedoralready applied. - If a migration fails, the deploy fails with Database migration failed: … and production keeps serving the previous deployment.
Number your files (001_, 002_…) so the order is obvious.
db/migrations/002_receipts.sql
alter table purchase_requests add column if not exists receipt_path text;
Apply a named migration directly
Agents and scripts can apply a migration without a deploy:
- MCP:
apply_migrationwith anameandsql. - API:
POST /api/projects/:name/db/migrationswith{ "name": "003_add_cost_center", "sql": "..." }. - List what has run:
GET /api/projects/:name/db/migrations.
Named migrations are recorded in the same tc.migrations table, so a migration applied by an agent and later shipped in db/migrations/ under the same name runs only once.
Writing safe migrations
- Forward only. Rollback switches code, not the database. Prefer additive changes (new columns, new tables) that the previous version can live with.
- Idempotent where you can:
create table if not exists,add column if not exists. - Turn on RLS in the same migration that creates a table people reach from the browser, and add its policies.
- Keep data out of migrations unless it's reference data the app needs.
Related
Was this page helpful?