Skip to content

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.

chkit check [flags]
FlagTypeDefaultDescription
--strictbooleanfalseForce 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.

PolicyConfig keyDefaultWhat it checks
Fail on pendingcheck.failOnPendingtruePending migrations exist
Fail on checksum mismatchcheck.failOnChecksumMismatchtrueApplied migration files have been modified
Fail on driftcheck.failOnDrifttrueLive ClickHouse schema differs from snapshot (not every property is compared)
Fail on extra objectscheck.failOnExtraObjectsfalseObjects 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 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.

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:

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.

Terminal window
# In your CI pipeline
chkit check --strict --json
# Exit code 0 = all checks pass
# Exit code 1 = one or more checks failed

Run all checks with defaults:

Terminal window
chkit check

Strict mode (all policies on):

Terminal window
chkit check --strict

JSON output for CI:

Terminal window
chkit check --json
CodeMeaning
0All checks pass
1One or more checks failed
{
"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 exist
  • checksum_mismatch — applied migration checksums don’t match
  • schema_drift — live schema differs from snapshot
  • plugin:<name> — a plugin check reported an error