chops

ClickHouse Operations CLI — health checks, data quality profiling, schema migrations, and observability from your terminal.

No more copy-pasting system table queries. One command to check cluster health, profile data quality, manage schema migrations, or find slow queries.

Quick Start

# Run directly with uvx (no install needed)
uvx chops health summary

# Or install with pip
pip install chops

Configuration

Set environment variables or pass flags:

export CLICKHOUSE_HOST=localhost
export CLICKHOUSE_PORT=8123
export CLICKHOUSE_USER=default
export CLICKHOUSE_PASSWORD=

Or use flags: chops --host myserver --user admin health summary

Config File

Create chops.toml (or .chops.toml) in your project directory, or ~/.config/chops/config.toml for global settings:

host = "localhost"
user = "default"

[profiles.prod]
host = "prod-cluster.example.com"
user = "admin"
password = "secret"
database = "analytics"

[profiles.staging]
host = "staging.example.com"
user = "readonly"

Use profiles with --profile or the CHOPS_PROFILE env var:

chops --profile prod health summary
CHOPS_PROFILE=staging chops dq profile events

Commands

Health & Observability

Data Quality

Ad-hoc Query

Schema Migrations

Examples

# Quick cluster health check
chops health summary

# Find which tables are eating disk
chops health table-sizes --limit 10

# Slowest queries in the last 6 hours
chops health slow-queries --hours 6

# Profile a table's data quality
chops dq profile mydb.events

# Run quality checks in CI (non-zero exit on failure)
chops dq check mydb.events --max-null-pct 5 --min-rows 1000

# Check if a streaming table is still receiving data
chops dq freshness mydb.events --warn 60 --critical 1440

# Detect row count anomalies (z-score based)
chops dq anomalies mydb.events --days 14

# Compare schemas between tables
chops dq compare mydb.events mydb.events_v2

# Ad-hoc query with different output formats
chops query "SELECT database, count() FROM system.tables GROUP BY database"
chops query "SELECT * FROM mydb.events LIMIT 10" --format json
chops query "SELECT * FROM mydb.events LIMIT 10" --format csv

# JSON output for automation
chops dq profile mydb.events --output json

# Schema migrations
chops migrate init
chops migrate new "add_user_scores_table"
chops migrate up
chops migrate status
chops migrate down --confirm

Migration files use a simple format with -- migrate:up and -- migrate:down sections:

-- migrate:up
CREATE TABLE mydb.user_scores (
    user_id UInt64,
    score Float32,
    updated_at DateTime DEFAULT now()
)
ENGINE = ReplacingMergeTree(updated_at)
ORDER BY user_id;

-- migrate:down
DROP TABLE IF EXISTS mydb.user_scores;

CI/CD Integration

chops dq check and chops dq freshness return non-zero exit codes on failure, making them usable in CI pipelines:

- name: Data quality gate
  run: |
    chops dq check production.orders --max-null-pct 2 --min-rows 10000
    chops dq freshness production.orders --warn 30 --critical 120

Development

git clone https://github.com/antonio-mello-ai/chops.git
cd chops
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/ tests/

# Type check
mypy src/

License

MIT