v0.6.0 plan: open issues, priorities and API-team blockers #1182

Replaces #939 (v0.5.1 follow-ups) and #757 (v0.5.0, shipped 2026-10-22). Based on a triage of all open issues on 2026-11-02.

Untracked: cargo audit is failing on main

audit.yml has failed on main every day since 2026-10-29: RUSTSEC-2026-0387 in crypto-bigint 0.5.5, reached through aws-config → p256 (credentials-login feature), a dev-dependency of clickhouse-cloud-api. Shipped binaries are not affected, but it turns every PR red (#1178, #1179). Fix by trimming aws-config features or bumping it.

Stack #1153: review and merge

These close when the stack merges:

• OpenAPI drift: 68 gaps between live spec and library #1144 OpenAPI drift (18 gaps), with cloud clickpipe: accept MongoDB mongoConfig in --table-mapping-json (#1144) #1147 (MongoDB mongoConfig) and cloud clickstack: cover log source eventNameExpression and severityNumberExpression (#1144) #1148 (ClickStack log source expressions)
• Stop resolving the latest clickhousectl version through the GitHub API #1142 resolve the latest version from builds.clickhouse.com (PR fix(update): resolve the latest version from builds.clickhouse.com (#1142) #1143)
• Route Cloud Postgres handlers through CloudClient wrappers #1156 route Cloud Postgres handlers through CloudClient wrappers (PR fix(cli): route Cloud Postgres handlers through CloudClient wrappers (#1156) #1165)
• Split oversized Cloud domain modules into directories #1157 split oversized Cloud modules (services, postgres, organizations in this stack; clickpipes and clickstack still to do)
• Read-only local commands create .clickhouse/servers/.metadata.lock outside a project #1077 read-only local commands create project state (PR fix(local): stop read-only commands creating project state (#1077) #1166)
• Add local postgres list and rename local server to local clickhouse (ch) #1159 rename local server to local clickhouse, add postgres list and local status (PR feat(local): rename local server to local clickhouse; add postgres list and local status (#1159) #1169)
• Pin subcommand order in --help #1158 pin subcommand order in --help (PR docs(cli): pin subcommand order in --help (#1158) #1171)
• Write Cloud service connection settings to .env #1164 write Cloud service connection settings to .env (PR feat(cli): write Cloud service connection settings to .env (#1164) #1167)
• Finish the clickhouse-cloud-api module split: Query API, large models, test files #1173 finish the clickhouse-cloud-api module split (PRs refactor(api): move the Query API into client/query.rs (#1173) #1176–refactor(api): split ClickStack models by resource (#1173) #1181)

Note: #1149 fails spec_coverage_test on its own head (the ClickStack fields arrive in #1151), so merge the stack together rather than one PR at a time.

Ready to work, in priority order

1. Local Postgres container names collide across projects #1160 local Postgres container names collide across projects (hits parallel worktree agents)
2. Show foreign error text in local JSON errors instead of redacting it #1072 carry the other program's error text in a details field of local JSON errors instead of redacting it
3. Unify the Cloud service poll loops (delete --force and udf attach --wake) #1065 unify the Cloud service poll loops
4. Define how local ClickHouse build artifacts are installed or linked #129 install or link locally built ClickHouse binaries
5. Return next-step polling hints in JSON for asynchronous Cloud operations #1162 next-step polling hints in JSON for asynchronous Cloud operations
6. Add a status command that reports CLI, auth, project and skills context in one call #1163 one status command for CLI, auth, project and skills context (settle naming against local status from Add local postgres list and rename local server to local clickhouse (ch) #1159 first)
7. Add a command search so agents can find commands and flags by keyword #1161 command search for agents
8. Cloud access request negotiation: role discovery, OAuth org selection and approval flow #1131 Cloud access request flow (PR feat(cloud): access request flow for scoped API keys #1132 needs review)
9. Always-applied server configs: ./clickhouse/config.d (project) and ~/.clickhouse/config.d (global) #1062 always-applied config.d (settle the open questions first)
10. Local server selection: one rule for omitted names, or require a name (check telemetry first) #1064 local server selection (query telemetry first, then choose A or B)
11. Local Postgres: use the pg_clickhouse image and enable its extensions #1096 local Postgres on the pg_clickhouse image (draft PR feat(local): run local Postgres on the pg_clickhouse image #1097; weigh against the native bundle prototype in PR Prototype: native (no-Docker) local Postgres from portable bundles #1098)
12. Direct Cloud database connections with JWT auth (no password, no Query API key) #1154 direct Cloud database connections with JWT (phase 1 can start now; phases 2–3 wait on the Cloud team)
13. Design reusable connection profiles and MCP-compatible export #800 connection profiles and MCP export (POC in PR feat(mcp): mcp add / mcp run POC for mcp-clickhouse #1061)
14. Choose an explicit override for agent-detected JSON output #915 override for agent-detected JSON output (run the eval; shares a harness with Add a command search so agents can find commands and flags by keyword #1161)
15. Shell completions: decide how to serve them #1155 shell completions
16. Design opt-in global local-server data directories #250 opt-in global data directories (revisit after Always-applied server configs: ./clickhouse/config.d (project) and ~/.clickhouse/config.d (global) #1062)

Unblocked from the API-team list (2026-11-02)

Answered by reading the control-plane and backend source. Each issue has a findings comment and, where something needs changing upstream, a link to a control-plane issue. These are small help, docs and validation changes.

17. Establish supported Kafka schema-discovery authentication modes #841 require Kafka authentication locally (exit 2), matching the API
18. Verify source-kind rules before enforcing ClickPipe field mappings #845 validate that fieldMappings exactly match destination.columns, for every source kind
19. Resolve whether whole-pipe ClickPipe PATCH applies settings #824 reject settings in a whole-pipe update file and point to clickpipe settings update
20. Clarify when successful ClickPipe state requests are no-ops #926 state-command help from the real guard table; say that start on a Completed pipe has no effect
21. Confirm and fix switchover acknowledgment when no standby exists #835 rewrite switchover help: it replaces the primary with a fresh server, works without HA, and may wait for the maintenance window
22. Align Postgres API timestamp grammar and detail-selector precision #797 say that slowquery get --timestamp is ignored by the API, and correct the list window to inclusive
23. Establish the supported Postgres log severity filter values #931 upper-case --severity, list the values, and warn on unknown ones
24. Verify and document Postgres replica and restore credentials #935 document replica and restore passwords (docs only)
25. Define ClickPipe null-setting behavior across create and updates #937 document null, omit and reset semantics for settings (docs only)

In progress elsewhere

• Cut local test run time: six tests wait out real timeouts (~70s of ~2m) #1174 cut local test run time
• Remove low-value local tests and adopt a one-layer-per-behaviour test rule #1175 remove low-value local tests, one-layer-per-behaviour rule

In scope for v0.6.0, blocked on the API team

Upstream issues raised on 2026-11-02, after reading the control-plane and backend source. The CLI-side steps for #797, #824, #835, #841, #926 and #931 are in the ready list above; what remains here is the upstream part.

• Align Postgres slow-query duration schemas with fractional responses #796 slow-query duration types: spec-only fix in ClickHouse/control-plane#40265 (assigned). No CLI work; close once the spec is corrected.
• Align Postgres API timestamp grammar and detail-selector precision #797 timestamp grammar, and the detail timestamp the backend ignores: ClickHouse/control-plane#40266 (assigned).
• Define reliable Postgres create region and size diagnostics #838 typed region and size errors, plus a public capabilities endpoint: ClickHouse/control-plane#44993.
• Direct Cloud database connections with JWT auth (no password, no Query API key) #1154 phases 2–3: accept the CLI's token for database JWT exchange, or add a /v1 route: ClickHouse/control-plane#44995.
• Upstream follow-ups to the ready CLI fixes: Resolve whether whole-pipe ClickPipe PATCH applies settings #824 → ClickHouse/control-plane#44988, Define ClickPipe null-setting behavior across create and updates #937 → ClickHouse/control-plane#44989, Clarify when successful ClickPipe state requests are no-ops #926 → ClickHouse/control-plane#44990, Establish supported Kafka schema-discovery authentication modes #841 → ClickHouse/control-plane#44991, Confirm and fix switchover acknowledgment when no standby exists #835 → ClickHouse/control-plane#44992 (progress visibility), Establish the supported Postgres log severity filter values #931 → ClickHouse/control-plane#44994.
• Improve backend context when waking a stopped service #923 waking a stopped service: the error should name the current state and the next command: ClickHouse/control-plane#45002.
• Explore schema-assisted ClickPipe creation #928 schema-assisted ClickPipe creation: the backend marks virtual fields, but the public API drops the flags: ClickHouse/control-plane#44998.

Blocked elsewhere

• Support homebrew install #276 Homebrew (PR Support Homebrew install #279): waiting on the macOS signing key.

Closed in this triage

• Done: v0.5.0 release scope and acceptance checklist #757, Track v0.5.1 follow-ups, handoffs, and deferrals #939, Telemetry: record the local error code so user-input failures can be separated from CLI faults #1063 (feat(telemetry): record local failure codes as failure_kind (#1063) #1076), Mirror release archives to S3 from the release workflow #995 (ci(release): upload binaries to builds.clickhouse.com from release.yml #1115; the leftovers are noted on Stop resolving the latest clickhousectl version through the GitHub API #1142), Define automatic default server configuration and precedence #254 (superseded by Always-applied server configs: ./clickhouse/config.d (project) and ~/.clickhouse/config.d (global) #1062)
• Not planned: Investigate live u64-max service-setting readback precision #832, Confirm Query API payload limit units and enforcement #936, Define how schema discovery identifies virtual and optional fields #929 (folded into Explore schema-assisted ClickPipe creation #928), Add a live Pub/Sub ClickPipe source test with agreed GCP fixtures #206, Decide the stable exit-code taxonomy #234

🤖 Generated with Claude Code