feat(clickhouse)!: storage clauses as nodes, and one introspect question per family

.github/workflows/test.yml

@@ -69,24 +69,10 @@ jobs:
           pip install -r requirements.txt
           pip install -r requirements-dev.txt
 
-      - name: Check out activerecord and testsuite (release branches)
-        uses: actions/checkout@v6
-        with:
-          repository: rhosocial/python-activerecord
-          ref: release/v1.0.0.dev30
-          path: _activerecord
-
-      - name: Check out testsuite (release branch)
-        uses: actions/checkout@v6
-        with:
-          repository: rhosocial/python-activerecord-testsuite
-          ref: release/v1.0.0.dev17
-          path: _testsuite
-
-      - name: Install activerecord and testsuite (editable)
+      - name: Install activerecord and testsuite
         run: |
-          pip install -e ./_activerecord
-          pip install -e ./_testsuite
+          pip install "rhosocial-activerecord @ git+https://github.com/rhosocial/python-activerecord.git@release/v1.0.0.dev30"
+          pip install "rhosocial-activerecord-testsuite @ git+https://github.com/rhosocial/python-activerecord-testsuite.git@fix/column-constraint-gates"
 
       - name: Verify ClickHouse connectivity
         run: |

.gitignore

@@ -213,4 +213,9 @@ tests/config/clickhouse_scenarios.yml
 
 # Claude Code temporary files (local only)
 .claude/tmp/
-.claude/plan*/
+.claude/plan*/
+# Worktrees for feature/* and fix/* branches. Never tracked: a `git add -A`
+# from the repo root would commit each branch's whole toolchain -- the venv, the
+# build directory and the test artifacts -- and the directory disappears when the
+# branch merges, so the history would keep a second copy of the source tree.
+.worktree/

AGENTS.md

@@ -66,6 +66,14 @@ and raise `UnsupportedFeatureError` instead of being emulated:
 - Mutations run with `mutations_sync=1`; `affected_rows` for UPDATE/DELETE is a
   pre-count of rows matching the WHERE predicate.
 - Optional model fields must map to `Nullable(T)` columns.
+- The CLI's `introspect` offers exactly seven types — `tables`, `views`,
+  `columns`, `indexes`, `partitions`, `table-engine`, `database` — and each is
+  gated on a dialect `supports_*` switch (exit 2 when the connected server
+  answers False). `foreign-keys` / `triggers` are absent from the vocabulary
+  because the engine has neither, which is a different statement from a
+  capability switch. The SHOW passthrough (`introspector.show`, 19 methods) is
+  library-only and deliberately not wired into `introspect`: SHOW and
+  `system.*` are not equivalent, and every introspect type reads `system.*`.
 
 ## Python Version Support
 

README.md

@@ -51,7 +51,7 @@ from pydantic import Field
 from rhosocial.activerecord.base import FieldProxy
 from rhosocial.activerecord.backend.impl.clickhouse.backend import ClickHouseBackend
 from rhosocial.activerecord.backend.impl.clickhouse.config import ClickHouseConnectionConfig
-from rhosocial.activerecord.backend.expression import CreateTableExpression
+from rhosocial.activerecord.backend.expression import CreateTableStatement
 from rhosocial.activerecord.backend.expression.statements import ColumnDefinition
 from rhosocial.activerecord.backend.expression.types import IntegerType, VarCharType
 from rhosocial.activerecord.model import ActiveRecord
@@ -80,7 +80,7 @@ User.configure(
 )
 
 dialect = User.__backend__.dialect
-User.__backend__.execute(*CreateTableExpression(
+User.__backend__.execute(*CreateTableStatement(
     dialect,
     "users",
     columns=[

changelog.d/6.added.md

@@ -0,0 +1 @@
+`partitions` and `table-engine` on the introspect CLI, `views NAME`, and storage clauses (`ENGINE`, `ORDER BY`, `PARTITION BY`, `TTL`) as expression nodes.

changelog.d/6.changed.md

@@ -0,0 +1 @@
+The introspect type list excludes `foreign-keys` and `triggers` because the engine has neither, and derives the rest from `_TYPE_CAPABILITIES`. `--async` is refused with a sentence rather than reached.

changelog.d/6.fixed.md

@@ -0,0 +1 @@
+The async introspect handler called five methods no introspector class has; the relation kind is reported as the server answers it.

changelog.d/6.internal.md

@@ -0,0 +1 @@
+The CLI tests exercise every declared type in both paths, and CI installs core from `release/v1.0.0.dev30` now that core #127 has merged.

docs/en_US/cli/README.md

@@ -59,11 +59,18 @@ Introspect the schema via `system.*` tables.
 ```bash
 $ python -m rhosocial.activerecord.backend.impl.clickhouse introspect tables \
     --host localhost --database test_db --user root --password password
+
+$ python -m rhosocial.activerecord.backend.impl.clickhouse introspect views daily_totals \
+    --host localhost --database test_db --user root --password password
 ```
 
-Positional argument (introspection type): `tables`/`views`/`table`/`columns`/`indexes`/`foreign-keys`/`triggers`/`database`. `foreign-keys`/`triggers` return empty for ClickHouse (not supported).
+Positional argument (introspection type): `tables` / `views` / `columns` / `indexes` / `partitions` / `table-engine` / `database`.
+
+`NAME` is a table for `columns` / `indexes` / `partitions` / `table-engine`, and the view itself for `views`. `tables` / `database` answer for the whole database and **refuse** a name (exit 2) rather than print a listing that looks narrowed. Exit 1 means the run failed — a connection or query error, or a view name that does not exist.
+
+`foreign-keys` / `triggers` are not offered at all: ClickHouse has neither, so the type is absent from this backend's vocabulary instead of being answered with an empty list. Every offered type is gated on a dialect capability switch; a server that answers `False` for it is refused with exit 2 and `Error: <type> introspection is not supported by this server`. The backend's `show.*` SHOW passthrough is not exposed here either: `SHOW` and `system.*` are not equivalent, and every introspection type reads `system.*`.
 
-Specific arguments: `--schema SCHEMA`, `--include-system` (include system tables).
+Specific arguments: `--include-system` (include system tables).
 
 ## status — server status
 

docs/en_US/ddl/table_engine.md

@@ -2,7 +2,7 @@
 
 ClickHouse DDL consists of clauses such as `ENGINE`, `ORDER BY`, `PARTITION BY`, `TTL`, `PRIMARY KEY`, `SAMPLE BY`, and `SETTINGS`. This backend supports them natively at the dialect layer and can generate them through the core library's DDL expressions — **full SQL semantic coverage**, no hand-written SQL required.
 
-> 📐 This backend inherits and extends the core library's `CreateTableExpression`: declaring ClickHouse clauses through the `storage_options` dictionary, with `to_sql()` generating complete native ClickHouse DDL.
+> 📐 This backend extends the core library's `CreateTableStatement` with its own options node: the clauses are declared as **expression nodes** on `ClickHouseCreateTableOptions(table_storage_options=...)`, and `to_sql()` generates complete native ClickHouse DDL.
 
 ## MergeTree Family
 
@@ -29,16 +29,15 @@ The backend maps the model's `__primary_key__` to the `ORDER BY` sorting key.
 
 ## DDL Expression vs Raw SQL Comparison
 
-Both approaches generate **exactly the same** ClickHouse DDL, demonstrating that the expressions cover all SQL semantics:
+Both approaches produce the **same** ClickHouse DDL, demonstrating that the expressions cover the SQL semantics:
 
 ### Raw SQL
 
 ```sql
 CREATE TABLE IF NOT EXISTS events (
-    ts DateTime64(6, 'UTC'),
+    ts DateTime64(6),
     id Int64,
-    url String,
-    INDEX idx_url url TYPE bloom_filter GRANULARITY 4
+    url String
 ) ENGINE = MergeTree
 PARTITION BY toYYYYMM(ts)
 ORDER BY (ts, id)
@@ -49,52 +48,107 @@ SETTINGS enable_block_number_column = 1, enable_block_offset_column = 1;
 ### DDL Expression (equivalent)
 
 ```python
+from rhosocial.activerecord.backend.expression.core import Column, FunctionCall
+from rhosocial.activerecord.backend.expression.objects import Table
+from rhosocial.activerecord.backend.expression.operators import RawSQL
 from rhosocial.activerecord.backend.expression.statements import (
-    CreateTableExpression, ColumnDefinition, IndexDefinition,
+    ColumnDefinition,
+    CreateTableStatement,
 )
-from rhosocial.activerecord.backend.expression.parts import IndexType
 from rhosocial.activerecord.backend.impl.clickhouse.expression import (
-    ClickHouseInt64Type, ClickHouseStringType, ClickHouseDateTime64Type,
+    ClickHouseCreateTableOptions,
+    ClickHouseDateTime64Type,
+    ClickHouseEngineSpec,
+    ClickHouseInt64Type,
+    ClickHouseSetting,
+    ClickHouseStorageOptionKind,
+    ClickHouseStringType,
+    ClickHouseTableStorageOption,
 )
 
-expr = CreateTableExpression(
-    dialect=dialect,
-    table="events",
-    columns=[
-        ColumnDefinition(name="ts", data_type=ClickHouseDateTime64Type(6)),
-        ColumnDefinition(name="id", data_type=ClickHouseInt64Type()),
-        ColumnDefinition(name="url", data_type=ClickHouseStringType()),
+kind = ClickHouseStorageOptionKind
+
+storage = [
+    ClickHouseTableStorageOption(
+        dialect, kind.ENGINE, value=ClickHouseEngineSpec(dialect, "MergeTree")
+    ),
+    ClickHouseTableStorageOption(
+        dialect,
+        kind.PARTITION_BY,
+        value=[FunctionCall(dialect, "toYYYYMM", Column(dialect, "ts"))],
+    ),
+    ClickHouseTableStorageOption(
+        dialect, kind.ORDER_BY, value=[Column(dialect, "ts"), Column(dialect, "id")]
+    ),
+    ClickHouseTableStorageOption(
+        dialect, kind.TTL, value=RawSQL(dialect, "ts + INTERVAL 90 DAY DELETE")
+    ),
+    ClickHouseTableStorageOption(
+        dialect,
+        kind.SETTINGS,
+        value=[
+            ClickHouseSetting(dialect, "enable_block_number_column", 1),
+            ClickHouseSetting(dialect, "enable_block_offset_column", 1),
+        ],
+    ),
+]
+
+expr = CreateTableStatement(
+    dialect,
+    Table(dialect, "events"),
+    [
+        ColumnDefinition(dialect, "ts", ClickHouseDateTime64Type(dialect, precision=6)),
+        ColumnDefinition(dialect, "id", ClickHouseInt64Type(dialect)),
+        ColumnDefinition(dialect, "url", ClickHouseStringType(dialect)),
     ],
-    indexes=[
-        IndexDefinition(name="idx_url", columns=["url"], index_type="bloom_filter",
-                       dialect_options={"granularity": 4}),
-    ],
-    storage_options={
-        "ENGINE": "MergeTree",
-        "PARTITION BY": "toYYYYMM(ts)",
-        "ORDER BY": ["ts", "id"],
-        "TTL": "ts + INTERVAL 90 DAY DELETE",
-        "SETTINGS": "enable_block_number_column = 1, enable_block_offset_column = 1",
-    },
     if_not_exists=True,
+    table_options=ClickHouseCreateTableOptions(dialect, table_storage_options=storage),
 )
-sql, _ = expr.to_sql()      # 与上方原始 SQL 等价
-dialect.execute(sql)
+sql, params = expr.to_sql()
+dialect.execute(sql, params)
+```
+
+Generated SQL (one line; ClickHouse accepts either form):
+
+```sql
+CREATE TABLE IF NOT EXISTS `events` (`ts` DateTime64(6), `id` Int64, `url` String)
+ENGINE = MergeTree PARTITION BY TOYYYYMM(`ts`) ORDER BY (`ts`, `id`)
+TTL ts + INTERVAL 90 DAY DELETE
+SETTINGS enable_block_number_column = 1, enable_block_offset_column = 1
 ```
 
-### Supported `storage_options` keys
+## Storage Clause Nodes
+
+One clause is one `ClickHouseTableStorageOption`. Which payload shape it takes is decided by its `option` member, and the renderer owns the keyword — the caller never writes SQL text for a clause:
+
+| `option` | `value` | renders as |
+|-----|--------|--------|
+| `ENGINE` | `ClickHouseEngineSpec` | `ENGINE = MergeTree`, `ENGINE = ReplacingMergeTree(version)` |
+| `PRIMARY KEY` | list of expression nodes | `PRIMARY KEY (a, b)` |
+| `PARTITION BY` | list of expression nodes | `PARTITION BY toYYYYMM(ts)` |
+| `ORDER BY` | list of expression nodes | `ORDER BY (ts, id)` |
+| `SAMPLE BY` | one expression node | `SAMPLE BY cityHash64(user_id)` |
+| `TTL` | one expression node | `TTL ts + INTERVAL 90 DAY DELETE` |
+| `SETTINGS` | list of `ClickHouseSetting` | `SETTINGS index_granularity = 8192` |
 
-`format_table_engine_clauses` accepts (case/underscore insensitive, values inserted as-is):
+Three rules the renderer enforces:
 
-| key | renders as |
-|-----|--------|
-| `ENGINE` | `ENGINE = <value>` |
-| `ORDER BY` | `ORDER BY (col1, col2)` |
-| `PARTITION BY` | `PARTITION BY <expr>` |
-| `PRIMARY KEY` | `PRIMARY KEY (...)` |
-| `SAMPLE BY` | `SAMPLE BY <expr>` |
-| `TTL` | `TTL <expr>` |
-| `SETTINGS` | `SETTINGS k = v, ...` |
+- **Canonical order.** Clauses are emitted in ClickHouse's grammar order (`ENGINE` → `PRIMARY KEY` → `PARTITION BY` → `ORDER BY` → `SAMPLE BY` → `TTL` → `SETTINGS`) regardless of the order you declared them in.
+- **One clause, once.** Declaring the same `option` twice raises `ValueError` at construction instead of rendering a statement ClickHouse would reject.
+- **A single node needs no parentheses.** `ORDER BY id` and `ORDER BY (ts, id)` are both valid; the renderer parenthesises only when there is more than one expression.
+
+`ON CLUSTER` is not a storage clause: it sits between the table name and the column list, so it is declared on the options node next to the clauses:
+
+```python
+table_options=ClickHouseCreateTableOptions(
+    dialect,
+    on_cluster="analytics_cluster",
+    table_storage_options=storage,
+)
+# CREATE TABLE `events` ON CLUSTER `analytics_cluster` (...) ENGINE = MergeTree ...
+```
+
+> ⚠️ The core `CreateTableStatement(storage_options=...)` slot is **refused by name** in this backend: ClickHouse has no generic `WITH (...)` storage-options clause, and accepting the dict would render a statement that silently differs from what the caller wrote. The error names `ClickHouseCreateTableOptions` as the replacement.
 
 > 💡 *AI prompt: "`ReplacingMergeTree` dedup is eventually consistent; how does the caller ensure it reads the latest version when querying? What is the cost of the `FINAL` keyword?"*
 
@@ -119,17 +173,22 @@ Expired data is automatically deleted; commonly used for log/event tables.
 This backend supports `ALTER TABLE` ADD/DROP COLUMN (including `IF EXISTS`/`IF NOT EXISTS`), MODIFY COLUMN, etc.:
 
 ```python
+from rhosocial.activerecord.backend.expression.objects import Table
 from rhosocial.activerecord.backend.expression.statements import (
-    AlterTableExpression, AlterColumn, ColumnAlterOperation,
+    AddColumnAction, AlterTableStatement, ColumnDefinition,
+)
+from rhosocial.activerecord.backend.impl.clickhouse.expression import ClickHouseStringType
+
+expr = AlterTableStatement(
+    dialect,
+    Table(dialect, "events"),
+    [AddColumnAction(dialect, ColumnDefinition(dialect, "country", ClickHouseStringType(dialect)))],
 )
-expr = AlterTableExpression(dialect, "users", [
-    AlterColumn("col", ColumnAlterOperation.SET_DEFAULT, new_value="ABC"),
-])
 sql, _ = expr.to_sql()
-# ALTER TABLE users ALTER COLUMN col SET DEFAULT 'ABC'
+# ALTER TABLE `events` ADD COLUMN `country` String
 ```
 
-See the DDL comparison in [First CRUD application](../getting_started/first_crud.md).
+See the DDL comparison in [First CRUD application](../getting_started/first_crud.md), and [Skip indexes](skip_indexes.md) for inline `INDEX` clauses.
 
 ## Next steps
 

docs/en_US/getting_started/first_crud.md

@@ -44,22 +44,22 @@ User.configure(config, ClickHouseBackend)
 ## 2. Create the table (DDL expression vs raw SQL)
 
 ClickHouse does not auto-create tables. This backend **inherits and extends** the
-core library's DDL expressions: `CreateTableExpression` can generate complete
+core library's DDL expressions: `CreateTableStatement` can generate complete
 native ClickHouse DDL. The two approaches are equivalent:
 
 ### Approach A: DDL expression (recommended, type-safe, serializable)
 
 ```python
 from rhosocial.activerecord.backend.expression.statements import (
-    CreateTableExpression, ColumnDefinition, DropTableExpression,
+    CreateTableStatement, ColumnDefinition, DropTableStatement,
 )
 from rhosocial.activerecord.backend.impl.clickhouse.expression import (
     ClickHouseInt64Type, ClickHouseStringType, ClickHouseInt32Type,
     ClickHouseNullableType, ClickHouseDateTime64Type,
 )
 
 # Declare ENGINE / ORDER BY / PARTITION BY / TTL / SETTINGS via storage_options
-expr = CreateTableExpression(
+expr = CreateTableStatement(
     dialect=User.__dialect__,
     table="users",
     columns=[

docs/en_US/getting_started/quick_start.md

@@ -69,7 +69,7 @@ SETTINGS enable_block_number_column = 1, enable_block_offset_column = 1;
 > mutations by default. See [Mutations (UPDATE/DELETE)](../capabilities/mutations.md).
 >
 > You can also generate the equivalent DDL via a DDL expression
-> (`CreateTableExpression` + `storage_options`); see
+> (`CreateTableStatement` + `storage_options`); see
 > [First CRUD application](first_crud.md#2-create-the-table-ddl-expression-vs-raw-sql).
 
 ## Key points

docs/zh_CN/cli/README.md

@@ -59,11 +59,18 @@ $ python -m rhosocial.activerecord.backend.impl.clickhouse info \
 ```bash
 $ python -m rhosocial.activerecord.backend.impl.clickhouse introspect tables \
     --host localhost --database test_db --user root --password password
+
+$ python -m rhosocial.activerecord.backend.impl.clickhouse introspect views daily_totals \
+    --host localhost --database test_db --user root --password password
 ```
 
-位置参数（自省类型）：`tables`/`views`/`table`/`columns`/`indexes`/`foreign-keys`/`triggers`/`database`。`foreign-keys`/`triggers` 对 ClickHouse 返回空（不支持）。
+位置参数（自省类型）：`tables` / `views` / `columns` / `indexes` / `partitions` / `table-engine` / `database`。
+
+`NAME` 对 `columns` / `indexes` / `partitions` / `table-engine` 是表名，对 `views` 是视图本身。`tables` / `database` 回答的是整个数据库，因此**拒绝**名字（退出 2），不会打印一份看起来被收窄过的列表。退出 1 表示运行失败——连接或查询出错，或指定的视图不存在。
+
+`foreign-keys` / `triggers` 根本不提供：ClickHouse 既没有外键也没有触发器，所以这两个类型不在本后端的词汇表里，而不是返回空列表。每个提供的类型都挂在 dialect 的能力开关上；服务端对该开关回答 `False` 时以退出 2 拒绝，并输出 `Error: <type> introspection is not supported by this server`。后端的 `show.*`（SHOW 直通）同样不从这里暴露：`SHOW` 与 `system.*` 并不等价，而所有自省类型都读 `system.*`。
 
-专属参数：`--schema SCHEMA`、`--include-system`（含系统表）。
+专属参数：`--include-system`（含系统表）。
 
 ## status — 服务器状态