docs(db): prod schema quick-ref + ClickHouse materialization caveat

@zen-agentchecks n/achecks…zen/prod-schema-quickref-sa9d9c → master1 files · +66 −2updated 3w ago

▸Description· 1 comment · 4 noise

Description

Adds two retro-driven sections to packages/db/CLAUDE.md. Both codify prod-DB query traps that have cost multiple Zen / Cursor sessions a 400 round trip — verified against production this run.

### Prod DB Column-Naming Quick Reference — a five-row table mapping the actual prod column names of the most-queried Apollo tables (connected_accounts, auth_configs, user_org_mapping, users, trigger_instance) to their typical "Common 400" shapes:

connected_accounts has NO toolkit_slug column — must JOIN auth_configs via "authConfigId".
user_org_mapping columns are "userId" / "orgId" (camelCase, quoted), NOT organizationId.
Branded-prefix IDs (ac_*, ca_*, pr_*, ti_*, ok_*) all live in "nanoId", never id.
Soft-delete is per-table (boolean deleted vs "deletedAt").
Apollo "projectId" is UUID; Thermos trigger_messages.project_id is snake_case AND stores the nanoId (pr_*) — opposite convention.

### ClickHouse tool_execution_logs Materialization Caveat — explicitly lists the four MATERIALIZED columns derived from sessionInfo (the only ones that can be queried as bare columns), and corrects the recurring assumption that metadata.source / metadata.framework are materialized too. They are NOT — dotted access parses as (metadata).source and silently fails; use JSONExtractString(metadata, 'source'). Includes the system.columns verification query and notes that request / response are AES-encrypted (use errorRequest for substring search).

How did I test this PR

Verified every column claim against production via METABASE_POST_API_DATASET:
- db=2 (Prod Database, Postgres) — SELECT column_name, data_type FROM information_schema.columns WHERE table_schema='public' AND table_name IN ('connected_accounts','user_org_mapping'). connected_accounts returns 22 columns, none named toolkit_slug. user_org_mapping returns 7 columns with exactly "userId" / "orgId" (no organizationId).
- db=3 (Clickhouse) — SELECT name, type, default_kind, default_expression FROM system.columns WHERE database='app_db' AND table='tool_execution_logs'. Confirmed exactly four MATERIALIZED columns (session_id, sandbox_id, tool_router_session_id, request_id) — all JSONExtractString(sessionInfo, ...). metadata is plain String, no materialization.
cd apps/apollo && BYPASS_BUN_VERSION_CHECK=1 pnpm format:check /workspace/hermes/packages/db/CLAUDE.md — clean ("All matched files use the correct format").
This is a docs-only change to packages/db/CLAUDE.md; no behavioral / build / test surface affected. The cosmetic blank-line and import-grouping reflows in the same file are produced by oxfmt (canonical formatter) — running pnpm format:check confirms the result is the steady state.

Origin: cron-weekly-retro-ai-improvements / zen-cron-f638f64ebeba Triggered by: karan@composio.dev | Source: cron-weekly-retro-ai-improvements Session: https://zen-api-production-4c98.up.railway.app/dashboard/#/chat/zen-cron-f638f64ebeba

@zen-agent3w ago

Post-PR lifecycle complete

/build-checks (apollo profile): ✅ 3/3 PASS

doppler run -- pnpm lint (129.45s, 0 errors / 1 unrelated warning)
doppler run -- pnpm format:check (3.16s, 1625 files)
doppler run -- pnpm check-types (84.95s)

/codex-review-loop: ✅ LGTM after 2 iterations

Iteration 1 (P3): "Fix misleading auth_configs casing guidance" — auth_configs was claimed "All snake_case" but is mostly camelCase (22 quoted columns + 2 snake_case: toolkit_slug, toolkit_group). Verified via prod information_schema.columns and corrected the row in commit cd5548d.
Iteration 2: "The changes are documentation-only additions/formatting updates in packages/db/CLAUDE.md and do not introduce executable code paths or test-breaking behavior."

CI: ✅ 28/28 green in 501s (lint-apollo, lint-thermos, format:check, check-types, all vitest suites, all Apollo core platform reusable workflows, run-thermos-tests, Analyze go/js/python/actions, etc.).

PR comments: Only Vercel preview + reviewer-suggestion bots. No human review comments to address.

Ready for human merge. mergeStateStatus: BLOCKED is REVIEW_REQUIRED (no human approval) — not a CI blocker.

▸ 4 bot/status comments hidden

@vercel[bot]3w ago

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
apollo	Ready	Preview, Comment	May 20, 2026 12:41am

Project	Deployment	Actions	Updated (UTC)
debby	Ignored	Preview	May 20, 2026 12:41am

@github-actions[bot]3w ago

🔍 Suggested Reviewers

Based on git blame analysis of 1 file(s):

Contributor	Contribution	Files
abir-taheer

loading diff…

@zen-agent3w ago

Post-PR lifecycle complete

/build-checks (apollo profile): ✅ 3/3 PASS

doppler run -- pnpm lint (129.45s, 0 errors / 1 unrelated warning)
doppler run -- pnpm format:check (3.16s, 1625 files)
doppler run -- pnpm check-types (84.95s)

/codex-review-loop: ✅ LGTM after 2 iterations

Iteration 1 (P3): "Fix misleading auth_configs casing guidance" — auth_configs was claimed "All snake_case" but is mostly camelCase (22 quoted columns + 2 snake_case: toolkit_slug, toolkit_group). Verified via prod information_schema.columns and corrected the row in commit cd5548d.
Iteration 2: "The changes are documentation-only additions/formatting updates in packages/db/CLAUDE.md and do not introduce executable code paths or test-breaking behavior."

PR comments: Only Vercel preview + reviewer-suggestion bots. No human review comments to address.

Ready for human merge. mergeStateStatus: BLOCKED is REVIEW_REQUIRED (no human approval) — not a CI blocker.

Flag	Coverage Δ
e2e-tests	`?`
self-hosted-tests	`5.59% <ø> (ø)`
thermos-unit-tests	`?`
unit-tests	`?`

docs(db): prod schema quick-ref + ClickHouse materialization caveat

Description

How did I test this PR

Post-PR lifecycle complete

🔍 Suggested Reviewers

Description

How did I test this PR

Post-PR lifecycle complete

🔍 Suggested Reviewers

💡 Recommendation

🧪 Test Results Summary (Self-Hosted Tests)

Codecov Report