perf(webapp,clickhouse): move runs empty-state check to ClickHouse

The runs list empty-state check ("does this environment have any run?") ran a findFirst against the Postgres TaskRun table. Serve it from ClickHouse instead (the same store the runs list already reads), so the check no longer queries TaskRun.

Only the runs list issues the check now; it filters the (organization, project, environment) prefix with a configurable created_at lower bound and is SWR-cached (positive results only) so a new environment's first run is picked up immediately.

Author: ericallam

.server-changes/runs-empty-state-clickhouse.md

@@ -0,0 +1,6 @@
+---
+area: webapp
+type: improvement
+---
+
+Reduce primary database load on the runs page by serving its empty-state check from ClickHouse instead of Postgres.

apps/webapp/app/env.server.ts

@@ -330,6 +330,13 @@ const EnvironmentSchema = z
       .string()
       .default(process.env.REDIS_TLS_DISABLED ?? "false"),
     TASK_META_CACHE_CURRENT_ENV_TTL_SECONDS: z.coerce.number().default(86400),
+
+    // Runs-list empty-state check: how far back the ClickHouse "does this env have any run"
+    // probe looks. Bounds the prove-absence partition scan. 0 = unbounded ("any run ever").
+    RUN_LIST_HAS_RUNS_LOOKBACK_DAYS: z.coerce.number().default(30),
+    // SWR TTLs for the empty-state has-runs cache (memory + Redis).
+    RUN_LIST_HAS_RUNS_CACHE_FRESH_MS: z.coerce.number().default(86_400_000),
+    RUN_LIST_HAS_RUNS_CACHE_STALE_MS: z.coerce.number().default(604_800_000),
     TASK_META_CACHE_BY_WORKER_TTL_SECONDS: z.coerce.number().default(2592000),
 
     REALTIME_STREAMS_REDIS_HOST: z

apps/webapp/app/presenters/v3/NextRunListPresenter.server.ts

@@ -11,11 +11,47 @@ import { timeFilters } from "~/components/runs/v3/SharedFilters";
 import { findDisplayableEnvironment } from "~/models/runtimeEnvironment.server";
 import { getTaskIdentifiers } from "~/models/task.server";
 import { RunsRepository } from "~/services/runsRepository/runsRepository.server";
+import { env } from "~/env.server";
+import {
+  createCache,
+  createLRUMemoryStore,
+  DefaultStatefulContext,
+  Namespace,
+} from "@internal/cache";
+import { RedisCacheStore } from "~/services/unkey/redisCacheStore.server";
+import { singleton } from "~/utils/singleton";
 import { regionForDisplay } from "~/runEngine/concerns/workerQueueSplit.server";
 import { machinePresetFromRun } from "~/v3/machinePresets.server";
 import { ServiceValidationError } from "~/v3/services/baseService.server";
 import { isCancellableRunStatus, isFinalRunStatus, isPendingRunStatus } from "~/v3/taskStatus";
 
+// Positive-only cache: only envs known to have runs are stored (empty envs are re-checked),
+// so "has runs" is monotonic and the TTL can be very long. Tiered memory + Redis.
+const runsExistCache = singleton("runsExistCache", () => {
+  const ctx = new DefaultStatefulContext();
+  const memory = createLRUMemoryStore(5000, "runs-has-runs-cache");
+  const redis = new RedisCacheStore({
+    name: "runs-has-runs",
+    connection: {
+      keyPrefix: "tr:cache:runs-has-runs",
+      port: env.CACHE_REDIS_PORT,
+      host: env.CACHE_REDIS_HOST,
+      username: env.CACHE_REDIS_USERNAME,
+      password: env.CACHE_REDIS_PASSWORD,
+      tlsDisabled: env.CACHE_REDIS_TLS_DISABLED === "true",
+      clusterMode: env.CACHE_REDIS_CLUSTER_MODE_ENABLED === "1",
+    },
+  });
+
+  return createCache({
+    hasRuns: new Namespace<boolean>(ctx, {
+      stores: [memory, redis],
+      fresh: env.RUN_LIST_HAS_RUNS_CACHE_FRESH_MS,
+      stale: env.RUN_LIST_HAS_RUNS_CACHE_STALE_MS,
+    }),
+  });
+});
+
 export type RunListOptions = {
   userId?: string;
   projectId: string;
@@ -42,6 +78,8 @@ export type RunListOptions = {
   direction?: Direction;
   cursor?: string;
   pageSize?: number;
+  // Run the empty-state "has any run ever" probe. Only the runs list consumes it.
+  includeHasAnyRuns?: boolean;
 };
 
 const DEFAULT_PAGE_SIZE = 25;
@@ -65,37 +103,31 @@ export class NextRunListPresenter {
     }
   ) {}
 
-  // Existence probe for the empty-state. run-ops (TaskRun) read.
-  // Split off / single-DB: one plain findFirst on `replica` (passthrough).
-  // Split on: true if a row exists in the NEW run-ops DB OR the LEGACY run-ops
-  // read replica only (never the legacy writer). New first to avoid touching
-  // legacy whenever the new DB already answers.
-  async #anyRunExistsInEnv(environmentId: string): Promise<boolean> {
-    const splitEnabled = this.readThroughDeps?.splitEnabled ?? false;
+  // Empty-state existence probe, served from ClickHouse (same connection as the runs
+  // list) so it no longer scans TaskRun in Postgres. SWR-cached to spare ClickHouse;
+  // RUN_LIST_HAS_RUNS_LOOKBACK_DAYS bounds the prove-absence partition scan.
+  async #anyRunExistsInEnv(
+    runsRepository: RunsRepository,
+    organizationId: string,
+    projectId: string,
+    environmentId: string
+  ): Promise<boolean> {
+    const lookbackDays = env.RUN_LIST_HAS_RUNS_LOOKBACK_DAYS;
+    const createdAtLowerBoundMs =
+      lookbackDays > 0 ? Date.now() - lookbackDays * 24 * 60 * 60 * 1000 : undefined;
 
-    if (!splitEnabled) {
-      const firstRun = await this.replica.taskRun.findFirst({
-        where: { runtimeEnvironmentId: environmentId },
-        select: { id: true },
+    const result = await runsExistCache.hasRuns.swr(environmentId, async () => {
+      const exists = await runsRepository.runExistsInEnvironment({
+        organizationId,
+        projectId,
+        environmentId,
+        createdAtLowerBoundMs,
       });
-      return firstRun !== null;
-    }
-
-    const newClient = this.readThroughDeps?.newClient ?? this.replica;
-    const newRun = await newClient.taskRun.findFirst({
-      where: { runtimeEnvironmentId: environmentId },
-      select: { id: true },
+      // undefined (not false) so swr does NOT cache the empty result — re-check until a run exists.
+      return exists ? true : undefined;
     });
-    if (newRun) {
-      return true;
-    }
 
-    const legacyReplica = this.readThroughDeps?.legacyReplica ?? this.replica;
-    const legacyRun = await legacyReplica.taskRun.findFirst({
-      where: { runtimeEnvironmentId: environmentId },
-      select: { id: true },
-    });
-    return legacyRun !== null;
+    return result.val ?? false;
   }
 
   public async call(
@@ -125,6 +157,7 @@ export class NextRunListPresenter {
       direction = "forward",
       cursor,
       pageSize = DEFAULT_PAGE_SIZE,
+      includeHasAnyRuns = false,
     }: RunListOptions
   ) {
     //get the time values from the raw values (including a default period)
@@ -252,8 +285,13 @@ export class NextRunListPresenter {
 
     let hasAnyRuns = runs.length > 0;
 
-    if (!hasAnyRuns) {
-      hasAnyRuns = await this.#anyRunExistsInEnv(environmentId);
+    if (!hasAnyRuns && includeHasAnyRuns) {
+      hasAnyRuns = await this.#anyRunExistsInEnv(
+        runsRepository,
+        organizationId,
+        projectId,
+        environmentId
+      );
     }
 
     return {

apps/webapp/app/routes/_app.orgs.$organizationSlug.projects.$projectParam.env.$envParam.runs._index/route.tsx

@@ -111,6 +111,7 @@ export const loader = async ({ request, params }: LoaderFunctionArgs) => {
     userId,
     projectId: project.id,
     ...filters,
+    includeHasAnyRuns: true,
   });
 
   // Only persist rootOnly when no tasks are filtered. While a task filter is active,

apps/webapp/app/services/runsRepository/clickhouseRunsRepository.server.ts

@@ -35,6 +35,38 @@ export class ClickHouseRunsRepository implements IRunsRepository {
     return "clickhouse";
   }
 
+  async runExistsInEnvironment(options: {
+    organizationId: string;
+    projectId: string;
+    environmentId: string;
+    createdAtLowerBoundMs?: number;
+  }): Promise<boolean> {
+    const queryBuilder = this.options.clickhouse.taskRuns.existsQueryBuilder();
+
+    queryBuilder
+      .where("organization_id = {organizationId: String}", {
+        organizationId: options.organizationId,
+      })
+      .where("project_id = {projectId: String}", { projectId: options.projectId })
+      .where("environment_id = {environmentId: String}", { environmentId: options.environmentId });
+
+    if (typeof options.createdAtLowerBoundMs === "number") {
+      queryBuilder.where("created_at >= fromUnixTimestamp64Milli({createdAtLowerBound: Int64})", {
+        createdAtLowerBound: options.createdAtLowerBoundMs,
+      });
+    }
+
+    queryBuilder.limit(1);
+
+    const [queryError, result] = await queryBuilder.execute();
+
+    if (queryError) {
+      throw queryError;
+    }
+
+    return (result?.length ?? 0) > 0;
+  }
+
   /**
    * Runs the keyset-paginated query and returns `{ runId, createdAt }` rows
    * (one extra beyond `page.size` to signal "has more"). The ordering is always

apps/webapp/app/services/runsRepository/runsRepository.server.ts

@@ -176,6 +176,12 @@ export interface IRunsRepository {
   }>;
   countRuns(options: RunListInputOptions): Promise<number>;
   listTags(options: TagListOptions): Promise<TagList>;
+  runExistsInEnvironment(options: {
+    organizationId: string;
+    projectId: string;
+    environmentId: string;
+    createdAtLowerBoundMs?: number;
+  }): Promise<boolean>;
 }
 
 export class RunsRepository implements IRunsRepository {
@@ -189,6 +195,26 @@ export class RunsRepository implements IRunsRepository {
     return "runsRepository";
   }
 
+  async runExistsInEnvironment(options: {
+    organizationId: string;
+    projectId: string;
+    environmentId: string;
+    createdAtLowerBoundMs?: number;
+  }): Promise<boolean> {
+    return startActiveSpan(
+      "runsRepository.runExistsInEnvironment",
+      async () => this.clickHouseRunsRepository.runExistsInEnvironment(options),
+      {
+        attributes: {
+          "repository.name": "clickhouse",
+          organizationId: options.organizationId,
+          projectId: options.projectId,
+          environmentId: options.environmentId,
+        },
+      }
+    );
+  }
+
   async listRunIds(options: ListRunsOptions): Promise<RunIdsPage> {
     return startActiveSpan(
       "runsRepository.listRunIds",

internal-packages/clickhouse/src/index.ts

@@ -15,6 +15,7 @@ import {
   getTaskRunsCountQueryBuilder,
   getTaskRunTagsQueryBuilder,
   getPendingVersionIdsQueryBuilder,
+  getTaskRunExistsQueryBuilder,
 } from "./taskRuns.js";
 import {
   getSpanDetailsQueryBuilder,
@@ -228,6 +229,7 @@ export class ClickHouse {
       insertPayloadsCompactArrays: insertRawTaskRunPayloadsCompactArrays(this.writer),
       queryBuilder: getTaskRunsQueryBuilder(this.reader),
       countQueryBuilder: getTaskRunsCountQueryBuilder(this.reader),
+      existsQueryBuilder: getTaskRunExistsQueryBuilder(this.reader, { max_execution_time: 10 }),
       tagQueryBuilder: getTaskRunTagsQueryBuilder(this.reader),
       pendingVersionIdsQueryBuilder: getPendingVersionIdsQueryBuilder(this.reader),
       getTaskActivity: getTaskActivityQueryBuilder(this.reader),

internal-packages/clickhouse/src/taskRuns.ts

@@ -461,6 +461,23 @@ export function getTaskRunsCountQueryBuilder(ch: ClickhouseReader, settings?: Cl
   });
 }
 
+export const TaskRunExistsQueryResult = z.object({
+  run_exists: z.number().int(),
+});
+
+export type TaskRunExistsQueryResult = z.infer<typeof TaskRunExistsQueryResult>;
+
+// Empty-state existence probe. No FINAL (a stale/dup row still answers "a run exists").
+// Callers must filter organization_id + project_id + environment_id (the sort-key prefix).
+export function getTaskRunExistsQueryBuilder(ch: ClickhouseReader, settings?: ClickHouseSettings) {
+  return ch.queryBuilder({
+    name: "getTaskRunExists",
+    baseQuery: "SELECT 1 AS run_exists FROM trigger_dev.task_runs_v2",
+    schema: TaskRunExistsQueryResult,
+    settings,
+  });
+}
+
 export const TaskRunTagsQueryResult = z.object({
   tag: z.string(),
 });