chops 0.1.0__py3-none-any.whl

chops/__init__.py

@@ -0,0 +1,3 @@
+"""chops — ClickHouse Operations CLI."""
+
+__version__ = "0.1.0"

chops/cli.py

@@ -0,0 +1,70 @@
+"""CLI entry point for chops."""
+
+from __future__ import annotations
+
+import typer
+
+from chops import __version__
+from chops.commands import dq, health
+
+app = typer.Typer(
+    name="chops",
+    help="ClickHouse Operations CLI — health checks, data quality, and observability.",
+    no_args_is_help=True,
+)
+
+app.add_typer(health.app, name="health", help="Cluster health and observability commands.")
+app.add_typer(dq.app, name="dq", help="Data quality profiling and checks.")
+
+
+@app.command()
+def version() -> None:
+    """Show chops version."""
+    typer.echo(f"chops {__version__}")
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    host: str | None = typer.Option(
+        None,
+        "--host",
+        "-h",
+        envvar="CLICKHOUSE_HOST",
+        help="ClickHouse host",
+    ),
+    port: int | None = typer.Option(
+        None,
+        "--port",
+        "-p",
+        envvar="CLICKHOUSE_PORT",
+        help="ClickHouse HTTP port",
+    ),
+    user: str | None = typer.Option(
+        None,
+        "--user",
+        "-u",
+        envvar="CLICKHOUSE_USER",
+        help="ClickHouse user",
+    ),
+    password: str | None = typer.Option(
+        None,
+        "--password",
+        envvar="CLICKHOUSE_PASSWORD",
+        help="ClickHouse password",
+    ),
+    database: str | None = typer.Option(
+        None,
+        "--database",
+        "-d",
+        envvar="CLICKHOUSE_DATABASE",
+        help="Default database",
+    ),
+) -> None:
+    """Global connection options."""
+    ctx.ensure_object(dict)
+    ctx.obj["host"] = host
+    ctx.obj["port"] = port
+    ctx.obj["user"] = user
+    ctx.obj["password"] = password
+    ctx.obj["database"] = database

chops/client.py

@@ -0,0 +1,40 @@
+"""ClickHouse connection client."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import clickhouse_connect
+from clickhouse_connect.driver.client import Client
+
+
+def get_client(
+    host: str | None = None,
+    port: int | None = None,
+    user: str | None = None,
+    password: str | None = None,
+    database: str | None = None,
+    secure: bool | None = None,
+) -> Client:
+    """Create a ClickHouse client from explicit args or environment variables."""
+    return clickhouse_connect.get_client(
+        host=host or os.getenv("CLICKHOUSE_HOST", "localhost"),
+        port=port or int(os.getenv("CLICKHOUSE_PORT", "8123")),
+        username=user or os.getenv("CLICKHOUSE_USER", "default"),
+        password=password if password is not None else os.getenv("CLICKHOUSE_PASSWORD", ""),
+        database=database if database is not None else os.getenv("CLICKHOUSE_DATABASE", "default"),
+        secure=(
+            secure
+            if secure is not None
+            else os.getenv("CLICKHOUSE_SECURE", "false").lower() == "true"
+        ),
+        connect_timeout=10,
+    )
+
+
+def query(client: Client, sql: str, params: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+    """Execute a query and return results as list of dicts."""
+    result = client.query(sql, parameters=params or {})
+    columns = result.column_names
+    return [dict(zip(columns, row, strict=False)) for row in result.result_rows]

chops/commands/__init__.py

@@ -0,0 +1 @@
+"""chops CLI commands."""

chops/commands/dq.py

@@ -0,0 +1,345 @@
+"""Data quality commands."""
+
+from __future__ import annotations
+
+import json as json_mod
+
+import typer
+from clickhouse_connect.driver.client import Client
+from rich.console import Console
+from rich.table import Table
+
+from chops.client import get_client, query
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+def _get_conn(ctx: typer.Context) -> Client:
+    """Build client from context."""
+    obj = ctx.obj or {}
+    return get_client(
+        host=obj.get("host"),
+        port=obj.get("port"),
+        user=obj.get("user"),
+        password=obj.get("password"),
+        database=obj.get("database"),
+    )
+
+
+def _resolve_table(table: str, ctx_database: str | None) -> tuple[str, str]:
+    """Resolve 'db.table' or 'table' into (database, table)."""
+    if "." in table:
+        db, tbl = table.split(".", 1)
+        return db, tbl
+    return ctx_database or "default", table
+
+
+@app.command()
+def profile(
+    ctx: typer.Context,
+    table: str = typer.Argument(help="Table to profile (e.g. 'mydb.events' or 'events')"),
+    output: str = typer.Option("table", "--output", "-o", help="Output format: table, json"),
+    sample: int | None = typer.Option(
+        None,
+        "--sample",
+        "-s",
+        help="Sample N rows (faster for huge tables)",
+    ),
+) -> None:
+    """Profile a table: row count, null rates, cardinality, min/max per column."""
+    client = _get_conn(ctx)
+    obj = ctx.obj or {}
+    db, tbl = _resolve_table(table, obj.get("database"))
+
+    # Get columns
+    cols = query(
+        client,
+        f"""
+        SELECT name, type
+        FROM system.columns
+        WHERE database = '{db}' AND table = '{tbl}'
+        ORDER BY position
+    """,
+    )
+
+    if not cols:
+        console.print(f"[red]Table '{db}.{tbl}' not found or has no columns.[/red]")
+        raise typer.Exit(1)
+
+    # Row count
+    count_result = query(client, f"SELECT count() AS c FROM {db}.{tbl}")
+    total_rows = int(count_result[0]["c"]) if count_result else 0
+
+    # Build profiling query
+    select_parts: list[str] = []
+    for col in cols:
+        name = col["name"]
+        col_type = col["type"]
+        escaped = f"`{name}`"
+
+        select_parts.append(f"countIf({escaped} IS NULL) AS `{name}__nulls`")
+        select_parts.append(f"uniq({escaped}) AS `{name}__cardinality`")
+
+        # Min/max only for numeric and date types
+        if any(t in col_type for t in ("Int", "UInt", "Float", "Decimal", "Date", "DateTime")):
+            select_parts.append(f"min({escaped}) AS `{name}__min`")
+            select_parts.append(f"max({escaped}) AS `{name}__max`")
+
+    source = f"(SELECT * FROM {db}.{tbl} LIMIT {sample})" if sample else f"{db}.{tbl}"
+
+    profile_sql = f"SELECT {', '.join(select_parts)} FROM {source}"
+    profile_result = query(client, profile_sql)
+    stats = profile_result[0] if profile_result else {}
+
+    row_base = sample if sample else total_rows
+
+    # Build results
+    results: list[dict[str, object]] = []
+    for col in cols:
+        name = col["name"]
+        nulls = int(stats.get(f"{name}__nulls", 0))
+        cardinality = int(stats.get(f"{name}__cardinality", 0))
+        null_pct = round(nulls / row_base * 100, 1) if row_base > 0 else 0.0
+
+        entry: dict[str, object] = {
+            "column": name,
+            "type": col["type"],
+            "null_count": nulls,
+            "null_pct": null_pct,
+            "cardinality": cardinality,
+        }
+
+        min_val = stats.get(f"{name}__min")
+        max_val = stats.get(f"{name}__max")
+        if min_val is not None:
+            entry["min"] = min_val
+            entry["max"] = max_val
+
+        results.append(entry)
+
+    if output == "json":
+        payload = {"table": f"{db}.{tbl}", "rows": total_rows, "columns": results}
+        typer.echo(json_mod.dumps(payload, indent=2, default=str))
+        return
+
+    # Rich table output
+    t = Table(title=f"Profile: {db}.{tbl} ({total_rows:,} rows)")
+    t.add_column("Column", style="bold")
+    t.add_column("Type", style="dim")
+    t.add_column("Nulls", justify="right")
+    t.add_column("Null %", justify="right")
+    t.add_column("Cardinality", justify="right")
+    t.add_column("Min", justify="right")
+    t.add_column("Max", justify="right")
+
+    for r in results:
+        null_style = "red" if r["null_pct"] > 10 else ""  # type: ignore[operator]
+        t.add_row(
+            str(r["column"]),
+            str(r["type"]),
+            f"{r['null_count']:,}",
+            f"[{null_style}]{r['null_pct']}%[/{null_style}]" if null_style else f"{r['null_pct']}%",
+            f"{r['cardinality']:,}",
+            str(r.get("min", "")),
+            str(r.get("max", "")),
+        )
+
+    console.print(t)
+
+
+@app.command()
+def freshness(
+    ctx: typer.Context,
+    table: str = typer.Argument(help="Table to check (e.g. 'mydb.events' or 'events')"),
+    column: str | None = typer.Option(
+        None,
+        "--column",
+        "-c",
+        help="DateTime column to check (auto-detected if not provided)",
+    ),
+    warn_minutes: int = typer.Option(60, "--warn", help="Warning threshold in minutes"),
+    critical_minutes: int = typer.Option(
+        1440,
+        "--critical",
+        help="Critical threshold in minutes (default 24h)",
+    ),
+) -> None:
+    """Check data freshness — time since last row was inserted."""
+    client = _get_conn(ctx)
+    obj = ctx.obj or {}
+    db, tbl = _resolve_table(table, obj.get("database"))
+
+    # Auto-detect datetime column
+    if not column:
+        dt_cols = query(
+            client,
+            f"""
+            SELECT name FROM system.columns
+            WHERE database = '{db}' AND table = '{tbl}'
+                AND type LIKE '%DateTime%'
+            ORDER BY position
+            LIMIT 1
+        """,
+        )
+        if not dt_cols:
+            msg = f"No DateTime column found in {db}.{tbl}. Use --column to specify."
+            console.print(f"[red]{msg}[/red]")
+            raise typer.Exit(1)
+        column = dt_cols[0]["name"]
+
+    result = query(
+        client,
+        f"""
+        SELECT
+            max(`{column}`) AS latest,
+            dateDiff('minute', max(`{column}`), now()) AS minutes_ago
+        FROM {db}.{tbl}
+    """,
+    )
+
+    if not result or result[0].get("latest") is None:
+        console.print(f"[red]Table {db}.{tbl} is empty or column '{column}' has no data.[/red]")
+        raise typer.Exit(2)
+
+    row = result[0]
+    minutes = int(row["minutes_ago"])
+    latest = row["latest"]
+
+    if minutes >= critical_minutes:
+        style = "bold red"
+        status = "CRITICAL"
+        exit_code = 2
+    elif minutes >= warn_minutes:
+        style = "bold yellow"
+        status = "WARNING"
+        exit_code = 1
+    else:
+        style = "bold green"
+        status = "OK"
+        exit_code = 0
+
+    hours, mins = divmod(minutes, 60)
+    age_str = f"{hours}h {mins}m" if hours > 0 else f"{mins}m"
+
+    console.print(f"[{style}]{status}[/{style}] — {db}.{tbl}.{column}")
+    console.print(f"  Latest: {latest}")
+    console.print(f"  Age: {age_str} ago")
+
+    if exit_code > 0:
+        raise typer.Exit(exit_code)
+
+
+@app.command()
+def check(
+    ctx: typer.Context,
+    table: str = typer.Argument(help="Table to check (e.g. 'mydb.events' or 'events')"),
+    max_null_pct: float = typer.Option(
+        5.0,
+        "--max-null-pct",
+        help="Max null percentage before failing",
+    ),
+    min_rows: int | None = typer.Option(None, "--min-rows", help="Minimum expected row count"),
+    output: str = typer.Option("table", "--output", "-o", help="Output format: table, json"),
+) -> None:
+    """Run data quality checks on a table. Returns non-zero exit code on failure."""
+    client = _get_conn(ctx)
+    obj = ctx.obj or {}
+    db, tbl = _resolve_table(table, obj.get("database"))
+
+    # Row count
+    count_result = query(client, f"SELECT count() AS c FROM {db}.{tbl}")
+    total_rows = int(count_result[0]["c"]) if count_result else 0
+
+    # Columns
+    cols = query(
+        client,
+        f"""
+        SELECT name, type
+        FROM system.columns
+        WHERE database = '{db}' AND table = '{tbl}'
+        ORDER BY position
+    """,
+    )
+
+    if not cols:
+        console.print(f"[red]Table '{db}.{tbl}' not found.[/red]")
+        raise typer.Exit(2)
+
+    # Null checks
+    select_parts = [f"countIf(`{c['name']}` IS NULL) AS `{c['name']}__nulls`" for c in cols]
+    null_result = query(client, f"SELECT {', '.join(select_parts)} FROM {db}.{tbl}")
+    null_stats = null_result[0] if null_result else {}
+
+    failures: list[dict[str, object]] = []
+    passes: list[dict[str, object]] = []
+
+    # Check min rows
+    if min_rows is not None and total_rows < min_rows:
+        failures.append(
+            {
+                "check": "min_rows",
+                "column": "-",
+                "expected": f">= {min_rows:,}",
+                "actual": f"{total_rows:,}",
+            }
+        )
+    else:
+        passes.append(
+            {
+                "check": "row_count",
+                "column": "-",
+                "expected": f">= {min_rows:,}" if min_rows else "any",
+                "actual": f"{total_rows:,}",
+            }
+        )
+
+    # Check null rates
+    for col in cols:
+        name = col["name"]
+        nulls = int(null_stats.get(f"{name}__nulls", 0))
+        null_pct = round(nulls / total_rows * 100, 1) if total_rows > 0 else 0.0
+
+        entry: dict[str, object] = {
+            "check": "null_rate",
+            "column": name,
+            "expected": f"<= {max_null_pct}%",
+            "actual": f"{null_pct}%",
+        }
+
+        if null_pct > max_null_pct:
+            failures.append(entry)
+        else:
+            passes.append(entry)
+
+    if output == "json":
+        typer.echo(
+            json_mod.dumps(
+                {
+                    "table": f"{db}.{tbl}",
+                    "rows": total_rows,
+                    "passed": len(passes),
+                    "failed": len(failures),
+                    "failures": failures,
+                },
+                indent=2,
+                default=str,
+            )
+        )
+    else:
+        total_checks = len(passes) + len(failures)
+        status = "[green]PASSED[/green]" if not failures else "[red]FAILED[/red]"
+        console.print(f"\n{status} — {db}.{tbl}: {len(passes)}/{total_checks} checks passed\n")
+
+        if failures:
+            t = Table(title="Failed Checks", border_style="red")
+            t.add_column("Check", style="bold")
+            t.add_column("Column")
+            t.add_column("Expected")
+            t.add_column("Actual", style="red")
+            for f in failures:
+                t.add_row(str(f["check"]), str(f["column"]), str(f["expected"]), str(f["actual"]))
+            console.print(t)
+
+    if failures:
+        raise typer.Exit(1)

chops/commands/health.py

@@ -0,0 +1,297 @@
+"""Health and observability commands."""
+
+from __future__ import annotations
+
+import typer
+from clickhouse_connect.driver.client import Client
+from rich.console import Console
+from rich.table import Table
+
+from chops.client import get_client, query
+
+app = typer.Typer(no_args_is_help=True)
+console = Console()
+
+
+def _get_conn(ctx: typer.Context) -> Client:
+    """Build client from context."""
+    obj = ctx.obj or {}
+    return get_client(
+        host=obj.get("host"),
+        port=obj.get("port"),
+        user=obj.get("user"),
+        password=obj.get("password"),
+        database=obj.get("database"),
+    )
+
+
+@app.command()
+def summary(ctx: typer.Context) -> None:
+    """Show cluster health summary: version, uptime, databases, tables, parts, merges, queries."""
+    client = _get_conn(ctx)
+
+    # Server info
+    info = query(client, "SELECT version() AS version, uptime() AS uptime_seconds")
+    row = info[0] if info else {}
+    ver = row.get("version", "?")
+    uptime_s = int(row.get("uptime_seconds", 0))
+    days, rem = divmod(uptime_s, 86400)
+    hours, rem = divmod(rem, 3600)
+    mins, _ = divmod(rem, 60)
+    uptime_str = f"{days}d {hours}h {mins}m"
+
+    # Counts
+    sys_dbs = "('system', 'INFORMATION_SCHEMA', 'information_schema')"
+    db_count = query(
+        client,
+        f"SELECT count() AS c FROM system.databases WHERE name NOT IN {sys_dbs}",
+    )
+    table_count = query(
+        client,
+        f"SELECT count() AS c FROM system.tables WHERE database NOT IN {sys_dbs}",
+    )
+    parts_count = query(client, "SELECT count() AS c FROM system.parts WHERE active")
+    merges_count = query(client, "SELECT count() AS c FROM system.merges")
+    queries_count = query(
+        client,
+        "SELECT count() AS c FROM system.processes WHERE is_initial_query",
+    )
+
+    # Disk usage
+    disk = query(
+        client,
+        """
+        SELECT
+            formatReadableSize(sum(bytes_on_disk)) AS total_size,
+            sum(rows) AS total_rows
+        FROM system.parts
+        WHERE active
+    """,
+    )
+
+    table = Table(title="ClickHouse Health Summary", show_header=False, border_style="dim")
+    table.add_column("Metric", style="bold")
+    table.add_column("Value")
+
+    table.add_row("Version", str(ver))
+    table.add_row("Uptime", uptime_str)
+    table.add_row("Databases", str(db_count[0]["c"] if db_count else 0))
+    table.add_row("Tables", str(table_count[0]["c"] if table_count else 0))
+    table.add_row("Active parts", str(parts_count[0]["c"] if parts_count else 0))
+    table.add_row("Running merges", str(merges_count[0]["c"] if merges_count else 0))
+    table.add_row("Active queries", str(queries_count[0]["c"] if queries_count else 0))
+    if disk:
+        table.add_row("Total data size", str(disk[0].get("total_size", "?")))
+        table.add_row("Total rows", f"{int(disk[0].get('total_rows', 0)):,}")
+
+    console.print(table)
+
+
+@app.command(name="table-sizes")
+def table_sizes(
+    ctx: typer.Context,
+    limit: int = typer.Option(20, "--limit", "-n", help="Number of tables to show"),
+    database: str | None = typer.Option(None, "--database", "-d", help="Filter by database"),
+) -> None:
+    """Show disk usage by table, sorted by size."""
+    client = _get_conn(ctx)
+
+    where = "WHERE database NOT IN ('system', 'INFORMATION_SCHEMA', 'information_schema')"
+    if database:
+        where += f" AND database = '{database}'"
+
+    rows = query(
+        client,
+        f"""
+        SELECT
+            database,
+            name AS table_name,
+            engine,
+            formatReadableSize(total_bytes) AS size,
+            total_bytes,
+            formatReadableQuantity(total_rows) AS rows,
+            total_rows AS raw_rows,
+            partition_count
+        FROM (
+            SELECT
+                database,
+                table AS name,
+                engine,
+                sum(bytes_on_disk) AS total_bytes,
+                sum(rows) AS total_rows,
+                count(DISTINCT partition) AS partition_count
+            FROM system.parts
+            {where}
+            AND active
+            GROUP BY database, table, engine
+        )
+        ORDER BY total_bytes DESC
+        LIMIT {limit}
+    """,
+    )
+
+    table = Table(title=f"Top {limit} Tables by Size")
+    table.add_column("Database", style="cyan")
+    table.add_column("Table", style="bold")
+    table.add_column("Engine")
+    table.add_column("Size", justify="right", style="green")
+    table.add_column("Rows", justify="right")
+    table.add_column("Partitions", justify="right")
+
+    for r in rows:
+        table.add_row(
+            r["database"],
+            r["table_name"],
+            r["engine"],
+            r["size"],
+            r["rows"],
+            str(r["partition_count"]),
+        )
+
+    console.print(table)
+
+
+@app.command(name="slow-queries")
+def slow_queries(
+    ctx: typer.Context,
+    limit: int = typer.Option(10, "--limit", "-n", help="Number of queries to show"),
+    hours: int = typer.Option(24, "--hours", help="Look back N hours"),
+) -> None:
+    """Show slowest queries from the query log."""
+    client = _get_conn(ctx)
+
+    rows = query(
+        client,
+        f"""
+        SELECT
+            type,
+            query_duration_ms / 1000 AS duration_s,
+            formatReadableSize(read_bytes) AS read_size,
+            read_rows,
+            formatReadableSize(memory_usage) AS peak_memory,
+            user,
+            substring(query, 1, 120) AS query_preview
+        FROM system.query_log
+        WHERE event_time > now() - INTERVAL {hours} HOUR
+            AND type IN ('QueryFinish', 'ExceptionWhileProcessing')
+            AND query_kind = 'Select'
+            AND is_initial_query
+        ORDER BY query_duration_ms DESC
+        LIMIT {limit}
+    """,
+    )
+
+    table = Table(title=f"Top {limit} Slow Queries (last {hours}h)")
+    table.add_column("#", justify="right", style="dim")
+    table.add_column("Duration", justify="right", style="bold red")
+    table.add_column("Read", justify="right")
+    table.add_column("Rows", justify="right")
+    table.add_column("Memory", justify="right")
+    table.add_column("User")
+    table.add_column("Query", max_width=80)
+
+    for i, r in enumerate(rows, 1):
+        dur = f"{r['duration_s']:.1f}s"
+        table.add_row(
+            str(i),
+            dur,
+            r["read_size"],
+            f"{int(r['read_rows']):,}",
+            r["peak_memory"],
+            r["user"],
+            r["query_preview"],
+        )
+
+    console.print(table)
+
+
+@app.command()
+def merges(ctx: typer.Context) -> None:
+    """Show currently running merges."""
+    client = _get_conn(ctx)
+
+    rows = query(
+        client,
+        """
+        SELECT
+            database,
+            table,
+            round(progress * 100, 1) AS progress_pct,
+            round(elapsed, 1) AS elapsed_s,
+            num_parts,
+            formatReadableSize(total_size_bytes_compressed) AS size,
+            formatReadableSize(bytes_read_uncompressed) AS bytes_read,
+            formatReadableSize(bytes_written_uncompressed) AS bytes_written
+        FROM system.merges
+        ORDER BY elapsed DESC
+    """,
+    )
+
+    if not rows:
+        console.print("[green]No active merges.[/green]")
+        return
+
+    table = Table(title=f"Active Merges ({len(rows)})")
+    table.add_column("Database", style="cyan")
+    table.add_column("Table", style="bold")
+    table.add_column("Progress", justify="right")
+    table.add_column("Elapsed", justify="right")
+    table.add_column("Parts", justify="right")
+    table.add_column("Size", justify="right")
+
+    for r in rows:
+        table.add_row(
+            r["database"],
+            r["table"],
+            f"{r['progress_pct']}%",
+            f"{r['elapsed_s']}s",
+            str(r["num_parts"]),
+            r["size"],
+        )
+
+    console.print(table)
+
+
+@app.command(name="running-queries")
+def running_queries(ctx: typer.Context) -> None:
+    """Show currently running queries."""
+    client = _get_conn(ctx)
+
+    rows = query(
+        client,
+        """
+        SELECT
+            query_id,
+            user,
+            round(elapsed, 1) AS elapsed_s,
+            formatReadableSize(read_bytes) AS read_size,
+            read_rows,
+            formatReadableSize(memory_usage) AS memory,
+            substring(query, 1, 100) AS query_preview
+        FROM system.processes
+        WHERE is_initial_query
+        ORDER BY elapsed DESC
+    """,
+    )
+
+    if not rows:
+        console.print("[green]No running queries.[/green]")
+        return
+
+    table = Table(title=f"Running Queries ({len(rows)})")
+    table.add_column("Elapsed", justify="right", style="bold")
+    table.add_column("User")
+    table.add_column("Read", justify="right")
+    table.add_column("Memory", justify="right")
+    table.add_column("Query", max_width=80)
+
+    for r in rows:
+        table.add_row(
+            f"{r['elapsed_s']}s",
+            r["user"],
+            r["read_size"],
+            r["memory"],
+            r["query_preview"],
+        )
+
+    console.print(table)

chops-0.1.0.dist-info/METADATA

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: chops
+Version: 0.1.0
+Summary: ClickHouse Operations CLI — health checks, data quality profiling, and observability
+Project-URL: Homepage, https://github.com/antonio-mello-ai/chops
+Project-URL: Repository, https://github.com/antonio-mello-ai/chops
+Project-URL: Issues, https://github.com/antonio-mello-ai/chops/issues
+Author-email: Antonio Mello <antonio.mello@felhen.com.br>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,clickhouse,data-quality,database,observability,operations
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: clickhouse-connect>=0.7
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# chops
+
+ClickHouse Operations CLI — health checks, data quality profiling, and observability from your terminal.
+
+No more copy-pasting system table queries. One command to check cluster health, profile data quality, or find slow queries.
+
+## Quick Start
+
+```bash
+# 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:
+
+```bash
+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`
+
+## Commands
+
+### Health & Observability
+
+| Command | Description |
+|---------|-------------|
+| `chops health summary` | Cluster overview: version, uptime, databases, tables, parts, merges, queries |
+| `chops health table-sizes` | Disk usage by table, sorted by size |
+| `chops health slow-queries` | Top N slowest queries from query log |
+| `chops health merges` | Currently running merge operations |
+| `chops health running-queries` | Active queries with elapsed time and memory |
+
+### Data Quality
+
+| Command | Description |
+|---------|-------------|
+| `chops dq profile <table>` | Column-level profiling: null rates, cardinality, min/max |
+| `chops dq check <table>` | Run quality checks with configurable thresholds (CI-friendly exit codes) |
+| `chops dq freshness <table>` | Time since last row — OK/WARNING/CRITICAL with exit codes |
+
+## Examples
+
+```bash
+# 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
+
+# JSON output for automation
+chops dq profile mydb.events --output json
+```
+
+## CI/CD Integration
+
+`chops dq check` and `chops dq freshness` return non-zero exit codes on failure, making them usable in CI pipelines:
+
+```yaml
+- 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
+
+```bash
+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

chops-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+chops/__init__.py,sha256=b5hTDGHQP8zhs3wtEtBryS43CeIdoRzOYx5aAP-fEds,66
+chops/cli.py,sha256=FoXpYsRrnx3EV8u-RJpN4w_YmedCaXu1R0UW88FJvwg,1665
+chops/client.py,sha256=NN8G_U_RP_0I36iEoEvbynKfUIoBSCwNcLu-3p3vuow,1437
+chops/commands/__init__.py,sha256=Eoi6lnn2eFRky6Zttu4A3M6oxqQsKrBnRv0hHzUz-wI,26
+chops/commands/dq.py,sha256=h_fCkAFbl9bO0uWxJg9ga6xhRJXHgh6zAX1UwRfTHvM,10757
+chops/commands/health.py,sha256=jEbBirRfr2JggEfyWsuK2-hnSexmNVQglRXNzPcEHuE,9011
+chops-0.1.0.dist-info/METADATA,sha256=QVeQepqRYDv4PE_5C4tq9ZGt6uwPBm4ZwIHS-ElcfdM,4082
+chops-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+chops-0.1.0.dist-info/entry_points.txt,sha256=Gyn8uepwVskbK_q7XQg804URgD1g6yqmwlaf2k-YTfw,40
+chops-0.1.0.dist-info/licenses/LICENSE,sha256=cTwIz6AWGa-AZ2FGm1UhQERg3Z1Rc46T8ci6XfTnrGo,1070
+chops-0.1.0.dist-info/RECORD,,

chops-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

chops-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+chops = chops.cli:app

chops-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Mello
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.