Migrations

KalamDB projects store schema history under kalam/migrations/ (configured in [migrations].dir). The CLI diffs schema.sql against a local baseline, maintains a working _draft.sql, and tracks applied migrations on the server per namespace.

Migration files

Draft files are not applied to production deployments until sealed into a numbered migration.

Typical development flow

1# 1. Edit schema.sql2vim schema.sql3 4# 2. Let kalam dev detect changes (or run pipeline manually)5kalam dev6 7# 3. When prompted, apply the draft — or seal and migrate explicitly:8kalam migration seal9kalam db migrate10 11# 4. Check state12kalam migration status

During kalam dev, edits to schema.sql update _draft.sql automatically. Numbered migrations apply on startup and after each watched change; the draft waits for your confirmation unless you use kalam dev --force (which skips the prompt but still leaves sealing/applying the draft to the Apply path or explicit kalam migration seal).

Commands

kalam migration create <name>

Create a numbered migration immediately from the current diff (without going through the draft file):

1kalam migration create add_messages_table2# creates kalam/migrations/20260611120000_add_messages_table.sql

kalam migration status

Report migration state for the resolved environment:

1kalam migration status2kalam migration status --env staging

Groups: Applied, Pending, Failed, Applying.

kalam migration seal

Promote _draft.sql into the next numbered migration file (rename only — does not apply to the database):

1kalam migration seal

Run kalam db migrate afterward to apply the sealed migration.

kalam db migrate

Apply all pending numbered migrations to the linked database:

1kalam db migrate2kalam db migrate --env prod

• Does not include _draft.sql unless you sealed it first
• Ensures the target namespace exists before applying
• Validates checksums for migrations already marked applied

kalam migration retry <id>

Re-queue a failed migration for another apply attempt:

1kalam migration retry 20260610120000_add_users

kalam migration repair <id> --mark-applied

Manually mark a migration as applied on the server (use when you’ve fixed state out of band):

1kalam migration repair 20260610120000_add_users --mark-applied

How drafting works

1. Baseline — kalam/.schema-baseline.sql mirrors the last successfully applied schema
2. Diff — the CLI compares schema.sql to the baseline and generates UP/DOWN SQL
3. Draft — changes land in kalam/migrations/_draft.sql
4. Seal — kalam migration seal renames the draft to timestamp_name.sql
5. Apply — kalam db migrate or the dev pipeline executes UP statements and records checksums on the server
6. Baseline update — after apply, baseline is refreshed from schema.sql

If the diff is empty, a stale _draft.sql is removed automatically.

Dev vs deploy behavior

Production deploy applies committed migration history only. Generate and seal migrations locally before kalam deploy --env prod.

Stuck or failed migrations

During apply, the CLI may prompt when a migration was interrupted or failed previously:

• Retry — attempt apply again
• Skip / mark applied — for failed migrations when you’ve verified state manually
• Abort — stop the apply run

Pass --force on kalam dev to retry automatically in some stuck states.

For manual recovery:

1kalam migration status2kalam migration retry <migration_id>3# or4kalam migration repair <migration_id> --mark-applied

Global flags

All migration commands accept:

Migration file format

1-- Migration: add_messages_table2-- Created: 2026-06-11T12:00:00Z3 4-- UP5CREATE TABLE app.messages (6  id BIGINT PRIMARY KEY,7  body TEXT8);9 10-- DOWN11DROP TABLE app.messages;

Related

• Local Development — watch loop and draft prompts
• Project Init — kalam.toml and migrations directory
• SQL reference