​

Migrations

​

Shape

use cratestack::Migration;

let migrations = vec![
    Migration {
        id: "20260101000000_create_accounts".to_owned(),
        description: "create accounts table".to_owned(),
        up: r#"
            CREATE TABLE accounts (
                id BIGINT PRIMARY KEY,
                balance NUMERIC NOT NULL DEFAULT 0,
                version BIGINT NOT NULL DEFAULT 0
            );
            CREATE INDEX accounts_balance_idx ON accounts (balance);
        "#.to_owned(),
        down: None,
    },
    Migration {
        id: "20260201000000_add_currency".to_owned(),
        description: "add currency to accounts".to_owned(),
        up: "ALTER TABLE accounts ADD COLUMN currency TEXT NOT NULL DEFAULT 'USD';".to_owned(),
        down: None,
    },
];

1. id is sortable — YYYYMMDDHHMMSS_<slug> is canonical
2. description is short and human-readable
3. up is the SQL applied forward, sent as a single batch to Postgres and run inside one transaction
4. down is recorded but never executed by the runner — irreversible-by-default is the safe banking posture

​

Running

use cratestack::{apply_pending, status, ensure_migrations_table};

ensure_migrations_table(&pool).await?;
let applied: Vec<String> = apply_pending(&pool, &migrations).await?;

1. compares each input migration against cratestack_migrations
2. skips already-applied rows whose checksum matches
3. aborts with CratestackError::Internal if an applied row’s checksum has drifted
4. for each pending row: opens a transaction, sends the entire up script in one batch via sqlx::raw_sql(&migration.up), inserts the record into cratestack_migrations, commits

​

Checksum drift

migration `20260101000000_create_accounts` is recorded as applied but its
SQL has changed; resolve drift before continuing

​

Inspecting state

pub struct MigrationState {
    pub id: String,
    pub status: MigrationStatus,
}

pub enum MigrationStatus {
    Pending,
    Applied,
    ChecksumMismatch,
}

​

Multi-statement scripts

CREATE TABLE transfers (
    id BIGINT PRIMARY KEY,
    amount BIGINT NOT NULL,
    status TEXT NOT NULL
);
CREATE INDEX transfers_status_idx ON transfers (status);
INSERT INTO transfers_status_lookup (key, label)
    VALUES ('pending', 'Pending'), ('settled', 'Settled');

​

What the runner is not

1. not a down/rollback engine — down is recorded for audit but never run
2. not a parallel-applier — migrations are sequential and serialized through the tracking table
3. not a long-running-migration coordinator — banks executing a 6-hour ALTER TABLE use their own backfill tooling and record the migration as a no-op when the backfill is done

​

Generating migrations from .cstack

• cratestack migrate diff — offline. Diffs the current .cstack against migrations/<backend>/schema.snapshot.json and writes a new migration directory.
• cratestack migrate baseline — adopts a database that already has tables and no prior cratestack migration history, by introspecting it directly instead of assuming an empty starting point. See Adopting an Existing Database for a full walkthrough against a real database.

• cratestack migrate verify — deferred. Intended as a CI gate that replays the full migration history against an ephemeral DB and checks the result matches the snapshot; blocked on ephemeral-DB spawning support.
• cratestack migrate drift — deferred. Intended as a read-only ops tool reporting differences between the committed snapshot and a live database, without writing anything. Distinct from migrate baseline above, which introspects a live database too but only for the one-time act of adoption — it writes a new snapshot and a cratestack_migrations row, where migrate drift would only report.

​

Table naming, pluralization, and @@rename

model Category {
  id    Int    @id
  label String

  @@rename(from = "categorys")
}

ALTER TABLE categorys RENAME TO categories;

​

Why this matters right now: the y -> ies pluralization fix

​

Foreign keys, referential actions, and composite uniqueness

model Application {
  id       String @id
  tenantId String
  tenant   Tenant @relation(fields: [tenantId], references: [id], onDelete: Cascade, onUpdate: Restrict)
}

ALTER TABLE applications ADD CONSTRAINT applications_tenant_id_fkey
  FOREIGN KEY (tenant_id) REFERENCES tenants (id) ON DELETE CASCADE ON UPDATE RESTRICT;

1. onDelete/onUpdate can only be declared on the relation’s owning side — the List-typed “many” side has no physical column of its own to attach a constraint to.
2. onDelete: SetNull / onUpdate: SetNull requires the local foreign-key field to be optional (tenantId String?); SetDefault requires it to declare @default(...).

model Application {
  id          String @id
  tenantId    String
  name        String
  environment String

  @@unique([tenantId, name, environment])
}

CREATE UNIQUE INDEX applications_tenant_id_name_environment_key
  ON applications (tenant_id, name, environment);

​

Schema

CREATE TABLE cratestack_migrations (
    id TEXT PRIMARY KEY,
    description TEXT NOT NULL,
    checksum BYTEA NOT NULL,
    applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

​

Read Next

1. Adopting an Existing Database — cratestack migrate baseline, a full walkthrough of pointing this migration runner at a real, already-populated database for the first time
2. ADR 0004: Schema diff and migration generation — how .cstack changes turn into the SQL this runner applies
3. Schema diff (CLI) — cratestack diff checks the same two .cstack versions for wire-contract breaking changes, independent of the DB migration this page describes
4. Composite keys — @@id([...]) / @@unique([...]), the multi-column constraints this generator emits
5. Field attributes — full @relation/onDelete/onUpdate/@@unique syntax reference
6. Audit log — banks frequently land @@audit retroactively via a migration
7. Soft delete — deleted_at columns are typically added by a follow-up migration on existing models