This page owns the shipped ClickHouse serving path: backend selection, local bring-up, migration steps, and the configuration-only DuckDB rollback. Use it when you need to run, verify, or roll back the serving engine on a local or configured host. It does not replace the decision in ADR 0006 or the walkthrough in deployment.md.
ClickHouse is the shipped serving engine (ADR 0006, executed 2026-07-02): config/serving.yaml defaults to backend: clickhouse, make demo and docker-compose.prod.yml bring the service up by default, and the local pipeline writes the serving tables + pipeline_events journal to it (src/agentflow_runtime/processing/clickhouse_sink.py). DuckDB remains the local-dev / test and compatibility store — pytest pins it (tests/conftest.py) and the control-plane state (webhooks, alerts, outbox, usage) stays on it per ADR 0009.
Upsert model on ClickHouse: mutable serving tables are ReplacingMergeTree versioned by a MATERIALIZED af_updated_at column; an upsert is an appended row version and every backend read runs with the final=1 setting, so queries always see the latest version. The journal stays append-only MergeTree. Live verification: clickhouse-serving-verify-2026-07-02.
- Zero-dependency offline development (no container / no server available).
- Test debugging against the pytest-pinned store.
Rollback is configuration-only: SERVING_BACKEND=duckdb.
Use either the environment variable or config/serving.yaml.
backend: clickhouse
clickhouse:
host: localhost
port: 8123
user: default
password: ""
database: agentflow
secure: false
timeout_seconds: 10Environment variables override the file:
SERVING_BACKEND=clickhouse
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=8123
CLICKHOUSE_DATABASE=agentflowClickHouse is part of the default bring-up (no profile flag needed):
docker compose -f docker-compose.prod.yml up -d clickhouseThen run the API against it (clickhouse is already the default backend):
docker compose -f docker-compose.prod.yml up -d agentflow-apiThe bundled production compose file provisions a local development user:
user: agentflow
password: agentflow
The backend initializes the demo tables on first start so entity lookups and metric reads work immediately in a fresh local environment.
- Provision
ClickHouseand verifyhttp://<host>:8123/pingreturnsOk.. - Copy the serving backend config into
config/serving.yamlor set the equivalent environment variables. - Start the API with
SERVING_BACKEND=clickhouse. - Validate health at the backend layer:
from agentflow_runtime.serving.semantic_layer.catalog import DataCatalog
from agentflow_runtime.serving.semantic_layer.query_engine import QueryEngine
engine = QueryEngine(catalog=DataCatalog())
print(engine.health())- Validate read parity through the API:
curl http://localhost:8000/v1/entity/order/ORD-20260404-1001
curl "http://localhost:8000/v1/metrics/revenue?window=24h"
curl http://localhost:8000/v1/query/explain -H "Content-Type: application/json" -d "{\"question\":\"What is the revenue today?\"}"Rollback is configuration-only:
SERVING_BACKEND=duckdbor:
backend: duckdbRestart the API and it will resume serving from the existing DuckDB path without code changes.
DuckDBremains available as the compatibility store for components that still readquery_engine._conndirectly.- Task 8 only abstracts entity, metric, NL query, pagination, and backend health reads behind the new serving backend contract.