Waymaker
Databases

Changing Your Schema (Migrations)

Learn about Changing Your Schema (Migrations) in WaymakerOS.

SchemaMigrationsWrite path

Reading your data is easy and available everywhere. Changing the shape of your database — creating tables, adding columns, adding indexes — happens one way: through migrations. This is deliberate. It keeps every structural change ordered, tracked, and repeatable, so your database never changes by accident.

What a migration is

A migration is a named step containing the SQL that makes a change:

{ name: "001_create_customers", sql: "CREATE TABLE customers (id serial primary key, email text not null, created_at timestamptz default now())" }

You apply migrations as an ordered list. Waymaker runs them in order and records which ones have already run, so:

  • Re-running is safe. A migration that's already been applied is skipped, not run twice. You can send the whole list every time and only the new ones take effect.
  • Order is preserved. Later migrations can build on earlier ones.
  • History is tracked. Waymaker keeps a record of what's been applied, so you always know the current state.

How to run them

Migrations are applied through the Waymaker tools from your editor — the same place you build and deploy your app. Provide the ordered list of migrations for your app, and Waymaker applies any that haven't run yet.

A typical flow while building:

  1. Write your next migration (a name and the sql).
  2. Add it to the end of your migration list.
  3. Apply the list — only your new migration runs.
  4. Check the result in the Tables and Data tabs of the workspace.

Good practice

  • One change per migration. Small, focused migrations are easy to read, easy to reason about, and easy to trace if something looks wrong.
  • Never edit an applied migration. Once a migration has run, it's history. To change something, add a new migration that alters it — don't rewrite the old one.
  • Name them in order. A numeric prefix (001_, 002_) keeps the sequence obvious.
  • Seed data is a migration too. Inserting reference rows (a list of countries, default settings) is a perfectly good use of a migration.

Why not just run CREATE TABLE in the console?

Because the SQL Console is read-only by design. A one-off CREATE TABLE typed into a console leaves no record and can't be replayed on another copy of your database — so a preview branch or a fresh environment wouldn't have it. Migrations are the record, which is exactly why they're the only write path.

Next Steps