Skip to Content
Schema Watch

Schema Watch

KalamDB supports two schema watch workflows. They solve different problems — use the one that matches how your schema changes.

ModeEntry pointWatchesBest for
File watchkalam devschema.sql on diskLocal development with kalam.toml projects
Remote pollkalam --watch-schemasystem.tables on the serverAny DDL applied outside your repo (admin UI, another CLI session)

File watch (kalam dev)

This is the default for KalamDB projects. Enable both flags in kalam.toml:

TOML
[schema]watch = true [dev]watch = trueapply_schema = truegenerate_types = true

Then run:

BASH
kalam dev

Behavior

  1. Poll schema.sql every 2 seconds
  2. On modification, debounce until the file is stable (handles editor save bursts)
  3. Diff against kalam/.schema-baseline.sql and update kalam/migrations/_draft.sql
  4. Apply pending numbered migrations
  5. Regenerate TypeScript/Dart artifacts when generate_types = true
  6. Prompt to apply the draft (unless kalam dev --force, which skips the modal — you still seal/apply through the prompt’s Apply path or kalam migration seal)

The watch loop runs alongside managed processes ([dev.processes]). Schema failures pause only the schema pipeline — other service logs keep streaming.

See Local Development and Migrations for the full pipeline.

Remote poll (kalam --watch-schema)

Legacy standalone mode for server-side schema changes. Requires --run:

BASH
kalam --watch-schema --run "npm run schema:gen"

Use when DDL runs directly against KalamDB (not through your local schema.sql) and you need a shell command to rerun after metadata changes.

Options

OptionDescription
--watch-schemaEnable remote polling mode
--namespace <NAME>Limit to namespaces (repeatable)
--table <namespace.table>Limit to tables (repeatable)
--run <COMMAND>Shell command after changes (required)
--run-on-startRun command once before polling
--interval <DURATION>Poll interval (default 5s; 500ms, 2s, 1m)

Examples

BASH
# All non-system schemaskalam --watch-schema --run "npm run schema:gen" # One namespacekalam --watch-schema --namespace app --run "npm run schema:gen" --run-on-start # Specific tablekalam --watch-schema --table app.messages --run "npm run schema:gen" --interval 2s

How remote polling works

The CLI queries system.tables and checks for rows whose updated_at is newer than the last observed timestamp. Namespace and table filters combine with OR.

This mode does not read kalam.toml, manage migrations, or start child processes. For full project workflows, prefer kalam dev.

Choosing a mode

BASH
# You edit schema.sql in a KalamDB project → use kalam devkalam dev # Someone else applies DDL via SQL/admin UI and you only need codegen → use --watch-schemakalam --watch-schema --namespace app --run "npm run schema:gen"
Last updated on
Topic ConsumersInteractive Commands