chkit check
Evaluates a set of policy checks and exits with code 1 if any fail. Designed as a CI gate to catch problems before deployment.
Synopsis
Section titled “Synopsis”chkit check [flags]| Flag | Type | Default | Description |
|---|---|---|---|
--strict | boolean | false | Force all check policies on, regardless of config |
-t, --table <selector> | string | — | Scope the drift and plugin checks to matching tables; pending and checksum checks still cover all migrations (details) |
Global flags documented on CLI Overview.
Behavior
Section titled “Behavior”Built-in policies
Section titled “Built-in policies”| Policy | Config key | Default | What it checks |
|---|---|---|---|
| Fail on pending | check.failOnPending | true | Pending migrations exist |
| Fail on checksum mismatch | check.failOnChecksumMismatch | true | Applied migration files have been modified |
| Fail on drift | check.failOnDrift | true | Live ClickHouse schema differs from snapshot (not every property is compared) |
| Fail on extra objects | check.failOnExtraObjects | false | Objects exist in ClickHouse that are not in your schema |
By default, objects that exist in ClickHouse but are not in your schema (extra_object) are not treated as drift — so chkit coexists with unmanaged tables on a shared database without breaking the CI gate. They are still reported by chkit drift for visibility. Set check.failOnExtraObjects: true only when chkit owns the entire database and any unmanaged object should fail the check.
Policies can be disabled in config. The --strict flag forces failOnPending, failOnChecksumMismatch, and failOnDrift on regardless of config values.
Drift evaluation
Section titled “Drift evaluation”Drift is only evaluated when both a snapshot.json and a clickhouse config block are present. If either is missing, drift is skipped (not treated as a failure).
check fails before any policy runs when the server’s MergeTree index_granularity default is not clickhouse.indexGranularity (8192 by default). The message names the value to set.
Plugin check integration
Section titled “Plugin check integration”Plugins can register onCheck hooks that return findings with severity levels. If a plugin check has evaluated: true, ok: false, and at least one finding with severity: 'error', it adds plugin:<name> to the list of failed checks.
Built-in plugins that integrate with check:
- Codegen plugin — checks generated type freshness
- Backfill plugin — checks pending backfill state
Schema warnings
Section titled “Schema warnings”check reports the snapshot’s schema warnings, such as a quoted string default, as Warning: lines and in the warnings array of --json output. Warnings never fail the check.
CI gate pattern
Section titled “CI gate pattern”# In your CI pipelinechkit check --strict --json
# Exit code 0 = all checks pass# Exit code 1 = one or more checks failedExamples
Section titled “Examples”Run all checks with defaults:
chkit checkStrict mode (all policies on):
chkit check --strictJSON output for CI:
chkit check --jsonExit codes
Section titled “Exit codes”| Code | Meaning |
|---|---|
| 0 | All checks pass |
| 1 | One or more checks failed |
JSON output
Section titled “JSON output”{ "command": "check", "schemaVersion": 1, "strict": false, "policy": { "failOnPending": true, "failOnChecksumMismatch": true, "failOnDrift": true }, "ok": false, "failedChecks": ["pending_migrations", "plugin:codegen"], "pendingCount": 2, "checksumMismatchCount": 0, "drifted": false, "driftEvaluated": true, "driftReasonCounts": {}, "driftReasonTotals": { "total": 0, "object": 0, "table": 0 }, "plugins": { "codegen": { "evaluated": true, "ok": false, "findingCodes": ["codegen_stale_output"] } }, "warnings": []}Possible values for failedChecks:
pending_migrations— pending migrations existchecksum_mismatch— applied migration checksums don’t matchschema_drift— live schema differs from snapshotplugin:<name>— a plugin check reported an error
Related commands
Section titled “Related commands”chkit status— view migration state detailschkit drift— inspect drift detailschkit migrate— apply pending migrations to resolve check failures