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 status13 14# 5. Start fresh local database state (stop kalam dev first)15kalam db reset16kalam dev

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 db reset

Clear local dev project state and, when appropriate, drop the linked namespace on the server so the next kalam dev can re-apply migrations cleanly.

1kalam db reset2kalam db reset --yes   # confirm namespace drop without prompting3kalam dev

Options

• --project-dir <PATH>
• --env <ENV>
• --yes — drop the namespace on a remote or non-project server without prompting (required in non-interactive shells when the server is not this project’s kalam/server)

Removes locally (when present):

• kalam/server/ — entire local server directory (data, logs, and server.toml)
• kalam/.schema-baseline.sql — schema diff baseline

Keeps:

• kalam/migrations/ — migration SQL files on disk

Server namespace drop (when the linked KalamDB server is reachable):

Dropping the namespace removes tables and server-side migration records for that namespace (including failed or stuck migrations in system.migrations).

If you decline the prompt, or run in a non-interactive shell without --yes, local files are still cleared but the server namespace is left unchanged. You may see migration failed previously on the next kalam dev until you run kalam db reset --yes or drop the namespace manually.

Stop kalam dev before reset when wiping kalam/server/ so RocksDB files are not locked.

After reset, run kalam dev again. Pending numbered migrations re-apply on startup.

The CLI prints each removed path, reports when nothing was present, and shows whether the namespace was dropped or skipped.

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 production behavior

Note: kalam deploy is not supported yet. For production, seal migrations locally, run kalam db migrate --env prod, and use your own rollout process.

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