clickhouse-tool 0.1.1__tar.gz

clickhouse_tool-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+coverage.xml
+htmlcov/
+.coverage
+.pytest_cache/
+__pycache__/
+*.pyc
+.venv/

clickhouse_tool-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vlad Korolev
+
+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.

clickhouse_tool-0.1.1/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.5
+Name: clickhouse-tool
+Version: 0.1.1
+Summary: ClickHouse query and administration CLI tool for the OTel logs/metrics pilot
+Author-email: Vlad Korolev <vlad@v-lad.org>
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: boto3>=1.34.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentry-sdk>=1.40.0
+Requires-Dist: structlog>=24.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: all
+Requires-Dist: clickhouse-connect>=0.7.0; extra == 'all'
+Requires-Dist: clickhouse-driver>=0.2.9; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pre-commit>=4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: http
+Requires-Dist: clickhouse-connect>=0.7.0; extra == 'http'
+Provides-Extra: native
+Requires-Dist: clickhouse-driver>=0.2.9; extra == 'native'
+Description-Content-Type: text/markdown
+
+# clickhouse-tool
+
+A command-line client for querying and inspecting ClickHouse, over both
+the native protocol (port 9000) and HTTP (port 8123).
+
+`clickhouse-tool` provides porcelain commands (`logs`, `hosts`, `services`)
+for browsing OTel-shaped log data, plus low-level verbs (`query`, `list`,
+`lift`, `config`) for direct inspection of any table. Output renders as a
+table, JSON, NDJSON, or the compact TOON format, with pinned typed exit
+codes for scripting.
+
+## Install
+
+```
+pip install clickhouse-tool[native]   # native protocol (port 9000)
+pip install clickhouse-tool[http]     # HTTP protocol (port 8123)
+pip install clickhouse-tool[all]      # both
+```
+
+## Configuration
+
+Copy `config.example.toml` to `./clickhouse-tool.toml` or
+`~/.config/clickhouse-tool/config.toml` and fill in a profile for your
+cluster. See that file for the full set of options.

clickhouse_tool-0.1.1/README.md

@@ -0,0 +1,24 @@
+# clickhouse-tool
+
+A command-line client for querying and inspecting ClickHouse, over both
+the native protocol (port 9000) and HTTP (port 8123).
+
+`clickhouse-tool` provides porcelain commands (`logs`, `hosts`, `services`)
+for browsing OTel-shaped log data, plus low-level verbs (`query`, `list`,
+`lift`, `config`) for direct inspection of any table. Output renders as a
+table, JSON, NDJSON, or the compact TOON format, with pinned typed exit
+codes for scripting.
+
+## Install
+
+```
+pip install clickhouse-tool[native]   # native protocol (port 9000)
+pip install clickhouse-tool[http]     # HTTP protocol (port 8123)
+pip install clickhouse-tool[all]      # both
+```
+
+## Configuration
+
+Copy `config.example.toml` to `./clickhouse-tool.toml` or
+`~/.config/clickhouse-tool/config.toml` and fill in a profile for your
+cluster. See that file for the full set of options.

clickhouse_tool-0.1.1/SKILL.md

@@ -0,0 +1,234 @@
+# clickhouse-tool
+
+CLI to query and inspect ClickHouse, over both the native protocol
+(port 9000) and HTTP (port 8123). Invoked as `clickhouse-tool`.
+
+## When to Use / When NOT to Use
+
+| Use clickhouse-tool for | Do NOT use for |
+|--------------------------|-----------------|
+| Browsing OTel-shaped logs with a `logs`/`hosts`/`services` porcelain | Writes or DDL (the tool is read-only by design) |
+| Counting hosts/services over logs or metrics activity | Detailed metric values/time series (`hosts`/`services` only count activity, not metric values) |
+| Inspecting any allow-listed table's rows/columns | Cluster administration (node/shard management, replication control) |
+| Running direct SQL against the cluster | |
+| Scripting against pinned exit codes | |
+
+## Quick Reference
+
+```bash
+clickhouse-tool logs --service payments -l error -t 1h    # recent error logs for a service
+clickhouse-tool logs --follow --host k8s-3                # tail new rows continuously
+clickhouse-tool hosts -t 15m                              # host counts, last 15 minutes
+clickhouse-tool services --unbounded                      # every service, no cap
+clickhouse-tool metrics names -n 10                       # most active metric names
+clickhouse-tool metrics status k8s.node.memory -t 1h       # min/max/avg/stddev per metric
+clickhouse-tool metrics histogram system.cpu.utilization -t 1h  # time-bucketed stats
+clickhouse-tool tables                                     # every table list/lift/query may target
+clickhouse-tool list otel.otel_logs -n 5                  # peek at raw rows
+clickhouse-tool lift otel.otel_logs                        # describe columns
+clickhouse-tool query "SELECT count() FROM otel.otel_logs" # raw SQL
+clickhouse-tool config                                     # show resolved profile, no AWS needed
+```
+
+## Commands
+
+### `logs` — the baseline verb
+
+```bash
+clickhouse-tool logs [--host/-h HOST] [--service SERVICE] [--namespace NS]
+                      [--container C] [--level/-l LEVEL] [-t/--time-range 15m|2h|1d]
+                      [--search/-s TERM] [--sort SORT] [--full] [--raw]
+                      [--count] [--follow] [--utc] [-n/--limit N]
+                      [-f/--format table|json|ndjson|toon]
+```
+
+- `--count` returns a single row count instead of rows.
+- `--full`/`--raw` select every column and switch to nested output — the only
+  verb that may stream (via the `ndjson` formatter).
+- `--follow` polls continuously for new rows, oldest first, until Ctrl-C.
+  `-t` seeds the starting point (how far back the first batch reaches);
+  after that, only rows newer than the last one seen are printed. Not
+  compatible with `--count` or `--sort` (follow mode always orders
+  ascending by time).
+- The `ts` column renders in local time by default; `--utc` shows UTC
+  instead. The profile's `default_timezone` sets the non-`--utc` default
+  (`local`, `UTC`, or any IANA zone name — `local` resolves to the
+  machine's own zone). `--full`/`--raw` show the raw server value
+  unconverted, since they select `*` directly, not the `ts` alias.
+- Time window defaults to the profile's `default_window` (`2h` in the
+  example config) when `-t` is omitted.
+
+### `hosts` / `services` — grouped counts
+
+```bash
+clickhouse-tool hosts    [--namespace NS] [--container C] [--level/-l LEVEL]
+                          [-t/--time-range WINDOW] [--search/-s TERM]
+                          [--stream logs|metrics] [-n/--limit N] [--unbounded]
+                          [-f/--format ...]
+clickhouse-tool services [same flags]
+```
+
+- Grouped by host or service, ordered by count descending, capped at 200
+  rows unless `--unbounded`. Each row also shows `last_seen`, rendered as a
+  relative time (`2h 20m ago`) -- a second unit only above a 10 threshold,
+  seconds is the finest granularity shown.
+- `--stream metrics` (default) counts metric datapoints -- useful since not
+  every host/service that emits metrics also emits logs. `--stream logs`
+  counts log rows instead. Metrics mode only supports `-t`/`--time-range`;
+  `--namespace`, `--container`, `--level`, `--search` all raise `ConfigError`
+  (exit 3) on that stream, since metrics carry none of those attributes.
+
+### `metrics` — metric names, stats, values, and histograms
+
+```bash
+clickhouse-tool metrics names   [-t/--time-range WINDOW] [-n/--limit N] [--unbounded] [-f/--format ...]
+clickhouse-tool metrics status  <name> [--host H] [--service S] [-t/--time-range WINDOW]
+                                 [--split-by host,service] [-f/--format ...]
+clickhouse-tool metrics values  <name> [--host H] [--service S] [-t/--time-range WINDOW]
+                                 [--follow] [-n/--limit N] [-f/--format ...]
+clickhouse-tool metrics histogram <name> [--host H] [--service S] [-t/--time-range WINDOW]
+                                   [--bucket WIDTH] [--split-by host,service] [-f/--format ...]
+```
+
+- `<name>` matches an exact metric name (`k8s.node.filesystem.capacity`) or a
+  dotted stem matching every child metric (`k8s.node.memory`).
+- `names` groups by metric name over the metrics stream, ordered by
+  datapoint count descending, capped at 200 unless `--unbounded`. Same
+  `last_seen` column as `hosts`/`services`.
+- `status` reports `min`/`max`/`avg`/`stddev` per matched metric name.
+  `--split-by host,service` breaks the summary out per host and/or
+  service instead of merging them.
+- `values` returns raw datapoints oldest-first, capped at 1000 unless
+  `-n` overrides. `--follow` polls continuously starting from the most
+  recent matching datapoint (not `-n`-compatible), same semantics as
+  `logs --follow`.
+- `histogram` buckets datapoints by time, reporting `min`/`max`/`avg`/`count`
+  per bucket per matched metric name. `--bucket` sets the width explicitly
+  (`5m`, `1h`, ...); omitted, it's sized automatically from the time window
+  to land around 36 buckets, snapped to a round duration (seconds through
+  weeks). `--split-by host,service` breaks each metric's buckets out per
+  host and/or service instead of merging them.
+
+### `list` / `lift` — low-level table inspection
+
+```bash
+clickhouse-tool list <table> [-n/--limit N] [-f/--format ...]   # raw rows
+clickhouse-tool lift <table> [-f/--format ...]                  # column metadata
+```
+
+- `<table>` must be allow-listed: any `otel.<identifier>`, or one of
+  `system.parts`, `.errors`, `.tables`, `.columns`, `.metrics`,
+  `.asynchronous_metrics`, `.query_log`.
+- `lift` defaults to `json` output (nested-friendly), not the profile's
+  `default_format`.
+
+### `query` — raw SQL
+
+```bash
+clickhouse-tool query "SELECT ... " [--param name=value ...] [-f/--format ...]
+echo "SELECT 1" | clickhouse-tool query
+```
+
+- SQL comes from the positional argument, or from stdin if no argument is
+  given and stdin is not a TTY — never both at once.
+- `--param` is repeatable, binds named parameters as strings.
+- Bypasses the query builder entirely: no table allow-list, no column
+  validation. Read-only safety comes **solely** from the server-side
+  `readonly=2` setting, not from anything this tool parses. Server errors
+  (including malformed SQL) echo back verbatim — the caller wrote the query.
+
+### `config` — show the resolved profile
+
+```bash
+clickhouse-tool config [--profile NAME]
+```
+
+- Never touches AWS SSM and never opens a connection — works with zero AWS
+  credentials present. Secrets print as unresolved references
+  (`(unresolved, ssm:<path>)`), never as values.
+
+### `tables` — list what `list`/`lift`/`query` may target
+
+```bash
+clickhouse-tool tables [--profile NAME] [-f/--format ...]
+```
+
+- Combines the profile's `otel.*` tables (queried live from the cluster)
+  with the seven fixed `system.*` tables the allow-list also accepts.
+  Unlike `config`, this connects to the cluster.
+
+## Profiles and Connection
+
+- `--profile NAME` on any command selects a named profile from config.
+- Config precedence, highest first: CLI flag > `CLICKHOUSE_TOOL_*` env var >
+  selected profile > project-local `./clickhouse-tool.toml` > user
+  `~/.config/clickhouse-tool/config.toml` > built-in defaults.
+- Copy `config.example.toml` to get started; it ships a `pilot` (native,
+  port 9000) and `pilot-http` (HTTP, port 8123) profile pointed at the same
+  cluster, with credentials resolved lazily from AWS SSM (`user`/`password`
+  as `{ ssm = "<path>" }`).
+- Secrets are resolved lazily — only verbs that actually connect touch SSM.
+  `config` never does.
+
+## Output Formats
+
+| Flag | Use case |
+|------|----------|
+| `-f json` | Agent processing, or nested output (`lift`, `--full`, `--raw`) — buffered array, Map columns kept nested |
+| `-f ndjson` | Streaming large result sets row-by-row — never buffers the full set |
+| `-f table` | Presenting results to a human in a terminal — rich table, null renders `-` |
+| `-f toon` | Default format — compact `name[N]{fields}` dialect, cheapest to read/grep |
+
+Format defaults to the profile's `default_format` (`toon` in the example
+config) when `-f` is omitted, except `lift`, which defaults to `json`.
+
+`-f table` humanizes numbers and timestamps; every other format renders raw
+values, unaffected by any of the flags below:
+- Numbers get a k/m/g suffix once the scaled value would read 10 or
+  higher (`1024` stays `1024`, `10000` becomes `10k`), rounded to 2
+  decimal places by default -- override with `--decimals N` (`metrics
+  status`/`values`/`histogram`).
+- Timestamps drop their seconds component once the queried time window
+  exceeds 3 hours, showing whole seconds below that. `--ts-decimals N`
+  (`metrics values`/`histogram`) forces second-level display with `N`
+  fractional digits, overriding the window-based default.
+
+## Error Handling
+
+| Exit code | Meaning | Agent action |
+|-----------|---------|---------------|
+| 0 | Success | Proceed |
+| 1 | General/unexpected error | Report — no documented outcome maps here |
+| 2 | Usage error | Fix command syntax |
+| 3 | Config error (bad profile, unknown column/table/sort, malformed `--param`, missing driver, bad `--stream` value) | Check flags/profile, fix and retry |
+| 4 | Connection failed | Cluster unreachable — check host/port/transport |
+| 5 | Auth failed | Check credentials / SSM refs |
+| 6 | Query timeout | Narrow the query or raise `query_timeout` in the profile |
+| 7 | Result too large | Narrow the time window or add a `--limit` |
+| 8 | Server resource error | Cluster is under memory/resource pressure — retry later |
+| 9 | Permission denied | Check the ClickHouse user's grants |
+| 10 | Schema error | Table/column doesn't exist as named — check `lift` |
+| 11 | Unsupported filter (e.g. `--container` on a key that doesn't exist) | The container-preflight check failed — verify the filter value |
+| 12 | Server error (unmapped ClickHouse code) | Server returned an error code with no local mapping — report the message |
+
+Every typed error prints its message to stderr; stdout is reserved for
+data only. `BrokenPipeError` (e.g. piping into `head`) exits 0 quietly,
+no traceback.
+
+## Global Options
+
+| Flag | Purpose |
+|------|---------|
+| `--profile NAME` | Select connection profile |
+| `-f/--format table\|json\|ndjson\|toon` | Output format |
+| `-v/--verbose` | Enable debug logging |
+| `--help` | Show help (note: `-h` is reserved for `--host` on `logs`, not help) |
+
+## Known Limitations
+
+- No cluster administration commands (node/shard/replication management)
+  — use ClickHouse's own tooling for that.
+- `hosts --stream metrics` / `services --stream metrics` only enumerate
+  activity against `otel_metrics_gauge`; the other metrics tables
+  (`otel_metrics_sum`, `otel_metrics_histogram`, etc. — see `tables`) have
+  no porcelain support yet — use `list`/`query` directly against them.

clickhouse_tool-0.1.1/config.example.toml

@@ -0,0 +1,40 @@
+# Example clickhouse-tool configuration.
+#
+# Copy to ./clickhouse-tool.toml (project-local) or
+# ~/.config/clickhouse-tool/config.toml (user-level). Project-local wins
+# on any field present in both.
+
+default_profile = "pilot"      # never "default"
+default_format  = "toon"
+default_window  = "2h"
+default_timezone = "local"     # "local", "UTC", or any IANA zone name
+
+[profiles.pilot]
+host      = "your-clickhouse-host.example.com"
+port      = 9000
+transport = "native"           # "native" | "http", both implemented
+database  = "otel"
+secure    = false
+logs_table = "otel_logs"
+connect_timeout = 10
+query_timeout   = 60
+
+[profiles.pilot.user]
+ssm = "/clickhouse/v1/pilot/tool/username"
+[profiles.pilot.password]
+ssm = "/clickhouse/v1/pilot/tool/password"
+
+[profiles.pilot-http]           # HTTP-transport variant of the same pilot
+host = "your-clickhouse-host.example.com"
+port = 8123
+transport = "http"
+database = "otel"
+secure = false
+logs_table = "otel_logs"
+connect_timeout = 10
+query_timeout = 60
+
+[profiles.pilot-http.user]
+ssm = "/clickhouse/v1/pilot/tool/username"
+[profiles.pilot-http.password]
+ssm = "/clickhouse/v1/pilot/tool/password"

clickhouse_tool-0.1.1/pyproject.toml

@@ -0,0 +1,149 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "clickhouse-tool"
+version = "0.1.1"
+description = "ClickHouse query and administration CLI tool for the OTel logs/metrics pilot"
+readme = "README.md"
+authors = [
+  {name = "Vlad Korolev", email = "vlad@v-lad.org"}
+]
+requires-python = ">=3.11"
+dependencies = [
+  "typer>=0.12.0",
+  "pydantic>=2.5.0",
+  "rich>=13.0.0",
+  "structlog>=24.0",
+  "sentry-sdk>=1.40.0",
+  "boto3>=1.34.0"
+]
+
+[project.optional-dependencies]
+native = [
+  "clickhouse-driver>=0.2.9"
+]
+http = [
+  "clickhouse-connect>=0.7.0"
+]
+all = [
+  "clickhouse-tool[native]",
+  "clickhouse-tool[http]"
+]
+dev = [
+  "pytest>=8.0",
+  "pytest-cov>=4.0",
+  "ruff>=0.8",
+  "mypy>=1.13",
+  "pre-commit>=4.0"
+]
+
+[project.scripts]
+clickhouse-tool = "clickhouse_tool.cli.main:run"
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "def __repr__",
+  "if self.debug:",
+  "if settings.DEBUG",
+  "raise AssertionError",
+  "raise NotImplementedError",
+  "if 0:",
+  "if __name__ == .__main__.:",
+  "class .*\\bProtocol\\):",
+  "@(abc\\.)?abstractmethod"
+]
+
+[tool.coverage.run]
+source = ["src"]
+omit = [
+  "*/tests/*",
+  "*/test_*.py",
+  "*/__about__.py"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clickhouse_tool"]
+
+[tool.mypy]
+python_version = "3.11"
+plugins = ["pydantic.mypy"]
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_any_generics = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_unreachable = true
+strict_equality = true
+exclude = ["tests/"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = ["clickhouse_driver.*", "clickhouse_connect.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = [
+  "--strict-markers",
+  "--strict-config",
+  "--cov=clickhouse_tool",
+  "--cov-report=term-missing",
+  "--cov-report=html:htmlcov",
+  "--cov-report=xml",
+  "--cov-fail-under=80"
+]
+markers = [
+  "unit: marks tests as unit tests (fast, no external dependencies)",
+  "integration: marks tests as integration tests (requires the real ClickHouse pilot)",
+  "slow: marks tests as slow (deselect with '-m \"not slow\"')"
+]
+filterwarnings = [
+  "error",
+  "ignore::UserWarning",
+  "ignore::DeprecationWarning"
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+  "E",
+  "F",
+  "I",
+  "N",
+  "W",
+  "UP",
+  "B",
+  "C4",
+  "SIM",
+  "PTH",
+  "RUF",
+  "S"
+]
+ignore = [
+  "E501",
+  "B008",
+  "N818" # exception names are the plan's pinned contract (AuthFailed, QueryTimeout, ...)
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.isort]
+known-first-party = ["clickhouse_tool"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"tests/**/*.py" = ["S101"]

clickhouse_tool-0.1.1/src/clickhouse_tool/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

clickhouse_tool-0.1.1/src/clickhouse_tool/__init__.py

@@ -0,0 +1,5 @@
+from clickhouse_tool import __about__
+
+__version__ = __about__.__version__
+
+__all__ = ["__about__", "__version__"]

clickhouse_tool-0.1.1/src/clickhouse_tool/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for ``python -m clickhouse_tool``."""
+
+from clickhouse_tool.cli.main import run
+
+if __name__ == "__main__":
+    run()

clickhouse_tool-0.1.1/src/clickhouse_tool/cli/commands/config.py

@@ -0,0 +1,21 @@
+"""The skip-secrets verb: shows the resolved profile with provenance.
+
+Never materialises secrets and never opens a connection, so it works
+with no AWS credentials present at all.
+"""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from clickhouse_tool.cli import wiring
+
+
+def config(
+    profile: str | None = typer.Option(None, "--profile", help="Named connection profile"),
+) -> None:
+    """Show the resolved configuration, with secrets redacted."""
+    resolved = wiring.load_profile(profile)
+    print(json.dumps(resolved.model_dump(), indent=2, default=str))