Migrations
What you’ll learn
- What a migration is, in plain words
- How Strutvane creates migrations from your models
- How it protects you from losing data by accident
What is a migration?
Section titled “What is a migration?”Your database has a shape: which tables exist and which columns they have. When you change your models, the database shape must change too.
A migration is a small file that says “change the database like this”. For example:
CREATE TABLE products ( id uuid PRIMARY KEY, name varchar(255) NOT NULL, price numeric(10, 2) NOT NULL);Think of migrations as renovation instructions for a house. Each one is a step: “add a window here”, “build a new room”. Anyone who follows the same instructions in order ends up with the same house. That’s how your laptop, your teammate’s laptop and the production server all end up with the same database.
How Strutvane does it
Section titled “How Strutvane does it”-
You change a model, for example by adding a
skufield toProduct. -
You run the migrate command:
Terminal window pnpm sv migrate -
Strutvane compares your models with the last recorded state, writes a migration file and applies it:
◇ Comparing models (postgres)…│ + alter table products add column sku varchar(64)◇ Wrote database/migrations/20261113143012_auto.sql✔ Applied 1 migrationGive the file a better name with
--name:pnpm sv migrate --name add_sku_to_products. -
The migration file is saved in your project. You commit it to Git like any other code, so teammates and servers apply exactly the same change.
Safety features
Section titled “Safety features”| Situation | What Strutvane does |
|---|---|
| A change could delete data (dropping a column, removing an enum value, making a column required) | Stops with a clear error. Run it again with --allow-destructive once you’re sure. |
A field looks renamed (phone → phoneNumber) |
Stops and asks you to decide: --rename customers.phone=phone_number for a rename, or --separate phone=phone_number for a delete-plus-add. It never guesses, because guessing wrong loses data. Your answer is recorded in the migration file. |
| Someone edits a migration that’s already been applied | Stops and names the file. Applied migrations must never change. |
| Several migrations are pending | They all apply together, or none do. A failure halfway leaves the database as it was. |
| Two servers try to migrate at the same time | Only one goes ahead (on PostgreSQL, a database lock). The second sees the first one’s work. |
Preview without changing anything
Section titled “Preview without changing anything”pnpm sv migrate --pretendThis writes the migration file so you can read the SQL, but applies nothing to the database.
Handy commands
Section titled “Handy commands”| Command | What it does |
|---|---|
pnpm sv migrate |
Create and apply migrations from your models |
pnpm sv migrate:status |
List applied, pending and changed migrations |
pnpm sv db:seed |
Fill the database with seed data (--class InvoiceSeeder for one seeder) |
pnpm sv migrate:rollback |
Planned: undo the last batch of migrations |
pnpm sv migrate:fresh --seed |
Planned, development only: wipe the database, rebuild it and fill it with fake data |
pnpm sv db:pull |
Planned: read an existing database and write models for it |
When you need a hand-written migration
Section titled “When you need a hand-written migration”Sometimes you need to move data, not just change the shape. For example: “copy every old phone value into the new phoneNumber column”. For that, create a hand-written SQL migration:
pnpm sv make:migration copy_phone_numbers --sql-- copy_phone_numbers-- Hand-written migration. Keep "up" and "down" sections; run with `sv migrate`.
-- upUPDATE customers SET phone_number = phone WHERE phone_number IS NULL;
-- downpnpm sv migrate applies it in order with the generated ones.