clickhawk 0.1.0__tar.gz

clickhawk-0.1.0/.claude/settings.local.json

@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(which clickhouse:*)",
+      "Bash(pip show:*)",
+      "Bash(pip3 show:*)",
+      "Bash(which ch:*)",
+      "Bash(/Users/zhenningli/.pyenv/versions/3.14.2/bin/pip show:*)",
+      "Bash(/Users/zhenningli/.pyenv/versions/3.14.2/bin/ch query:*)",
+      "Bash(/Users/zhenningli/.pyenv/versions/3.14.2/bin/pip install:*)",
+      "Bash(CH=/Users/zhenningli/.pyenv/versions/3.14.2/bin/ch\n\necho \"=== ch health ===\"\n$CH health\n\necho \"\"\necho \"=== ch query table ===\"\n$CH query 'SELECT event_type, count\\(\\) AS cnt FROM demo.events GROUP BY event_type ORDER BY cnt DESC'\n\necho \"\"\necho \"=== ch query --format json ===\"\n$CH query 'SELECT event_type, count\\(\\) AS cnt FROM demo.events GROUP BY event_type' --format json\n\necho \"\"\necho \"=== ch query --format csv ===\"\n$CH query 'SELECT user_id, count\\(\\) AS cnt FROM demo.events GROUP BY user_id ORDER BY cnt DESC LIMIT 5' --format csv\n\necho \"\"\necho \"=== ch query --limit ===\"\n$CH query 'SELECT * FROM demo.events' --limit 3\n\necho \"\"\necho \"=== ch schema tables ===\"\n$CH schema tables --database demo\n\necho \"\"\necho \"=== ch schema show ===\"\n$CH schema show events --database demo\n\necho \"\"\necho \"=== ch slowlog ===\"\n$CH slowlog --threshold 1 --hours 1 --top 5\n\necho \"\"\necho \"=== ch profile ===\"\n$CH profile 'SELECT uniq\\(user_id\\) FROM demo.events WHERE date = today\\(\\)')",
+      "Bash(/Users/zhenningli/.pyenv/versions/3.14.2/bin/python -m pytest tests/unit/ -v 2>&1)",
+      "Bash(/Users/zhenningli/.pyenv/versions/3.14.2/bin/python -c \"import clickhawk.formatters.table as m; import inspect; print\\(inspect.signature\\(m.print_result\\)\\)\")",
+      "Bash(/Users/zhenningli/.pyenv/versions/3.14.2/bin/python -m pytest tests/integration/ -v -m integration 2>&1)",
+      "Bash(for f:*)",
+      "Bash(do echo:*)",
+      "Read(//Users/zhenningli/Documents/GitHub/clickhawk/**)",
+      "Bash(done)",
+      "Bash(git mv:*)",
+      "Bash(cat:*)",
+      "Bash(git rm:*)",
+      "Bash(echo:*)",
+      "Bash(which python3:*)",
+      "Bash(~/.pyenv/shims/python -m pytest tests/unit/ -q 2>&1 | tail -5)",
+      "Bash(~/.pyenv/shims/python -m pytest tests/integration/ -m integration -q 2>&1 | tail -5)"
+    ]
+  }
+}

clickhawk-0.1.0/.env.example

@@ -0,0 +1,5 @@
+CH_HOST=localhost
+CH_PORT=8123
+CH_USER=default
+CH_PASSWORD=
+CH_DATABASE=default

clickhawk-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

clickhawk-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+wheels/
+sdist/
+.eggs/
+
+# 虚拟环境
+.venv/
+venv/
+env/
+ENV/
+
+# 环境配置（含敏感信息）
+.env
+.env.local
+.env.*.local
+
+# 类型检查 / linter / 测试缓存
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# 编辑器
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# ClickHouse 本地数据（tutorial.md 中创建的本地测试目录）
+clickhouse-data/
+clickhouse-config.xml
+/tmp/clickhouse.log
+
+# 日志
+*.log
+
+# pyproject 构建产物
+*.whl

clickhawk-0.1.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+This project follows the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format, and versioning follows [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+### Planned
+- `ch explain` — colorized tree-style EXPLAIN PLAN output
+- `ch schema diff` — compare schema differences between two ClickHouse environments
+- `ch migrate run/status` — file-based schema migration management
+
+---
+
+## [0.1.0] — 2026-03-16
+
+### Added
+- **`ch health`** — cluster health check displaying version, uptime, database count, and table count
+- **`ch query <sql>`** — execute SQL queries with support for `table` (default) / `json` / `csv` output formats and `--limit` row truncation
+- **`ch profile <sql>`** — query performance analysis extracting real execution statistics from `system.query_log` (wall time, DB time, rows/bytes read, memory, parts/ranges hit count)
+- **`ch slowlog`** — slow query history ranking with customizable `--top`, `--threshold` (milliseconds), and `--hours` parameters
+- **`ch schema show <table>`** — display table schema (column name / type / default / comment) with `--database` filter support
+- **`ch schema tables`** — list all user tables showing database, engine, disk size, and row count with `--database` filter support
+- **`ch monitor`** — real-time live dashboard polling `system.processes`, with color-coded long-running queries (>5s yellow, >30s red) and customizable `--interval` refresh rate
+- **`ch migrate run/status`** — placeholder commands, to be fully implemented in v0.2
+
+### Technical Foundation
+- CLI framework built on **Typer** with `ch` as the command entry point
+- **Rich** for colorized table rendering and Live real-time refresh
+- **clickhouse-connect** for ClickHouse connectivity (HTTP protocol)
+- **Pydantic Settings v2** for configuration management with `.env` file and environment variable support
+- Singleton pattern for the connection client to avoid repeated handshakes
+- Python 3.13+ support
+
+---
+
+[Unreleased]: https://github.com/your-username/clickhawk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/your-username/clickhawk/releases/tag/v0.1.0

clickhawk-0.1.0/CHANGELOG_CN.md

@@ -0,0 +1,41 @@
+> English version: [CHANGELOG.md](CHANGELOG.md)
+
+# 更新日志
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/) 格式，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+---
+
+## [未发布]
+
+### 计划中
+- `ch explain` — 彩色树形 EXPLAIN PLAN 输出
+- `ch schema diff` — 对比两个 ClickHouse 环境的 schema 差异
+- `ch migrate run/status` — 基于文件的 schema 迁移管理
+
+---
+
+## [0.1.0] — 2026-03-16
+
+### 新增
+- **`ch health`** — 集群健康检查，显示版本、uptime、数据库数量和表数量
+- **`ch query <sql>`** — 执行 SQL 查询，支持 `table`（默认）/`json`/`csv` 三种输出格式，支持 `--limit` 截断行数
+- **`ch profile <sql>`** — 查询性能分析，通过 `system.query_log` 提取真实执行统计（wall time、DB 耗时、读取行数/字节数、内存、parts/ranges 命中数）
+- **`ch slowlog`** — 慢查询历史排行，支持 `--top`、`--threshold`（毫秒）、`--hours` 参数自定义
+- **`ch schema show <table>`** — 展示表结构（列名/类型/默认值/注释），支持 `--database` 过滤
+- **`ch schema tables`** — 列出所有用户表，展示数据库、引擎、磁盘大小和行数，支持 `--database` 过滤
+- **`ch monitor`** — 实时 Live Dashboard，轮询 `system.processes`，超时查询以颜色区分（>5s 黄色，>30s 红色），支持 `--interval` 自定义刷新频率
+- **`ch migrate run/status`** — 占位命令，v0.2 正式实现
+
+### 技术基础
+- 基于 **Typer** 构建 CLI 框架，命令入口为 `ch`
+- 使用 **Rich** 渲染彩色表格和 Live 实时刷新
+- 通过 **clickhouse-connect** 连接 ClickHouse（HTTP 协议）
+- 使用 **Pydantic Settings v2** 管理配置，支持 `.env` 文件和环境变量
+- 连接客户端采用单例模式，避免重复握手
+- 支持 Python 3.13+
+
+---
+
+[未发布]: https://github.com/your-username/clickhawk/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/your-username/clickhawk/releases/tag/v0.1.0

clickhawk-0.1.0/LESSONS_LEARNED.md

@@ -0,0 +1,245 @@
+> 中文版: [LESSONS_LEARNED_CN.md](LESSONS_LEARNED_CN.md)
+
+# Lessons Learned
+
+Pitfalls encountered and lessons learned during ClickHawk development, for reference by future developers and contributors.
+
+---
+
+## 1. macOS Gatekeeper Blocking ClickHouse Binaries Installed via Homebrew Tap
+
+**Problem:**
+After installing via `brew tap clickhouse/clickhouse && brew install clickhouse`, executing `clickhouse` in the terminal produces an error stating "cannot be opened because the developer cannot be verified", or the binary is silently blocked by macOS.
+
+**Root Cause:**
+The official ClickHouse tap installs a pre-compiled binary. macOS Gatekeeper adds a quarantine attribute to binaries that have not been notarized by Apple, preventing them from running.
+
+**Solution:**
+```bash
+xattr -d com.apple.quarantine $(which clickhouse)
+```
+
+Takes effect immediately without requiring a restart.
+
+**Appendix: `brew services start clickhouse` Error**
+The `clickhouse/clickhouse` tap installs a single-file binary without registering a Homebrew service (no launchd plist), so `brew services` cannot manage it.
+The correct way to start it is to run it directly (a complete config.xml must be provided — see next item):
+```bash
+clickhouse server --config-file=$HOME/clickhouse-config.xml &
+```
+
+**`ch slowlog` / `ch profile` Reporting `Unknown table 'system.query_log'`**
+When `config.xml` lacks a `<query_log>` configuration block, ClickHouse does not create the `system.query_log` table (lazy initialization), causing slowlog and profile commands to fail. Solution: add a `<query_log>` node to `config.xml` and set `<log_queries>1</log_queries>` in the default profile.
+
+**A minimal working `config.xml` must include profiles/users/quotas**, otherwise the error `Settings profile 'default' not found` (exit 180) will occur. Path and port configuration alone is insufficient — ClickHouse looks for the `default` profile at startup:
+```xml
+<clickhouse>
+    <path>...</path>
+    <tmp_path>...</tmp_path>
+    <tcp_port>9000</tcp_port>
+    <http_port>8123</http_port>
+    <listen_host>127.0.0.1</listen_host>
+    <profiles>
+        <default><max_memory_usage>10000000000</max_memory_usage></default>
+    </profiles>
+    <users>
+        <default>
+            <password></password>
+            <networks><ip>::/0</ip></networks>
+            <profile>default</profile>
+            <quota>default</quota>
+        </default>
+    </users>
+    <quotas>
+        <default>
+            <interval>
+                <duration>3600</duration>
+                <queries>0</queries><errors>0</errors>
+                <result_rows>0</result_rows><read_rows>0</read_rows>
+                <execution_time>0</execution_time>
+            </interval>
+        </default>
+    </quotas>
+</clickhouse>
+```
+
+---
+
+## 2. Typer 0.12+: Options Cannot Follow Positional Arguments in Sub-Apps
+
+**Problem:**
+`ch query 'SELECT ...' --format json` reports `Missing argument 'SQL'`, while `ch query --format json 'SELECT ...'` works correctly.
+
+**Root Cause:**
+In Typer 0.12+ when using `add_typer()` for nested sub-apps, the sub-app's callback does not allow options (e.g., `--format`) to appear after positional arguments (e.g., SQL) by default — which is counter-intuitive.
+
+**Solution:**
+Add `context_settings={"allow_interspersed_args": True}` to each sub-app that combines positional arguments with options:
+```python
+app = typer.Typer(help="...", context_settings={"allow_interspersed_args": True})
+```
+Affected commands: `query`, `profile`, `slowlog`, `monitor`.
+
+---
+
+## 3. ClickHouse 26.x Crashes on macOS ARM64 Without a Config File
+
+**Problem:**
+Running `./clickhouse server &` on macOS Apple Silicon causes the server to crash immediately with exit code 91 and the error:
+
+```
+DB::Exception: Poco::Exception. Code: 1000, e.code() = 0, Null pointer
+DB::Context::setClustersConfig ... CANNOT_LOAD_CONFIG
+```
+
+**Root Cause:**
+ClickHouse 26.3 (and some 26.x versions) triggers a null pointer crash in `setClustersConfig` when starting in embedded config mode (without a `config.xml`) on macOS ARM64. This is a known ClickHouse bug, not a system or permissions issue.
+
+**Solutions:**
+
+Option 1 (recommended): Use Docker to avoid configuration issues entirely:
+```bash
+docker run -d --name clickhouse-local \
+  -p 8123:8123 -p 9000:9000 \
+  --ulimit nofile=262144:262144 \
+  clickhouse/clickhouse-server
+```
+
+Option 2: Provide a minimal `config.xml` to work around the bug:
+```bash
+mkdir -p ~/clickhouse-data/{data,logs,tmp}
+cat > config.xml << 'EOF'
+<clickhouse>
+    <path>clickhouse-data/data/</path>
+    <tmp_path>clickhouse-data/tmp/</tmp_path>
+    <tcp_port>9000</tcp_port>
+    <http_port>8123</http_port>
+    <listen_host>127.0.0.1</listen_host>
+</clickhouse>
+EOF
+./clickhouse server --config-file=config.xml &
+```
+
+**Takeaway:**
+The official single-file binary is unstable on macOS (especially newer versions). Docker is the preferred approach for local development. On Linux, single-file mode generally works without this issue.
+
+---
+
+## 4. Delayed Writes to `system.query_log`
+
+**Problem:**
+In the `ch profile` command, querying `system.query_log` immediately after executing a query returns empty results, causing performance statistics to not display.
+
+**Root Cause:**
+ClickHouse's `query_log` is not written synchronously. There is an asynchronous flush delay after a query completes (typically 100–500ms, depending on server load and configuration).
+
+**Solution:**
+After executing the target query, call `time.sleep(0.3)` to wait 300ms before querying `system.query_log`. This is a trade-off: too short a wait risks missing data, while too long a wait degrades user experience.
+
+```python
+client.query(sql, settings={"log_queries": 1, "query_id": query_id})
+time.sleep(0.3)  # wait for async query_log flush
+stats = client.query(f"SELECT ... FROM system.query_log WHERE query_id = '{query_id}'")
+```
+
+**Takeaway:**
+ClickHouse system tables (`system.query_log`, `system.part_log`, etc.) are typically written asynchronously. Do not assume they are immediately consistent. If you encounter empty results, delayed writes should be the first thing to investigate.
+
+---
+
+## 5. Accessing `ProfileEvents` Fields
+
+**Problem:**
+The `ProfileEvents` field in `system.query_log` is of type `Map(String, UInt64)`. Accessing a specific key requires the `ProfileEvents['KeyName']` syntax, not dot notation.
+
+**Correct usage:**
+```sql
+SELECT
+    ProfileEvents['SelectedParts'] AS parts_selected,
+    ProfileEvents['SelectedRanges'] AS ranges_selected
+FROM system.query_log
+WHERE query_id = '...'
+```
+
+**Commonly used ProfileEvents keys:**
+- `SelectedParts` — number of parts hit by the query (fewer is better, indicating effective partition pruning)
+- `SelectedRanges` — number of ranges hit
+- `SelectedMarks` — number of marks hit (related to index granularity)
+- `RealTimeMicroseconds` — actual elapsed time in microseconds
+- `UserTimeMicroseconds` — user-space CPU time
+
+---
+
+## 6. Conflict Between Typer Sub-Commands and `callback`
+
+**Problem:**
+In Typer, if a sub-app has both `@app.callback(invoke_without_command=True)` and `@app.command()` sub-commands, command routing becomes confused.
+
+**Context:**
+The `schema` command has two sub-commands `show` and `tables`, while `query`, `profile`, and other commands run directly (no sub-commands).
+
+**Solution:**
+- Direct-execution commands (`query`, `profile`, `slowlog`, `monitor`): use `@app.callback(invoke_without_command=True)`
+- Multi-sub-command commands (`schema`, `migrate`): define sub-commands using standard `@app.command()`, without a callback
+
+This keeps routing clean, and both `ch query "..."` and `ch schema show table_name` work correctly.
+
+---
+
+## 7. Rich `Live` and `Console` Compatibility
+
+**Problem:**
+In `ch monitor`, calling `console.print()` outside the `Live` context causes output to intermix with Live-refreshed content, resulting in a garbled terminal display.
+
+**Solution:**
+All content that needs to be shown during a Live refresh should be delivered by returning a new `Table` object via `live.update(new_table)`. Do not call `console.print()` directly inside a `Live` context.
+
+---
+
+## 8. `clickhouse-connect` Result Set Row Access
+
+**Problem:**
+`clickhouse-connect` query results support multiple access patterns that are easy to confuse:
+- `result.result_rows` — returns `List[tuple]`, iterable row by row
+- `result.first_row` — returns the first row as a `tuple` (note: raises `IndexError` if the result is empty)
+- `result.row_count` — returns the number of rows
+
+**Takeaway:**
+Always check `result.row_count > 0` before accessing `result.first_row`, otherwise the command will crash when no query record exists (e.g., when `profile` cannot find the corresponding record in `query_log`).
+
+```python
+if stats.row_count > 0:
+    row = stats.first_row
+    # safe access to row[0], row[1], ...
+else:
+    # handle gracefully
+```
+
+---
+
+## 9. Pydantic Settings `env_prefix` Behavior
+
+**Problem:**
+The configuration class uses `env_prefix = "CH_"`, meaning all environment variables must be prefixed with `CH_` (`CH_HOST`, `CH_PORT`, etc.). The `.env` file can sometimes be missing the prefix or use incorrect casing.
+
+**Takeaway:**
+- Pydantic Settings v2 reads environment variables case-insensitively by default
+- Variables in the `.env` file must include the prefix (`CH_HOST=localhost`), not the bare field name (`HOST=localhost`)
+- It is recommended to list all variables in `.env.example` to prevent users from missing any
+
+---
+
+## 10. Wheel Package Path Configuration in `pyproject.toml`
+
+**Problem:**
+`pyproject.toml` had `[tool.hatch.build.targets.wheel]` configured with `packages = ["src/clickhawk"]`, but the actual code structure places the code in `clickhawk/` (not `src/clickhawk/`), causing the package to not be found after `pip install`.
+
+**Solution:**
+Ensure the package path matches the actual directory structure. If the code is in `clickhawk/` (a same-name package at the project root), the configuration should be:
+```toml
+[tool.hatch.build.targets.wheel]
+packages = ["clickhawk"]
+```
+
+**Takeaway:**
+Before publishing to PyPI, always install with `pip install -e .` and run `ch --help` to verify that commands are registered correctly — do not rely solely on checking `pyproject.toml` syntax.

clickhawk-0.1.0/LESSONS_LEARNED_CN.md

@@ -0,0 +1,245 @@
+> English version: [LESSONS_LEARNED.md](LESSONS_LEARNED.md)
+
+# 调试经验记录（Lessons Learned）
+
+开发 ClickHawk 过程中踩过的坑和学到的经验，供后续开发和贡献者参考。
+
+---
+
+## 1. macOS Gatekeeper 拦截 Homebrew tap 安装的 ClickHouse 二进制
+
+**问题描述：**
+通过 `brew tap clickhouse/clickhouse && brew install clickhouse` 安装后，终端执行 `clickhouse` 报错"无法打开，因为无法验证开发者"，或者直接被 macOS 静默拦截。
+
+**根本原因：**
+ClickHouse 官方 tap 安装的是预编译二进制，macOS Gatekeeper 会对未经 Apple 公证的二进制添加隔离标记（quarantine attribute），阻止其运行。
+
+**解决方案：**
+```bash
+xattr -d com.apple.quarantine $(which clickhouse)
+```
+
+执行后无需重启，立即生效。
+
+**附：`brew services start clickhouse` 报错问题**
+`clickhouse/clickhouse` tap 安装的是单文件二进制，没有注册 Homebrew service（没有 launchd plist），所以 `brew services` 无法管理它。
+正确的启动方式是直接运行（需提供完整 config.xml，见下一条）：
+```bash
+clickhouse server --config-file=$HOME/clickhouse-config.xml &
+```
+
+**`ch slowlog` / `ch profile` 报 `Unknown table 'system.query_log'`**
+config.xml 缺少 `<query_log>` 配置时，ClickHouse 不会创建 `system.query_log` 表（懒加载），导致 slowlog 和 profile 命令报错。解决方案：在 config.xml 中加入 `<query_log>` 节点并在 default profile 中设置 `<log_queries>1</log_queries>`。
+
+**最小可用 config.xml 必须包含 profiles/users/quotas**，否则会报 `Settings profile 'default' not found`（exit 180）。仅有路径和端口配置不够，ClickHouse 启动时会查找 `default` profile：
+```xml
+<clickhouse>
+    <path>...</path>
+    <tmp_path>...</tmp_path>
+    <tcp_port>9000</tcp_port>
+    <http_port>8123</http_port>
+    <listen_host>127.0.0.1</listen_host>
+    <profiles>
+        <default><max_memory_usage>10000000000</max_memory_usage></default>
+    </profiles>
+    <users>
+        <default>
+            <password></password>
+            <networks><ip>::/0</ip></networks>
+            <profile>default</profile>
+            <quota>default</quota>
+        </default>
+    </users>
+    <quotas>
+        <default>
+            <interval>
+                <duration>3600</duration>
+                <queries>0</queries><errors>0</errors>
+                <result_rows>0</result_rows><read_rows>0</read_rows>
+                <execution_time>0</execution_time>
+            </interval>
+        </default>
+    </quotas>
+</clickhouse>
+```
+
+---
+
+## 2. Typer 0.12+ 子 app 中选项不能放在位置参数之后
+
+**问题描述：**
+`ch query 'SELECT ...' --format json` 报 `Missing argument 'SQL'`，而 `ch query --format json 'SELECT ...'` 正常。
+
+**根本原因：**
+Typer 0.12+ 使用 `add_typer()` 嵌套子 app 时，子 app 的 callback 默认不允许选项（`--format`）出现在位置参数（SQL）之后，与用户直觉相反。
+
+**解决方案：**
+在每个有位置参数 + 选项组合的子 app 上加 `context_settings={"allow_interspersed_args": True}`：
+```python
+app = typer.Typer(help="...", context_settings={"allow_interspersed_args": True})
+```
+受影响的命令：`query`、`profile`、`slowlog`、`monitor`。
+
+---
+
+## 3. ClickHouse 26.x 在 macOS ARM64 上无配置文件启动崩溃
+
+**问题描述：**
+在 macOS Apple Silicon 上执行 `./clickhouse server &`，服务端立即 crash 并 exit 91，错误信息为：
+
+```
+DB::Exception: Poco::Exception. Code: 1000, e.code() = 0, Null pointer
+DB::Context::setClustersConfig ... CANNOT_LOAD_CONFIG
+```
+
+**根本原因：**
+ClickHouse 26.3（及部分 26.x 版本）在 macOS ARM64 上以 embedded config（无 `config.xml`）模式启动时，`setClustersConfig` 内部触发 null pointer crash。这是 ClickHouse 的已知 bug，不是系统或权限问题。
+
+**解决方案：**
+
+方案 1（推荐）：使用 Docker，完全规避配置问题：
+```bash
+docker run -d --name clickhouse-local \
+  -p 8123:8123 -p 9000:9000 \
+  --ulimit nofile=262144:262144 \
+  clickhouse/clickhouse-server
+```
+
+方案 2：提供最小 `config.xml` 绕过 bug：
+```bash
+mkdir -p ~/clickhouse-data/{data,logs,tmp}
+cat > config.xml << 'EOF'
+<clickhouse>
+    <path>clickhouse-data/data/</path>
+    <tmp_path>clickhouse-data/tmp/</tmp_path>
+    <tcp_port>9000</tcp_port>
+    <http_port>8123</http_port>
+    <listen_host>127.0.0.1</listen_host>
+</clickhouse>
+EOF
+./clickhouse server --config-file=config.xml &
+```
+
+**经验：**
+官方单文件二进制在 macOS 上不稳定（尤其是新版本），本地开发首选 Docker；Linux 上单文件模式通常没有此问题。
+
+---
+
+## 2. `system.query_log` 的延迟写入问题
+
+**问题描述：**
+在 `ch profile` 命令中，执行完查询后立即查询 `system.query_log` 会得到空结果，导致性能统计不显示。
+
+**根本原因：**
+ClickHouse 的 `query_log` 不是同步写入的，查询结束后有一段异步刷新延迟（通常 100~500ms，取决于服务器负载和配置）。
+
+**解决方案：**
+在执行完目标查询后，`time.sleep(0.3)` 等待 300ms 再查询 `system.query_log`。这是一个权衡：等待时间太短会漏掉数据，太长会影响用户体验。
+
+```python
+client.query(sql, settings={"log_queries": 1, "query_id": query_id})
+time.sleep(0.3)  # 等待 query_log 异步刷新
+stats = client.query(f"SELECT ... FROM system.query_log WHERE query_id = '{query_id}'")
+```
+
+**经验：**
+ClickHouse 的系统表（`system.query_log`、`system.part_log` 等）通常是异步写入的，不要假设它们是实时一致的。如果遇到空结果，优先考虑写入延迟问题。
+
+---
+
+## 2. `ProfileEvents` 字段访问方式
+
+**问题描述：**
+`system.query_log` 中的 `ProfileEvents` 是一个 `Map(String, UInt64)` 类型字段，访问特定 key 需要用 `ProfileEvents['KeyName']` 语法，而不是点号。
+
+**正确写法：**
+```sql
+SELECT
+    ProfileEvents['SelectedParts'] AS parts_selected,
+    ProfileEvents['SelectedRanges'] AS ranges_selected
+FROM system.query_log
+WHERE query_id = '...'
+```
+
+**常用的 ProfileEvents key：**
+- `SelectedParts` — 查询命中的 part 数量（越少越好，说明分区剪枝有效）
+- `SelectedRanges` — 命中的 range 数量
+- `SelectedMarks` — 命中的 mark 数量（与 index granularity 相关）
+- `RealTimeMicroseconds` — 实际耗时（微秒）
+- `UserTimeMicroseconds` — 用户态 CPU 耗时
+
+---
+
+## 3. Typer 子命令与 `callback` 的冲突
+
+**问题描述：**
+在 Typer 中，如果一个子 app 既有 `@app.callback(invoke_without_command=True)` 又有 `@app.command()` 子命令，会出现命令路由混乱的问题。
+
+**场景：**
+`schema` 命令有两个子命令 `show` 和 `tables`，而 `query`、`profile` 等命令是直接运行的（没有子命令）。
+
+**解决方案：**
+- 直接运行型命令（`query`、`profile`、`slowlog`、`monitor`）：使用 `@app.callback(invoke_without_command=True)`
+- 多子命令型命令（`schema`、`migrate`）：使用普通的 `@app.command()` 定义子命令，不用 callback
+
+这样路由清晰，`ch query "..."` 和 `ch schema show table_name` 都能正常工作。
+
+---
+
+## 4. Rich `Live` 与 `Console` 的兼容性
+
+**问题描述：**
+在 `ch monitor` 中，如果在 `Live` 上下文之外调用 `console.print()`，输出会和 Live 刷新的内容混在一起，造成终端显示错乱。
+
+**解决方案：**
+所有需要在 Live 刷新期间显示的内容，都通过返回新的 `Table` 对象来更新（`live.update(new_table)`），不要在 Live 上下文内直接调用 `console.print()`。
+
+---
+
+## 5. `clickhouse-connect` 结果集的行访问方式
+
+**问题描述：**
+`clickhouse-connect` 的查询结果有多种访问方式，容易搞混：
+- `result.result_rows` — 返回 `List[tuple]`，逐行迭代
+- `result.first_row` — 返回第一行的 `tuple`（注意：结果为空时会抛 `IndexError`）
+- `result.row_count` — 返回行数
+
+**经验：**
+在访问 `result.first_row` 之前，务必先检查 `result.row_count > 0`，否则在没有查询记录时（如 `profile` 命令在 `query_log` 中找不到对应记录时）会直接崩溃。
+
+```python
+if stats.row_count > 0:
+    row = stats.first_row
+    # 安全访问 row[0], row[1], ...
+else:
+    # 优雅降级处理
+```
+
+---
+
+## 6. Pydantic Settings 的 `env_prefix` 行为
+
+**问题描述：**
+配置类使用了 `env_prefix = "CH_"`，意味着所有环境变量需要加 `CH_` 前缀（`CH_HOST`、`CH_PORT` 等）。但 `.env` 文件里有时会漏掉前缀或者写错大小写。
+
+**经验：**
+- Pydantic Settings v2 默认不区分大小写读取环境变量
+- `.env` 文件中的变量名需要包含前缀（`CH_HOST=localhost`），而不是裸字段名（`HOST=localhost`）
+- 建议在 `.env.example` 中把所有变量都列出来，避免用户遗漏
+
+---
+
+## 7. `pyproject.toml` 中 wheel 打包路径的配置
+
+**问题描述：**
+`pyproject.toml` 中的 `[tool.hatch.build.targets.wheel]` 配置了 `packages = ["src/clickhawk"]`，但实际代码结构中代码在 `clickhawk/` 目录（而不是 `src/clickhawk/`），导致 `pip install` 后找不到包。
+
+**解决方案：**
+确保打包路径与实际目录结构一致。如果代码在 `clickhawk/`（项目根目录下的同名包），则配置应为：
+```toml
+[tool.hatch.build.targets.wheel]
+packages = ["clickhawk"]
+```
+
+**经验：**
+在发布 PyPI 之前，务必用 `pip install -e .` 安装后运行 `ch --help` 验证命令是否正常注册，而不只是检查 `pyproject.toml` 的语法。