feat: ClickHouse database setup SQL on the warehouse card and docs

[Zaimwa9]

Thanks for submitting a PR! Please check the boxes below:

• I have read the Contributing Guide.
• I have added information to docs/ if required so people know about the feature.
• I have filled in the "Changes" section below.
• I have filled in the "How did you test this code" section below.

Changes

Surfaces the one-off ClickHouse database setup SQL (events table DDL):

• Collapsible "Database setup" section on the warehouse connection card (ClickHouse only), with syntax highlighting and a copy button. The SQL interpolates the connection's configured database, so the copied statements always match what was saved. Starts expanded until the connection has received its first event, then collapses to a one-line header. (total_events_received is currently always null for ClickHouse connections — a backend follow-up will extend event stats to ClickHouse so the collapse becomes effective.)
• The same section, collapsed, inside the create/edit form — interpolating the live Database field — so users can run the setup and test the connection in one sitting.
• Canonical database name is flagsmith_exp: form default and placeholder updated (backend default to follow in the backend PR).
• New "Bring your own ClickHouse" section in the Connect a Warehouse docs with the same SQL, setup steps, and separate admin (setup) vs runtime (INSERT/SELECT) permissions guidance.

How did you test this code?

Unit tests (including snippet interpolation pinned to the form's default database), lint, typecheck (no new errors against the baseline). Manually: checked the section renders on card and form for ClickHouse only, interpolates the Database field value, copies the SQL, and collapses/expands on click.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
flagsmith-frontend-preview	Ready	Preview, Comment	Jul 29, 2026 2:38pm
flagsmith-frontend-staging	Ready	Preview, Comment	Jul 29, 2026 2:38pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Ignored	Preview	Jul 29, 2026 2:38pm

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• ✅ Review completed - (🔄 Check again to review again)

📝 Walkthrough

Walkthrough

Adds customer-managed ClickHouse support for experiment warehouses, including generated database/table DDL, updated database defaults, setup documentation, and tests. Adds expandable SQL setup help with syntax highlighting and clipboard copying to the ClickHouse configuration form and connection card.

Estimated code review effort: 3 (Moderate) | ~20 minutes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Zaimwa9]

@themis-blindfold review

[themis-blindfold]

⚖️ Themis judgement: 🟠 Fix before merge

A small, well-shaped UI + docs addition that copies the existing CodeHelp pattern faithfully — but the SQL it hands customers and the product's own defaults disagree on the database name, and the "collapse once connected" behaviour the card asks for can never happen for a ClickHouse connection. Both are cheap to fix; neither is caught by the current tests. CI was still running (Link Check Docs in progress); everything that had completed — Unit Tests, Lint changed files, CodeQL, the Vercel builds — passed.

🎯 Correctness	3/5
🧪 Test coverage	3/5
📐 Code quality	4/5
🚀 Product impact	3/5

🟠 Majors

• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/clickhouseSetupSql.ts — the setup SQL creates a database the connection form never points at.
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseConnectionCard.tsx — the setup-SQL section stays expanded forever for ClickHouse connections.
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/clickhouseSetupSql.ts — the timestamp_sane CHECK constraint on a client-supplied timestamp (unverified).

🧹 Nits

• docs/docs/experimentation/connect-a-warehouse.md — the grant guidance and the "never leaves your data platform" claim outrun what the code does with a configured connection.

📝 Walkthrough

• Setup SQL constant — new clickhouseSetupSql.ts holds the flagsmith_exp.events DDL as a single exported string.
• Warehouse card — renders a collapsible "Database setup" callout for ClickHouse connections only, reusing CalloutBar + Highlight + Utils.copyToClipboard exactly as CodeHelp does, initially expanded when no events have been received.
• Docs — new "Bring your own ClickHouse" section with the same DDL, the connection-form steps, and a note on the native protocol/TLS defaults.

🧪 How to verify

• Run the DDL against a real ClickHouse instance, then configure a connection using the form's prefilled database (flagsmith) and confirm what Test connection reports — the mismatch with flagsmith_exp is the highest-risk path.
• With a ClickHouse connection saved, load Environment Settings > Warehouse and check the response of GET .../warehouse-connections/?exclude_event_stats=false: total_events_received is null for non-Flagsmith types, which is what drives the callout's initial state.
• Insert a batch into the new table containing one row with timestamp before 2020-01-01 and confirm whether ClickHouse rejects only the row or the whole insert.
• Toggle the connection between flagsmith, snowflake and clickhouse and confirm the callout renders for ClickHouse only, expands/collapses on click, and copies the full SQL.
• Automate: a unit test asserting the DDL string's database/table name matches CLICKHOUSE_DEFAULTS.database would have caught the naming split, and would keep the docs copy honest.

Product take: Removes a genuine onboarding dead end — before this, a BYO-ClickHouse customer had no idea what table Flagsmith expected. Modest in size but high leverage for the experimentation beta, provided the database name in the snippet and the form agree.

Big picture: The events schema is now maintained in three places — the TS constant, the docs code block, and whatever component actually writes the table (not in this repo). Nothing links them, so a column added upstream silently leaves customers with a table that no longer matches. The cheapest boundary is one source for the DDL in the repo (generate or include the docs block from the constant) plus a test pinning the database/table name to CLICKHOUSE_DEFAULTS.

🧭 Assumptions & unverified claims

• The component that writes events into a customer's ClickHouse is not in this repository — no code here inserts into a configured connection (only SELECT 1 during verification), so the DDL's column names, types and codecs could not be checked against an actual writer.
• ClickHouse's behaviour on a CHECK-constraint violation (aborting the insert rather than skipping the row) was not exercised against a server in this sandbox; no network access was available to confirm it against the official documentation.
• Whether timestamp is the client-supplied event time is inferred from the presence of a separate collected_at column, not from SDK code in this repo.

Handing customers a CREATE DATABASE and then prefilling a different name is a rite of passage; better to fail it in review than in a support ticket. · reviewed at bee1624

[github-actions]

Docker builds report

Image	Build Status	Security report
ghcr.io/flagsmith/flagsmith-api-test:pr-8112	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-e2e:pr-8112	Finished ✅	Skipped
ghcr.io/flagsmith/flagsmith-api:pr-8112	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith:pr-8112	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-private-cloud:pr-8112	Finished ✅	Results ✅
ghcr.io/flagsmith/flagsmith-frontend:pr-8112	Finished ✅	Results ✅

[coderabbitai]

Actionable comments posted: 4

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ea600869-bc74-4701-a542-6a60f9f2387c

📥 Commits

Reviewing files that changed from the base of the PR and between 0668c09 and bee1624.

📒 Files selected for processing (4)

• docs/docs/experimentation/connect-a-warehouse.md
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseConnectionCard.tsx
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSetupSqlHelp.tsx
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/clickhouseSetupSql.ts

[github-actions]

✅ private-cloud · depot-ubuntu-latest-16 — run #18853 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

 2 passed

Details

 2 tests across 2 suites
 1 minute, 5 seconds
 ff57e65
 🔄 Run: #18853 (attempt 1)

🗂️ Previous results

✅ private-cloud · depot-ubuntu-latest-arm-16 — run #18853 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

 22 passed
 1 skipped

Details

 23 tests across 18 suites
 1 minute, 22 seconds
 ff57e65
 🔄 Run: #18853 (attempt 1)

Skipped tests

firefox › tests/onboarding-tests.pw.ts › Onboarding › New user connects via the single-page onboarding flow @oss

✅ oss · depot-ubuntu-latest-arm-16 — run #18853 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 47.1 seconds
 ff57e65
 🔄 Run: #18853 (attempt 1)

✅ oss · depot-ubuntu-latest-16 — run #18853 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-16)

 1 passed

Details

 1 test across 1 suite
 36.8 seconds
 ff57e65
 🔄 Run: #18853 (attempt 1)

✅ private-cloud · depot-ubuntu-latest-arm-16 — run #18847 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 1 minute, 3 seconds
 6b5e02f
 🔄 Run: #18847 (attempt 1)

✅ private-cloud · depot-ubuntu-latest-16 — run #18847 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

 1 passed

Details

 1 test across 1 suite
 47.9 seconds
 6b5e02f
 🔄 Run: #18847 (attempt 1)

✅ oss · depot-ubuntu-latest-arm-16 — run #18847 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 45.4 seconds
 6b5e02f
 🔄 Run: #18847 (attempt 1)

✅ oss · depot-ubuntu-latest-16 — run #18847 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-16)

 1 passed

Details

 1 test across 1 suite
 33.4 seconds
 6b5e02f
 🔄 Run: #18847 (attempt 1)

✅ private-cloud · depot-ubuntu-latest-arm-16 — run #18830 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 1 minute, 6 seconds
 2c456d9
 🔄 Run: #18830 (attempt 1)

✅ private-cloud · depot-ubuntu-latest-16 — run #18830 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

 3 passed

Details

 3 tests across 3 suites
 32.5 seconds
 2c456d9
 🔄 Run: #18830 (attempt 1)

✅ oss · depot-ubuntu-latest-arm-16 — run #18830 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

 1 passed

Details

 1 test across 1 suite
 47.2 seconds
 2c456d9
 🔄 Run: #18830 (attempt 1)

✅ oss · depot-ubuntu-latest-16 — run #18830 (attempt 1)

Playwright Test Results (oss - depot-ubuntu-latest-16)

 1 passed

Details

 1 test across 1 suite
 36.5 seconds
 2c456d9
 🔄 Run: #18830 (attempt 1)

[Zaimwa9]

@themis-blindfold review

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (6)

frontend/web/components/pages/environment-settings/tabs/warehouse-tab/clickhouseSetupSql.ts (2)

1-5: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

Validate or safely quote the database identifier.

The database field is only checked for non-emptiness before being interpolated into executable DDL. A crafted value can alter the copied SQL an administrator runs. Restrict it to valid ClickHouse identifiers or quote and escape it centrally; add malicious-input coverage.

---

29-41: 🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Static onboarding SQL breaks custom database onboarding. The helper hardcodes flagsmith_exp, while the create form allows a different database after Step 1.

• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/clickhouseSetupSql.ts#L29-L41: accept the configured database and generate grants and DDL from it.
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSetup.tsx#L160-L167: provide the live database value to the onboarding SQL, rather than calling the static helper.

frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSetup.tsx (1)

162-165: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use the actual SQL placeholders in the instructions.

The script contains <USER> and <CHANGE_ME_PASSWORD>, not <USERNAME> and <YOUR_SECURED_PASSWORD>.

frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSqlSnippet.tsx (1)

1-30: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Both new SQL components bypass the required component-folder structure.

• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSqlSnippet.tsx#L1-L30: move the component into its named folder with barrel and co-located SCSS.
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSetupSqlHelp.tsx#L1-L35: move the component into its named folder with barrel and co-located SCSS.

As per coding guidelines, “Each new component must live in its own folder with a barrel index.ts, a ComponentName/ComponentName.tsx file, [and] co-located ComponentName.scss.”

Source: Coding guidelines

frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSetupSqlHelp.tsx (1)

17-17: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win

Extract the visibility override union into a named type.

Define, for example, type VisibilityOverride = boolean | null, then use it in the state declaration.

As per coding guidelines, “Extract inline union types into named types.”

Source: Coding guidelines

frontend/web/components/pages/environment-settings/tabs/warehouse-tab/warehouseFormUtils.ts (1)

14-15: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

The specialised warning path lacks punctuation handling and regression coverage.

• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/warehouseFormUtils.ts#L14-L15: append terminal punctuation to detail before adding the next sentence.
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/warehouseFormUtils.test.ts#L13-L24: add a missing-table detail without terminal punctuation and assert a sentence break.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1f0a3f2f-9772-477f-8c94-9d69548cdd63

📥 Commits

Reviewing files that changed from the base of the PR and between 5a61559 and 8df5da2.

📒 Files selected for processing (12)

• docs/docs/experimentation/connect-a-warehouse.md
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/ClickHouseConfigForm.tsx
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseConnectionCard.tsx
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSetup.scss
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSetup.tsx
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSetupSqlHelp.tsx
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseSqlSnippet.tsx
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/clickhouseSetupSql.test.ts
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/__tests__/warehouseFormUtils.test.ts
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/clickhouseConfig.ts
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/clickhouseSetupSql.ts
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/warehouseFormUtils.ts

[themis-blindfold]

⚖️ Themis review: 🧹 Ship it, nits inside

The two-step onboarding flow is a real improvement over the previous single form, and the naming is now coherent: flagsmith_exp agrees across the frontend default, the backend default, the form placeholder and the docs, and a jest test pins the docs SQL fence to getClickHouseOnboardingSql() byte-for-byte (verified locally — they match). What remains open are three nits: the first-event button's new fallback branch also captures Snowflake connections, the edit form's setup panel opens on failures it can't help with and closes again as soon as the user reacts, and the docs' "instead of the managed Flagsmith warehouse" framing promises more isolation than the results path provides. Several substantive issues from earlier rounds are still live in the code but were closed by the author; they're listed below rather than re-raised. CI was still running at review time — Unit Tests, Lint changed files, CodeQL and Link Check Docs had completed successfully; the four E2E jobs had not.

Area	Score
🎯 Correctness	3/5
🧪 Test coverage	4/5
📐 Code quality	4/5
🚀 Product impact	4/5

🧹 Nits

• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/WarehouseConnectionCard.tsx:64 — the new fallback branch is not ClickHouse-specific.
• frontend/web/components/pages/environment-settings/tabs/warehouse-tab/ClickHouseConfigForm.tsx:237 — setup panel visibility is keyed to transient test state.
• docs/docs/experimentation/connect-a-warehouse.md:55 — the opening sentence overstates where experiment data lives.

⚖️ Acknowledged

• Onboarding SQL hardcodes flagsmith_exp (database and grants) while step 2's Database field stays editable, so a renamed database yields a connection the created user has no privileges on — thread resolved by @Zaimwa9.
• Step-1 copy tells the user to replace <USERNAME> and <YOUR_SECURED_PASSWORD>, but the copied script contains <USER> and <CHANGE_ME_PASSWORD> (WarehouseSetup.tsx:164-165) — thread resolved by @Zaimwa9.
• The TLS switch is now disabled, leaving no path to enable TLS on a stored connection that has secure: false — thread resolved by @Zaimwa9.
• The database name is interpolated into copyable SQL that users are told to run as an administrator, and the backend only checks it is a non-empty string (api/experimentation/warehouse_validation.py:61-65); the HTML half of that concern does not apply — Highlight escapes before dangerouslySetInnerHTML (frontend/web/components/Highlight.js:4-14) — thread resolved by @Zaimwa9.
• CONSTRAINT timestamp_sane rejects rows with a client clock before 2020, which fails the whole insert batch rather than the row — thread resolved by @Zaimwa9.

📝 Walkthrough

• SQL generation — clickhouseSetupSql.ts splits the DDL (getClickHouseSetupSql(database), interpolated) from the full onboarding script (getClickHouseOnboardingSql(), user + grants + DDL, fixed to flagsmith_exp).
• Create flow — WarehouseSetup.tsx wraps ClickHouse in a numbered two-step rail: step 1 is the collapsible onboarding SQL, step 2 the connection form.
• Edit flow / card — WarehouseSetupSqlHelp renders the interpolated DDL behind a CalloutBar, expanded from a prop with a user toggle that wins afterwards.
• First-event nudge — showSendFirstEvent gains a non-flagsmith branch driven by total_events_received, which the backend now populates for ClickHouse from the customer's instance.
• Defaults & copy — database default and placeholder move to flagsmith_exp, username default becomes empty, TLS switch is disabled, a few labels reworded.
• Docs & tests — new "Bring your own ClickHouse" section, plus tests for interpolation, the onboarding script, and byte-parity between the docs fence and the generated SQL.

🧪 How to verify

• Create a ClickHouse connection with the Database field left at flagsmith_exp, run the copied step-1 script against a real instance as an admin, then Test connection — expect connected.
• Repeat with the Database field changed to analytics and confirm what the user sees: the copied script still targets flagsmith_exp, and the grants never mention analytics.
• Open the edit form, click Test connection against a wrong password, watch the "Database setup" panel expand, then type in any field and watch it collapse.
• Load the warehouse tab for a Snowflake connection (create one via the API — the UI card is disabled) and click "Send your first event"; expect the failure toast.
• cd frontend && npm run test:unit -- clickhouseSetupSql to re-run the docs-parity test.

Automate: the docs-parity test already guards the SQL copies; a render test for WarehouseSetupSqlHelp would cover the override ?? showInitially visibility rule, which nothing exercises today.

Product take: Self-serve setup for bring-your-own ClickHouse — the SQL is now one copy button away in the product instead of a support conversation, and the numbered steps make the ordering (provision, then connect) obvious. That is a solid capability improvement for the experimentation beta, above routine polish. The rough edge is the fixed flagsmith_exp in the copied script versus the editable Database field, which the author has consciously accepted.

Big picture: The canonical events schema now has two copies in this repo — the TS template and the docs fence — kept in step by a jest test, and zero copies in the backend that owns ingestion. Nothing here fails if the ingestor's real schema drifts from what customers are told to create, and the columns the DDL adds (collected_at, traits, metadata, sdk_*) are referenced by no query in this repository. Worth deciding which component owns that schema and having the frontend/docs render it from there, rather than growing a third hand-maintained copy when the next warehouse type lands.

🧭 Assumptions & unverified claims

• Events emitted by "Send your first event" are assumed to reach a customer-managed ClickHouse; that routing lives in Flagsmith's event ingestor, outside this repository, so I could not confirm that total_events_received ever becomes non-zero for a BYO connection in practice.
• The onboarding script grants on flagsmith_exp.events before creating the database and table. ClickHouse's name-based access control is assumed to accept grants on objects that do not exist yet; not verified against a live instance or the published docs (no network access in this environment).
• The DDL's collected_at, traits, metadata, sdk_language and sdk_version columns are assumed to match what the ingestor writes; no copy of the managed events schema exists in this repo to compare against.
• Frontend unit tests were not run locally (dependencies not installed); the Unit Tests check for this head had completed successfully, and the docs-fence-versus-generated-SQL comparison was reproduced by hand.

A setup script that documents itself, tested against the docs that document it — turtles, but well-stacked ones. · reviewed at 8df5da2

[talissoncosta]

No blockers, only suggestions