Skip to main content

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:

  1. Files are applied in name order, as the database owner.
  2. Each file runs once. Applied migrations are recorded in the tc.migrations table by name (the file name without .sql), and skipped next time.
  3. The build log shows Migration 001_purchase_requests.sql: applied or already applied.
  4. 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_migration with a name and sql.
  • API: POST /api/projects/:name/db/migrations with { "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.
Was this page helpful?