Skip to content

chkit status

Reports the current migration state by comparing migration files on disk against the migration journal stored in ClickHouse. Requires a ClickHouse connection.

chkit status [flags]

No command-specific flags. See global flags.

chkit status reads the migrations directory and the _chkit_migrations journal table in ClickHouse to compute:

  • Total migration files (.sql files in migrationsDir, sorted alphabetically)
  • Applied migrations (entries recorded in the journal table)
  • Pending migrations (on disk but not yet applied)
  • In progress migrations (pending migrations that failed part-way)
  • Checksum mismatches (applied migrations whose SHA-256 checksum no longer matches the file on disk)

A migration that failed part-way counts as pending until a later run applies it. chkit status also lists it under In progress, with the number of completed statements, the state of every other recorded statement, and the command that continues it. See failed migrations.

chkit status requires a ClickHouse connection and fails if no clickhouse connection is configured. It only reads: when the _chkit_migrations journal table does not exist, every migration is pending, and the table is not created (the first chkit migrate --apply creates it). A read-only user (readonly = 1 or readonly = 2, with SELECT on the journal) can run it, as well as chkit check, chkit drift, chkit migrate without --apply and chkit query. The one exception is a journal created by a chkit version without per-operation tracking: the first command that reads it adds the missing columns with ALTER TABLE ... ADD COLUMN IF NOT EXISTS, which needs a user that can alter the table.

Terminal window
chkit status
Migrations: 5 total, 3 applied, 2 pending
Checksum mismatches: 0

With a migration that failed part-way:

In progress (failed part-way, still pending):
- 20260929001110_funnel-model.sql: 1 statement completed
Statement 2 failed: Unknown table expression identifier 'analytics.sessions' in scope SELECT session_id FROM analytics.sessions.
Next: chkit migrate --apply
Terminal window
chkit status --json
CodeMeaning
0Success
1Error (e.g. no ClickHouse connection configured)
{
"command": "status",
"schemaVersion": 1,
"migrationsDir": "/absolute/path/to/migrations",
"total": 5,
"applied": 3,
"pending": 2,
"pendingMigrations": ["20260604104251_add_column.sql", "20260604105133_create_index.sql"],
"inProgressMigrations": [],
"checksumMismatchCount": 0,
"checksumMismatches": []
}

Each inProgressMigrations entry has the migration name, fileChanged (the file changed since its last failed attempt), completedStatements, statements and nextSteps (the commands that continue it, in order). statements lists every recorded statement that is not completed, with its 1-based statement number, operation type and key, and a state:

stateMeaning
failedThe statement failed; error holds the error.
interruptedchkit stopped while the statement ran, so it may have run.
runningAn async statement whose query may still run on the server; queryId names it.
awaiting_replicasThe statement ran, but its change has not reached every replica; the next apply waits for it again.
abandoned--abandon reset it; was is its status before.

When checksum mismatches are detected, each entry includes the migration name, expected checksum (from the journal), and actual checksum (from the file on disk).