apps/backend/scripts/clickhouse-migrations.ts (1)

9-12: Using plaintext password authentication.

While plaintext_password is acceptable for development environments, consider documenting this choice or using sha256_password for better security practices.

Example with SHA256:

import { createHash } from 'crypto';

const passwordHash = createHash('sha256')
  .update(clickhouseExternalPassword)
  .digest('hex');

await client.exec({
  query: "CREATE USER IF NOT EXISTS limited_user IDENTIFIED WITH sha256_password BY {passwordHash:String}",
  query_params: { passwordHash },
});

apps/e2e/tests/backend/endpoints/api/v1/analytics-query.test.ts (2)

1-29: Good test coverage for basic query execution.

The tests appropriately use inline snapshots as per coding guidelines. Consider adding a negative test case verifying that client accessType is rejected, since the route requires serverOrHigherAuthTypeSchema.

---

274-387: Security tests are comprehensive.

Good coverage of dangerous operations (CREATE TABLE, system tables, KILL QUERY, INSERT). Note that error messages expose the internal username limited_user - consider whether this level of detail should be sanitized in the route handler before returning to clients.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T02:09:03.104Z
Learning: Applies to packages/stack-shared/src/config/** : When making backwards-incompatible changes to the config schema, update the migration functions in `packages/stack-shared/src/config/schema.ts`

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T02:09:03.104Z
Learning: Applies to apps/e2e/**/*.{ts,tsx} : Always add new E2E tests when you change the API or SDK interface

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T02:09:03.104Z
Learning: Applies to **/*.{test,spec}.{ts,tsx} : Use `.toMatchInlineSnapshot` for test assertions instead of other selectors when possible; check snapshot-serializer.ts for formatting and non-deterministic value handling

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T02:09:03.104Z
Learning: Applies to apps/backend/src/app/api/latest/**/*.{ts,tsx} : In the Stack Auth monorepo backend API, organize routes by resource type (auth, user management, team management, OAuth providers) in `/apps/backend/src/app/api/latest/*`

apps/backend/scripts/clickhouse-migrations.ts (1)

4-23: Migration GRANT targets a likely non-existent table and hardcodes the external user

This script still has the two issues called out in earlier reviews:

• GRANT SELECT ON analytics.allowed_table1 TO limited_user; will fail if analytics.allowed_table1 doesn’t exist yet (which seems likely given the TODO about creating migration files).
• The external user name is hardcoded as limited_user, even though STACK_CLICKHOUSE_EXTERNAL_USER exists and is used elsewhere; that can drift.

You could make this more robust along these lines:

 export async function runClickhouseMigrations() {
   console.log("Running Clickhouse migrations...");
   const client = createClickhouseClient("admin");
-  const clickhouseExternalPassword = getEnvVariable("STACK_CLICKHOUSE_EXTERNAL_PASSWORD");
-  // todo: create migration files
-  await client.exec({
-    query: "CREATE USER IF NOT EXISTS limited_user IDENTIFIED WITH plaintext_password BY {clickhouseExternalPassword:String}",
-    query_params: { clickhouseExternalPassword },
-  });
-  const queries = [
-    "GRANT SELECT ON analytics.allowed_table1 TO limited_user;",
-    "REVOKE ALL ON system.* FROM limited_user;",
-    "REVOKE CREATE, ALTER, DROP, INSERT ON *.* FROM limited_user;"
-  ];
-  for (const query of queries) {
-    console.log(query);
-    await client.exec({ query });
-  }
-  console.log("Clickhouse migrations complete");
-  await client.close();
+  const externalUser = getEnvVariable("STACK_CLICKHOUSE_EXTERNAL_USER", "limited_user");
+  const clickhouseExternalPassword = getEnvVariable("STACK_CLICKHOUSE_EXTERNAL_PASSWORD");
+
+  try {
+    // TODO: create proper ClickHouse schema migrations
+    await client.exec({
+      query: "CREATE USER IF NOT EXISTS {externalUser:Identifier} IDENTIFIED WITH plaintext_password BY {clickhouseExternalPassword:String}",
+      query_params: { externalUser, clickhouseExternalPassword },
+    });
+
+    const queries = [
+      // Enable GRANTs once the target tables exist.
+      // "GRANT SELECT ON analytics.some_table TO {externalUser:Identifier};",
+      `REVOKE ALL ON system.* FROM ${externalUser};`,
+      `REVOKE CREATE, ALTER, DROP, INSERT ON *.* FROM ${externalUser};`,
+    ];
+
+    for (const query of queries) {
+      console.log(query);
+      await client.exec({ query });
+    }
+
+    console.log("Clickhouse migrations complete");
+  } finally {
+    await client.close();
+  }
 }

Adjust the GRANT line once your analytics tables are in place.

apps/backend/src/lib/clickhouse.tsx (1)

22-55: Fix getQueryTimingStats typing and guard against missing query_log rows

This function still has the issues called out in earlier reviews:

• profile.json is typed as if it returns a flat { cpu_time_ms, wall_clock_time_ms }, but you then access stats.data[0]; this doesn’t match the ClickHouse JSON shape and will likely fail type-checking.
• At runtime, system.query_log can legitimately return an empty data array (log entry not flushed yet), making stats.data[0] undefined and crashing callers that assume stats are always present.

A safer version would be:

-export const getQueryTimingStats = async (client: ClickHouseClient, queryId: string) => {
+export const getQueryTimingStats = async (
+  client: ClickHouseClient,
+  queryId: string,
+): Promise<{ cpu_time_ms: number; wall_clock_time_ms: number }> => {
@@
-  const stats = await profile.json<{
-    cpu_time_ms: number,
-    wall_clock_time_ms: number,
-  }>();
-  return stats.data[0];
+  const stats = await profile.json<{
+    data: Array<{
+      cpu_time_ms: number;
+      wall_clock_time_ms: number;
+    }>;
+  }>();
+
+  if (!stats.data || stats.data.length === 0) {
+    throw new Error(
+      `Query timing stats not found for query_id=${queryId}; query_log entry may not be available yet.`,
+    );
+  }
+
+  return stats.data[0];
 };

Callers can then convert this error into a KnownErrors.AnalyticsQueryError or similar, as appropriate for the API surface.

.github/workflows/docker-server-test.yaml (1)

26-30: Consider adding a lightweight readiness check for ClickHouse

The container may not always be ready within 5 seconds, especially on a busy CI runner. A transient slow start would make this job flaky.

Consider replacing the fixed sleep with a small readiness loop, for example:

      - name: Setup clickhouse
        run: |
          docker run -d --name clickhouse \
            -e CLICKHOUSE_DB=analytics \
            -e CLICKHOUSE_USER=stackframe \
            -e CLICKHOUSE_PASSWORD=password \
            -p 8133:8123 clickhouse/clickhouse-server:25.10

          for i in {1..30}; do
            if docker exec clickhouse clickhouse-client --query "SELECT 1" >/dev/null 2>&1; then
              echo "ClickHouse is ready"
              break
            fi
            echo "Waiting for ClickHouse..."
            sleep 1
          done

          docker logs clickhouse

</blockquote></details>
<details>
<summary>apps/backend/.env.development (1)</summary><blockquote>

`74-80`: **ClickHouse env block looks consistent with backend usage**

The new `STACK_CLICKHOUSE_*` variables line up with `createClickhouseClient` and the CI ClickHouse setup (DB `analytics`, admin user `stackframe`, external user `limited_user`), so this should wire up cleanly for local dev.

The `dotenv-linter` warnings here (substitution and key ordering) are stylistic only; the same `${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}` pattern is already used above. You can reorder the keys if you want to silence the linter, but it’s not functionally required.

</blockquote></details>

</blockquote></details>

<details>
<summary>📜 Review details</summary>

**Configuration used**: CodeRabbit UI

**Review profile**: CHILL

**Plan**: Pro

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 0c088962934cdf829c9e6b282d2fa5a4e07723a3 and 41287db62997e2a54a1084037a90136517fcbbe5.

</details>

<details>
<summary>📒 Files selected for processing (5)</summary>

* `.github/workflows/docker-server-test.yaml` (1 hunks)
* `apps/backend/.env.development` (1 hunks)
* `apps/backend/scripts/clickhouse-migrations.ts` (1 hunks)
* `apps/backend/src/lib/clickhouse.tsx` (1 hunks)
* `docker/server/.env.example` (1 hunks)

</details>

<details>
<summary>🧰 Additional context used</summary>

<details>
<summary>📓 Path-based instructions (2)</summary>

<details>
<summary>**/*.{ts,tsx}</summary>


**📄 CodeRabbit inference engine (AGENTS.md)**

> `**/*.{ts,tsx}`: Ensure code passes `pnpm typecheck` for TypeScript type validation
> Never use `toast` for blocking alerts and errors; use alerts instead as they are more visible to users
> Keep hover/click transitions snappy and fast; apply transitions after the action (e.g., smooth fade-out on hover end) rather than delaying actions with pre-transitions to avoid sluggish UI
> Never use try-catch-all, never void a promise, never use .catch(console.error) or similar; use `runAsynchronously` or `runAsynchronouslyWithAlert` for error handling instead of try-catch blocks
> Use loading indicators instead of try-catch blocks for asynchronous UI operations; button components like <Button> support async callbacks with built-in loading state
> Use ES6 maps instead of records wherever possible

Files:
- `apps/backend/src/lib/clickhouse.tsx`
- `apps/backend/scripts/clickhouse-migrations.ts`

</details>
<details>
<summary>apps/**/*.{ts,tsx}</summary>


**📄 CodeRabbit inference engine (AGENTS.md)**

> Prefer client components and dynamic functions like `usePathname` over Next.js dynamic functions to keep pages static; avoid using `await params` or similar dynamic patterns

Files:
- `apps/backend/src/lib/clickhouse.tsx`
- `apps/backend/scripts/clickhouse-migrations.ts`

</details>

</details><details>
<summary>🧠 Learnings (1)</summary>

<details>
<summary>📚 Learning: 2025-11-25T02:09:03.104Z</summary>

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T02:09:03.104Z
Learning: Applies to packages/stack-shared/src/config/** : When making backwards-incompatible changes to the config schema, update the migration functions in packages/stack-shared/src/config/schema.ts

**Applied to files:**
- `apps/backend/scripts/clickhouse-migrations.ts`

</details>

</details><details>
<summary>🧬 Code graph analysis (2)</summary>

<details>
<summary>apps/backend/src/lib/clickhouse.tsx (1)</summary><blockquote>

<details>
<summary>packages/stack-shared/src/utils/env.tsx (1)</summary>

* `getEnvVariable` (16-58)

</details>

</blockquote></details>
<details>
<summary>apps/backend/scripts/clickhouse-migrations.ts (2)</summary><blockquote>

<details>
<summary>apps/backend/src/lib/clickhouse.tsx (1)</summary>

* `createClickhouseClient` (11-19)

</details>
<details>
<summary>packages/stack-shared/src/utils/env.tsx (1)</summary>

* `getEnvVariable` (16-58)

</details>

</blockquote></details>

</details><details>
<summary>🪛 dotenv-linter (4.0.0)</summary>

<details>
<summary>docker/server/.env.example</summary>

[warning] 20-20: [UnorderedKey] The STACK_CLICKHOUSE_ADMIN_PASSWORD key should go before the STACK_CLICKHOUSE_URL key

(UnorderedKey)

---

[warning] 21-21: [UnorderedKey] The STACK_CLICKHOUSE_EXTERNAL_PASSWORD key should go before the STACK_CLICKHOUSE_URL key

(UnorderedKey)

</details>
<details>
<summary>apps/backend/.env.development</summary>

[warning] 75-75: [SubstitutionKey] The STACK_CLICKHOUSE_URL key is not assigned properly

(SubstitutionKey)

---

[warning] 76-76: [UnorderedKey] The STACK_CLICKHOUSE_ADMIN_USER key should go before the STACK_CLICKHOUSE_URL key

(UnorderedKey)

---

[warning] 77-77: [UnorderedKey] The STACK_CLICKHOUSE_ADMIN_PASSWORD key should go before the STACK_CLICKHOUSE_ADMIN_USER key

(UnorderedKey)

---

[warning] 78-78: [UnorderedKey] The STACK_CLICKHOUSE_EXTERNAL_USER key should go before the STACK_CLICKHOUSE_URL key

(UnorderedKey)

---

[warning] 79-79: [UnorderedKey] The STACK_CLICKHOUSE_EXTERNAL_PASSWORD key should go before the STACK_CLICKHOUSE_EXTERNAL_USER key

(UnorderedKey)

---

[warning] 80-80: [UnorderedKey] The STACK_CLICKHOUSE_DATABASE key should go before the STACK_CLICKHOUSE_EXTERNAL_PASSWORD key

(UnorderedKey)

</details>

</details>

</details>

<details>
<summary>⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (11)</summary>

* GitHub Check: Vercel Agent Review
* GitHub Check: docker
* GitHub Check: restart-dev-and-test-with-custom-base-port
* GitHub Check: check_prisma_migrations (22.x)
* GitHub Check: setup-tests
* GitHub Check: build (22.x)
* GitHub Check: lint_and_build (latest)
* GitHub Check: all-good
* GitHub Check: build (22.x)
* GitHub Check: restart-dev-and-test
* GitHub Check: build (22.x)

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

docker/server/.env.example (1)

19-21: Reorder ClickHouse keys for consistency with dotenv-linter and env-var conventions.

The three ClickHouse environment variables should be in alphabetical order to match the Postgres connection strings pattern and resolve the dotenv-linter UnorderedKey warnings.

Apply this diff:

-STACK_CLICKHOUSE_URL=http://host.docker.internal:8133
 STACK_CLICKHOUSE_ADMIN_PASSWORD=password
 STACK_CLICKHOUSE_EXTERNAL_PASSWORD=password
+STACK_CLICKHOUSE_URL=http://host.docker.internal:8133

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-25T02:09:03.104Z
Learning: When making dashboard changes, provide deep links to the dashboard page in the format `http://localhost:<$NEXT_PUBLIC_STACK_PORT_PREFIX>01/projects/-selector-/...` (or use a.localhost, b.localhost, c.localhost for port prefixes 91, 92, 93)

apps/backend/scripts/clickhouse-migrations.ts (2)

14-14: GRANT statement references non-existent table.

This grants SELECT on analytics.allowed_table1, which doesn't exist yet and will cause the migration to fail.

Comment or remove this line until the table is created in a prior migration step.

---

22-23: Move client cleanup to a finally block.

If any query fails before line 23, the client won't be closed, leaving the connection open.

Apply this diff to guarantee cleanup:

-  console.log("Clickhouse migrations complete");
-  await client.close();
+  try {
+    // existing migration logic here
+    console.log("Clickhouse migrations complete");
+  } finally {
+    await client.close();
+  }

Note: Per coding guidelines, avoid try-catch-all for error handling. Let errors propagate naturally while ensuring cleanup in the finally block.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-11-28T21:21:39.123Z
Learning: Applies to packages/stack-shared/src/config/schema.ts : Whenever making backwards-incompatible changes to the config schema, update the migration functions in `packages/stack-shared/src/config/schema.ts`

.github/workflows/docker-server-build-run.yaml (1)

26-30: ClickHouse setup step looks good and maintains consistency.

The step is well-configured:

• Uses the same ClickHouse version (25.10) as the docker-compose file for consistency
• Port mapping (8133:8123) aligns with the development environment configuration
• Environment variables match those in .env.development
• Logging output helps with debugging startup issues

Consider whether 5 seconds is sufficient for ClickHouse to fully initialize. Depending on the CI environment performance, you might want to add a health check loop similar to the "Check server health" step, or increase the sleep duration to ensure ClickHouse is ready before subsequent steps.

apps/backend/.env.development (1)

75-82: Consider alphabetically reordering the ClickHouse configuration keys for improved maintainability.

While the variable substitution pattern is already supported via the backend's custom environment variable handling, the ClickHouse keys should follow alphabetical order: STACK_CLICKHOUSE_ADMIN_PASSWORD, STACK_CLICKHOUSE_ADMIN_USER, STACK_CLICKHOUSE_DATABASE, STACK_CLICKHOUSE_EXTERNAL_PASSWORD, STACK_CLICKHOUSE_EXTERNAL_USER, STACK_CLICKHOUSE_URL.

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-04T18:03:49.984Z
Learning: Applies to {.env*,**/*.{ts,tsx,js}} : Prefix environment variables with STACK_ (or NEXT_PUBLIC_STACK_ if public) so changes are picked up by Turborepo and improves readability

apps/backend/scripts/clickhouse-migrations.ts (2)

14-14: Migration will fail: analytics.allowed_table1 doesn't exist.

This GRANT references a table that hasn't been created. The migration will fail at runtime. Per past discussion, this is noted as temporary, but it should be commented out or removed until the table exists.

---

9-21: Add try-finally to ensure client cleanup on failure.

If any client.exec() call throws, client.close() on line 23 won't be reached, causing a resource leak. Wrap the migration logic in a try-finally block.

 export async function runClickhouseMigrations() {
   console.log("[Clickhouse] Running Clickhouse migrations...");
-  const client = clickhouseAdminClient;
+  const client = createClickhouseClient("admin");
   const clickhouseExternalPassword = getEnvVariable("STACK_CLICKHOUSE_EXTERNAL_PASSWORD");
-  // todo: create migration files
-  await client.exec({
-    query: "CREATE USER IF NOT EXISTS limited_user IDENTIFIED WITH plaintext_password BY {clickhouseExternalPassword:String}",
-    query_params: { clickhouseExternalPassword },
-  });
-  const queries = [
-    "GRANT SELECT ON analytics.allowed_table1 TO limited_user;",
-    "REVOKE ALL ON system.* FROM limited_user;",
-    "REVOKE CREATE, ALTER, DROP, INSERT ON *.* FROM limited_user;"
-  ];
-  for (const query of queries) {
-    console.log("[Clickhouse] " + query);
-    await client.exec({ query });
+  try {
+    await client.exec({
+      query: "CREATE USER IF NOT EXISTS limited_user IDENTIFIED WITH plaintext_password BY {clickhouseExternalPassword:String}",
+      query_params: { clickhouseExternalPassword },
+    });
+    const queries = [
+      "GRANT SELECT ON analytics.allowed_table1 TO limited_user;",
+      "REVOKE ALL ON system.* FROM limited_user;",
+      "REVOKE CREATE, ALTER, DROP, INSERT ON *.* FROM limited_user;"
+    ];
+    for (const query of queries) {
+      console.log("[Clickhouse] " + query);
+      await client.exec({ query });
+    }
+    console.log("[Clickhouse] Clickhouse migrations complete");
+  } finally {
+    await client.close();
   }
-  console.log("[Clickhouse] Clickhouse migrations complete");
-  await client.close();
 }

apps/backend/src/app/api/latest/internal/analytics/query/route.ts (1)

52-53: Consider wrapping getQueryTimingStats errors.

If getQueryTimingStats fails (e.g., query log entry not found), it throws a StackAssertionError which will propagate as an internal error rather than a user-friendly AnalyticsQueryError. Consider wrapping this call for consistent error responses.

     const rows = await resultSet.data.json<Record<string, unknown>[]>();
-    const stats = await getQueryTimingStats(client, queryId);
+    let stats;
+    try {
+      stats = await getQueryTimingStats(client, queryId);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to retrieve query timing statistics";
+      throw new KnownErrors.AnalyticsQueryError(message);
+    }

apps/e2e/tests/backend/endpoints/api/v1/analytics-query.test.ts (1)

217-239: Test timeout behavior may be unstable across ClickHouse versions

The SELECT sleep(3) with 100ms timeout can be affected by ClickHouse versions where sleep queries behave inconsistently with max_execution_time enforcement. Recent ClickHouse versions show timeout behavior inconsistencies where max_execution_time is sometimes treated differently.

Consider adding an inline comment explaining that the test expects ANALYTICS_QUERY_ERROR due to server-side timeout enforcement, and note any specific ClickHouse version constraints if the timeout behavior is known to be reliable only in certain versions.

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Learnt from: N2D4
Repo: stack-auth/stack-auth PR: 1032
File: apps/backend/src/app/api/latest/analytics/query/route.tsx:20-20
Timestamp: 2025-12-17T01:23:07.460Z
Learning: In apps/backend/src/app/api/latest/analytics/query/route.tsx, the include_all_branches field controls which ClickHouse user type is used: when true, use "admin" authType for access to all branches; when false (default), use "external" authType for limited/filtered branch access.

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-04T18:03:49.984Z
Learning: Applies to **/*.{ts,tsx} : NEVER try-catch-all, NEVER void a promise, and NEVER .catch(console.error); use loading indicators and async callbacks instead, or use runAsynchronously/runAsynchronouslyWithAlert for error handling

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-04T18:03:49.984Z
Learning: Applies to apps/e2e/**/*.{ts,tsx} : Always add new E2E tests when changing API or SDK interface; err on the side of creating too many tests due to the critical nature of the industry

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-04T18:03:49.984Z
Learning: Applies to **/*.{ts,tsx} : Always add new E2E tests when changing the API or SDK interface

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-04T18:03:49.984Z
Learning: Applies to packages/stack-shared/src/config/schema.ts : Whenever making backwards-incompatible changes to the config schema, update the migration functions in packages/stack-shared/src/config/schema.ts

apps/backend/scripts/clickhouse-migrations.ts (3)

6-6: Critical: Closing the singleton admin client breaks subsequent usage.

The code uses clickhouseAdminClient (a module-level singleton exported from @/lib/clickhouse and used elsewhere in the codebase, e.g., apps/backend/src/lib/events.tsx line 198), but then closes it at line 28. This will break all subsequent operations that depend on this shared client.

🔎 Proposed fix

Since this is a one-off migration script, either:

Option 1 (Recommended): Create a dedicated client instance for migrations and close it:

-  const client = clickhouseAdminClient;
+  const client = createClickhouseClient("admin");

Then keep the client.close() at line 28.

Option 2: If using the singleton intentionally, remove the close call:

   console.log("[Clickhouse] Clickhouse migrations complete");
-  await client.close();

Also applies to: 28-28

---

4-29: Critical: Missing error handling causes resource leaks and silent failures.

The migration function lacks try-catch-finally error handling. If any client.exec() call fails, the client connection will leak (won't be closed), and the error won't be properly logged or propagated.

🔎 Proposed fix

Wrap the migration logic in try-finally to ensure cleanup:

 export async function runClickhouseMigrations() {
   console.log("[Clickhouse] Running Clickhouse migrations...");
   const client = clickhouseAdminClient;
-  const clickhouseExternalPassword = getEnvVariable("STACK_CLICKHOUSE_EXTERNAL_PASSWORD");
-  await client.exec({
-    query: "CREATE USER IF NOT EXISTS limited_user IDENTIFIED WITH sha256_password BY {clickhouseExternalPassword:String}",
-    query_params: { clickhouseExternalPassword },
-  });
-  // todo: create migration files
-  await client.exec({ query: EXTERNAL_ANALYTICS_DB_SQL });
-  await client.exec({ query: EVENTS_TABLE_BASE_SQL });
-  await client.exec({ query: EVENTS_VIEW_SQL });
-  const queries = [
-    "REVOKE ALL PRIVILEGES ON *.* FROM limited_user;",
-    "REVOKE ALL FROM limited_user;",
-    "GRANT SELECT ON default.events TO limited_user;",
-  ];
-  await client.exec({
-    query: "CREATE ROW POLICY IF NOT EXISTS events_project_isolation ON default.events FOR SELECT USING project_id = getSetting('SQL_project_id') AND branch_id = getSetting('SQL_branch_id') TO limited_user",
-  });
-  for (const query of queries) {
-    await client.exec({ query });
+  try {
+    const clickhouseExternalPassword = getEnvVariable("STACK_CLICKHOUSE_EXTERNAL_PASSWORD");
+    await client.exec({
+      query: "CREATE USER IF NOT EXISTS limited_user IDENTIFIED WITH sha256_password BY {clickhouseExternalPassword:String}",
+      query_params: { clickhouseExternalPassword },
+    });
+    // todo: create migration files
+    await client.exec({ query: EXTERNAL_ANALYTICS_DB_SQL });
+    await client.exec({ query: EVENTS_TABLE_BASE_SQL });
+    await client.exec({ query: EVENTS_VIEW_SQL });
+    const queries = [
+      "REVOKE ALL PRIVILEGES ON *.* FROM limited_user;",
+      "REVOKE ALL FROM limited_user;",
+      "GRANT SELECT ON default.events TO limited_user;",
+    ];
+    await client.exec({
+      query: "CREATE ROW POLICY IF NOT EXISTS events_project_isolation ON default.events FOR SELECT USING project_id = getSetting('SQL_project_id') AND branch_id = getSetting('SQL_branch_id') TO limited_user",
+    });
+    for (const query of queries) {
+      await client.exec({ query });
+    }
+    console.log("[Clickhouse] Clickhouse migrations complete");
+  } catch (error) {
+    console.error("[Clickhouse] Migration failed:", error);
+    throw error;
+  } finally {
+    await client.close();
   }
-  console.log("[Clickhouse] Clickhouse migrations complete");
-  await client.close();
 }

Note: This still has the singleton closing issue from the previous comment.

---

21-23: Major: Row policy relies on custom settings without proper configuration.

The row policy uses getSetting('SQL_project_id') and getSetting('SQL_branch_id'), but there's no configuration to:

1. Allow these custom settings to be changed in readonly mode
2. Create a role with CHANGEABLE_IN_READONLY constraints for these settings
3. Verify that server-side custom_settings_prefixes allows the SQL_ prefix

Without this configuration, the limited_user won't be able to set these custom settings, and the row policy won't function correctly, breaking tenant isolation.

🔎 Recommended approach

After creating the user, add role configuration:

   await client.exec({
     query: "CREATE USER IF NOT EXISTS limited_user IDENTIFIED WITH sha256_password BY {clickhouseExternalPassword:String}",
     query_params: { clickhouseExternalPassword },
   });
+  // Configure role to allow custom settings in readonly mode
+  await client.exec({
+    query: "CREATE ROLE IF NOT EXISTS limited_analytics_role SETTINGS SQL_project_id CHANGEABLE_IN_READONLY, SQL_branch_id CHANGEABLE_IN_READONLY",
+  });
+  await client.exec({
+    query: "GRANT limited_analytics_role TO limited_user",
+  });
+  await client.exec({
+    query: "SET DEFAULT ROLE limited_analytics_role TO limited_user",
+  });

Also, verify that the ClickHouse server configuration includes custom_settings_prefixes = 'SQL_' in the config file or environment.

Based on learnings from previous reviews on analytics query route.

apps/backend/scripts/clickhouse-migrations.ts (1)

12-12: TODO: Implement proper migration file system.

The inline SQL constants and sequential execution don't provide versioning, rollback capability, or idempotent re-runs. Consider implementing a proper migration system with:

• Numbered migration files (e.g., 001_create_events_table.sql)
• Migration tracking table to record applied migrations
• Ability to roll back or skip already-applied migrations

Do you want me to generate a migration framework implementation or open an issue to track this enhancement?

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Learnt from: CR
Repo: stack-auth/stack-auth PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-04T18:03:49.984Z
Learning: Applies to packages/stack-shared/src/config/schema.ts : Whenever making backwards-incompatible changes to the config schema, update the migration functions in packages/stack-shared/src/config/schema.ts

Learnt from: N2D4
Repo: stack-auth/stack-auth PR: 1032
File: apps/backend/src/app/api/latest/analytics/query/route.tsx:20-20
Timestamp: 2025-12-17T01:23:15.483Z
Learning: In apps/backend/src/app/api/latest/analytics/query/route.tsx, the include_all_branches field controls which ClickHouse user type is used: when true, use "admin" authType for access to all branches; when false (default), use "external" authType for limited/filtered branch access.

apps/e2e/tests/backend/backend-helpers.ts (1)

97-97: CamelCase detection is now too narrow (misses common keys).

Anchoring the regex means only strings like aBcd match, so typical camelCase keys (e.g., myKeyValue) will no longer be detected. This weakens the snake_case assertion. Consider reverting to a broader pattern.
Line 97.

🛠️ Suggested fix

-      if (key.match(/^[a-z0-9][A-Z][a-z0-9]+$/) && !key.includes("_") && !["newUser", "afterCallbackRedirectUrl"].includes(key)) {
+      if (key.match(/[a-z0-9]+[A-Z][a-z0-9]+/) && !key.includes("_") && !["newUser", "afterCallbackRedirectUrl"].includes(key)) {

apps/backend/src/app/api/latest/internal/clickhouse/migrate-events/route.tsx (2)

41-41: Extract branchId from event data instead of hardcoding.

This hardcodes branchId to DEFAULT_BRANCH_ID, causing historical events with non-default branch IDs to be migrated with incorrect data. The extraction pattern used for other fields (projectId, userId, etc.) should also apply here.

Suggested fix

-  const branchId = DEFAULT_BRANCH_ID;
+  const branchId = typeof dataRecord.branchId === "string" ? dataRecord.branchId : DEFAULT_BRANCH_ID;

---

62-208: Add E2E tests for this migration endpoint.

Per repository guidelines, new API endpoints require E2E test coverage. Tests should cover: successful migration with pagination, invalid timestamp handling, cursor-based pagination behavior, and empty result handling.

apps/backend/.env (1)

84-90: Optional: remove the extra blank line to avoid lint noise.
Keeps dotenv-linter clean and consistent.

🧹 Suggested cleanup

 STACK_CLICKHOUSE_EXTERNAL_PASSWORD=# a randomly generated secure string. The user account will be created automatically
-
-
+# (blank line removed)

apps/backend/src/app/api/latest/internal/clickhouse/migrate-events/route.tsx (3)

1-12: Unused import and prefer interface over type.

createClickhouseClient is imported but never used in this file. Also, per coding guidelines, prefer interface for defining object shapes.

Suggested fix

-import { clickhouseAdminClient, createClickhouseClient } from "@/lib/clickhouse";
+import { clickhouseAdminClient } from "@/lib/clickhouse";
 import { DEFAULT_BRANCH_ID } from "@/lib/tenancies";
 import { globalPrismaClient } from "@/prisma-client";
 import { createSmartRouteHandler } from "@/route-handlers/smart-route-handler";
 import { yupNumber, yupObject, yupString } from "@stackframe/stack-shared/dist/schema-fields";
 import { StatusError } from "@stackframe/stack-shared/dist/utils/errors";
 import type { Prisma } from "@/generated/prisma/client";

-type Cursor = {
-  created_at_millis: number,
-  id: string,
-};
+interface Cursor {
+  created_at_millis: number;
+  id: string;
+}

---

28-28: Add comment explaining the any type usage.

Per coding guidelines, when using any, leave a comment explaining why. The data field comes from Prisma's JSON type which doesn't have a strict schema.

Suggested fix

 const createClickhouseRows = (event: {
   id: string,
   systemEventTypeIds: string[],
-  data: any,
+  // eslint-disable-next-line `@typescript-eslint/no-explicit-any` -- Prisma JSON field has no schema; validated at runtime below
+  data: any,
   eventEndedAt: Date,
   eventStartedAt: Date,
   isWide: boolean,

---

176-187: Avoid non-null assertions; use explicit guards.

Per coding guidelines, prefer ?? throwErr(...) over non-null assertions. The progressCursorCreatedAt! assertions on lines 182-183 rely on the outer progressCursor check, but explicit handling is safer.

Suggested fix

-    const progressCursorCreatedAt = progressCursor ? new Date(progressCursor.created_at_millis) : null;
-    const remainingWhere = progressCursor ? {
+    const remainingWhere: Prisma.EventWhereInput = progressCursor ? {
+      AND: [
+        baseWhere,
+        {
+          OR: [
+            { createdAt: { gt: new Date(progressCursor.created_at_millis) } },
+            { createdAt: new Date(progressCursor.created_at_millis), id: { gt: progressCursor.id } },
+          ],
+        },
+      ],
+    } : baseWhere;
-      AND: [
-        baseWhere,
-        {
-          OR: [
-            { createdAt: { gt: progressCursorCreatedAt! } },
-            { createdAt: progressCursorCreatedAt!, id: { gt: progressCursor.id } },
-          ],
-        },
-      ],
-    } : baseWhere;

apps/backend/scripts/db-migrations.ts (2)

161-162: Consider clarifying migration types in console output.

As noted in a past review, it would help to differentiate between Postgres and ClickHouse migrations in the console logs. The summary log at lines 141-159 only mentions "migrations" generically.

---

21-24: ClickHouse client is never closed.

The client created here maintains an HTTP connection pool that should be closed after use to prevent resource leaks. Either close it explicitly or reuse the pattern from runClickhouseMigrations which closes its client.

🔧 Proposed fix

   const clickhouseClient = getClickhouseClient();
   await clickhouseClient.command({ query: "DROP DATABASE IF EXISTS analytics_internal" });
   await clickhouseClient.command({ query: "CREATE DATABASE IF NOT EXISTS analytics_internal" });
+  await clickhouseClient.close();
 };

apps/backend/src/app/api/latest/internal/analytics/query/route.ts (3)

116-119: Unknown error codes should log to Sentry before returning generic message.

Per prior review feedback, when an error code is neither safe nor unsafe, the function returns null which triggers a StackAssertionError. Unknown codes should be logged for investigation while returning the safe default message to users.

🔧 Proposed fix

+import { captureError } from "@stackframe/stack-shared/dist/utils/errors";
+
 function getSafeClickhouseErrorMessage(error: unknown): string | null {
   ...
   if (UNSAFE_CLICKHOUSE_ERROR_CODES.includes(errorCode)) {
     return DEFAULT_CLICKHOUSE_ERROR_MESSAGE;
   }
-  return null;
+  // Unknown error code - log to Sentry for investigation but return safe message to user
+  captureError("unknown-clickhouse-error-code", new Error(`Unknown ClickHouse error code: ${errorCode}`), { error });
+  return DEFAULT_CLICKHOUSE_ERROR_MESSAGE;
 }

---

34-82: ClickHouse client is never closed.

The client created at line 41 via getClickhouseExternalClient() maintains an HTTP connection pool. Without calling client.close(), connections will leak. Wrap the logic in try-finally.

🔧 Proposed fix

   async handler({ body, auth }) {
     if (body.include_all_branches) {
       throw new StackAssertionError("include_all_branches is not supported yet");
     }
     if (!isClickhouseConfigured()) {
       throw new StackAssertionError("ClickHouse is not configured");
     }
     const client = getClickhouseExternalClient();
-    const queryId = randomUUID();
-    const resultSet = await Result.fromPromise(client.query({
-      ...
-    }));
-    ...
-    return { ... };
+    try {
+      const queryId = randomUUID();
+      const resultSet = await Result.fromPromise(client.query({
+        ...
+      }));
+      ...
+      return { ... };
+    } finally {
+      await client.close();
+    }
   },

---

113-114: Safe error codes with null message should fallback to default.

If a safe error code lacks a message property, getSafeClickhouseErrorMessage returns null, causing a StackAssertionError to be thrown instead of a user-friendly AnalyticsQueryError.

🔧 Proposed fix

   if (SAFE_CLICKHOUSE_ERROR_CODES.includes(errorCode)) {
-    return message;
+    return message ?? DEFAULT_CLICKHOUSE_ERROR_MESSAGE;
   }

apps/backend/src/lib/events.tsx (2)

198-219: Isolate ClickHouse errors to prevent disrupting PostHog logging.

The ClickHouse insert is awaited without error handling. If ClickHouse is unavailable, the entire runAsynchronouslyAndWaitUntil block fails, preventing PostHog logging from executing.

🔧 Proposed fix

     if (isClickhouseConfigured()) {
-      const clickhouseClient = getClickhouseAdminClient();
-      await clickhouseClient.insert({
-        table: "analytics_internal.events",
-        values: eventTypesArray.map(eventType => ({
-          ...
-        })),
-        format: "JSONEachRow",
-        clickhouse_settings: {
-          date_time_input_format: "best_effort",
-          async_insert: 1,
-        },
-      });
+      try {
+        const clickhouseClient = getClickhouseAdminClient();
+        await clickhouseClient.insert({
+          table: "analytics_internal.events",
+          values: eventTypesArray.map(eventType => ({
+            ...
+          })),
+          format: "JSONEachRow",
+          clickhouse_settings: {
+            date_time_input_format: "best_effort",
+            async_insert: 1,
+          },
+        });
+      } catch (error) {
+        console.error("[Events] Failed to log event to ClickHouse:", error);
+      }
     }

---

214-217: Add wait_for_async_insert: 1 to prevent silent data loss.

With async_insert: 1 alone, inserts are fire-and-forget - the server won't report failures back to the client. Per ClickHouse best practices, pair it with wait_for_async_insert: 1 to receive feedback on insert failures.

🔧 Proposed fix

         clickhouse_settings: {
           date_time_input_format: "best_effort",
           async_insert: 1,
+          wait_for_async_insert: 1,
         },

apps/backend/src/app/api/latest/internal/clickhouse/migrate-events/route.tsx (2)

40-41: Extract branchId from event data instead of hardcoding.

All other fields (projectId, userId, teamId, sessionId, isAnonymous) are extracted from dataRecord, but branchId is hardcoded to DEFAULT_BRANCH_ID. This causes historical events with non-default branch IDs to be migrated with incorrect data.

🔧 Proposed fix

   const projectId = typeof dataRecord.projectId === "string" ? dataRecord.projectId : "";
-  const branchId = DEFAULT_BRANCH_ID;
+  const branchId = typeof dataRecord.branchId === "string" ? dataRecord.branchId : DEFAULT_BRANCH_ID;
   const userId = typeof dataRecord.userId === "string" ? dataRecord.userId : "";

---

155-166: Migration is not idempotent - re-runs will create duplicate rows.

The endpoint inserts rows without checking for existing entries, and the ClickHouse table uses MergeTree (not a deduplicating engine). If migration is re-run for the same time range, duplicate rows will be inserted. Consider either:

1. Using ReplacingMergeTree engine for the table
2. Adding a pre-insert check to filter out existing event IDs
3. Documenting this limitation and requiring manual table truncation before re-runs

apps/backend/scripts/db-migrations.ts (1)

14-14: Unnecessary wrapper function.

The getClickhouseClient wrapper adds no value over directly calling getClickhouseAdminClient(). Consider removing it for clarity.

♻️ Suggested simplification

-const getClickhouseClient = () => getClickhouseAdminClient();

Then use getClickhouseAdminClient() directly in dropSchema.

apps/backend/src/lib/clickhouse.tsx (1)

21-39: Add JSDoc documentation reminding callers to close returned clients, or implement a singleton pattern.

getClickhouseAdminClient() and getClickhouseExternalClient() create new client instances on each call. The @clickhouse/client library maintains HTTP connection pools that require explicit cleanup via client.close(). Current usage does not invoke close() on any returned clients. Consider adding JSDoc comments to document this requirement, or refactor to use a singleton/pooling pattern for long-lived clients.