refactor(run-ops): one RUN_OPS_* env var family, drop TASK_RUN_* aliases

The NEW-DB writer had two names (TASK_RUN_DATABASE_URL from the original split +
RUN_OPS_DATABASE_URL used by the schema/docker/.env), bridged by a `??` coalesce. Collapse
to a single canonical RUN_OPS_* family and delete the aliases (nothing deployed uses them yet):

- TASK_RUN_DATABASE_URL              -> RUN_OPS_DATABASE_URL (the writer; the ?? and the
  runOpsNewDatabaseUrl indirection are gone — consumers read env.RUN_OPS_DATABASE_URL directly)
- TASK_RUN_LEGACY_DATABASE_URL       -> RUN_OPS_LEGACY_DATABASE_URL
- TASK_RUN_DATABASE_READ_REPLICA_URL -> RUN_OPS_DATABASE_READ_REPLICA_URL
- TASK_RUN_DATABASE_DIRECT_URL       -> removed (dead; the schema no longer declares directUrl)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: d-cs

.server-changes/run-ops-auto-migrate.md

@@ -3,4 +3,4 @@ area: webapp
 type: feature
 ---
 
-Automatically migrate the dedicated run-ops database on deploy (entrypoint + `@internal/run-ops-database` deploy/status scripts) and resolve its connection through one canonical `RUN_OPS_DATABASE_URL` (falling back to `TASK_RUN_DATABASE_URL`) so migrations always target the DB the app connects to.
+Automatically migrate the dedicated run-ops database on deploy (entrypoint + `@internal/run-ops-database` deploy/status scripts), and standardize the run-ops DB connection on a single `RUN_OPS_DATABASE_URL` family (dropping the `TASK_RUN_DATABASE_URL` aliases) so migrations always target the DB the app connects to.

apps/webapp/app/db.server.ts

@@ -10,7 +10,7 @@ import {
 import { RunOpsPrismaClient } from "@internal/run-ops-database";
 import invariant from "tiny-invariant";
 import { z } from "zod";
-import { env, runOpsNewDatabaseUrl } from "./env.server";
+import { env } from "./env.server";
 import { logger } from "./services/logger.server";
 import { isValidDatabaseUrl } from "./utils/db";
 import {
@@ -237,16 +237,16 @@ export function selectRunOpsTopology(
 // nothing new. The builders apply the SAME wrapper pair the control-plane
 // singletons use (captureInfrastructureErrors(tagDatasource(role, raw))).
 const runOpsTopology: RunOpsTopology = singleton("runOpsTopology", () => {
-  const newUrl = runOpsNewDatabaseUrl;
+  const newUrl = env.RUN_OPS_DATABASE_URL;
   // Gate on the opt-in flag too: the distinct-DB sentinel only runs when the flag is on.
-  const splitEnabled = env.RUN_OPS_SPLIT_ENABLED && !!newUrl && !!env.TASK_RUN_LEGACY_DATABASE_URL;
+  const splitEnabled = env.RUN_OPS_SPLIT_ENABLED && !!newUrl && !!env.RUN_OPS_LEGACY_DATABASE_URL;
 
   return selectRunOpsTopology(
     {
       splitEnabled,
-      legacyUrl: env.TASK_RUN_LEGACY_DATABASE_URL,
+      legacyUrl: env.RUN_OPS_LEGACY_DATABASE_URL,
       newUrl,
-      newReplicaUrl: env.TASK_RUN_DATABASE_READ_REPLICA_URL,
+      newReplicaUrl: env.RUN_OPS_DATABASE_READ_REPLICA_URL,
     },
     {
       controlPlane: { writer: prisma, replica: $replica },
@@ -278,8 +278,8 @@ export const runOpsSplitReadEnabled: boolean = computeRunOpsSplitReadEnabled({
   newReplica: runOpsNewReplicaClient,
   controlPlaneWriter: prisma,
   controlPlaneReplica: $replica,
-  hasNewUrl: !!runOpsNewDatabaseUrl,
-  hasLegacyUrl: !!env.TASK_RUN_LEGACY_DATABASE_URL,
+  hasNewUrl: !!env.RUN_OPS_DATABASE_URL,
+  hasLegacyUrl: !!env.RUN_OPS_LEGACY_DATABASE_URL,
 });
 
 // Boot-time interlock: if the flag is on but the distinct-DB sentinel does not

apps/webapp/app/env.server.ts

@@ -132,36 +132,24 @@ const EnvironmentSchema = z
     // Explicit positive opt-in. Split behavior is unreachable unless this is true
     // AND the distinct-DB sentinel confirms the two URLs are physically distinct DBs.
     RUN_OPS_SPLIT_ENABLED: BoolEnv.default(false),
-    // Canonical connection URL for the dedicated run-ops DB — drives the runtime pool, the split
-    // decision, replication, and migrations (resolved via runOpsNewDatabaseUrl). Takes precedence
-    // over TASK_RUN_DATABASE_URL, which remains as the compatibility fallback.
+    // Canonical connection URL for the dedicated NEW run-ops DB — drives the runtime pool, the split
+    // decision, replication, and migrations. Optional so single-DB installs never set it.
     RUN_OPS_DATABASE_URL: z
       .string()
       .refine(isValidDatabaseUrl, "RUN_OPS_DATABASE_URL is invalid")
       .optional(),
-    // The NEW dedicated run-ops DB writer. Optional so single-DB installs never set it.
-    TASK_RUN_DATABASE_URL: z
-      .string()
-      .refine(isValidDatabaseUrl, "TASK_RUN_DATABASE_URL is invalid")
-      .optional(),
-    // The NEW run-ops DB unpooled/direct endpoint (Prisma migrate/introspection;
-    // connection poolers break advisory locks). Consumed by the migrations.
-    TASK_RUN_DATABASE_DIRECT_URL: z
-      .string()
-      .refine(isValidDatabaseUrl, "TASK_RUN_DATABASE_DIRECT_URL is invalid")
-      .optional(),
     // The LEGACY run-ops DB (the control-plane DB during the transition). When unset, legacy
     // run-ops reuses the existing DATABASE_URL (legacy run-ops == control-plane DB initially).
-    TASK_RUN_LEGACY_DATABASE_URL: z
+    RUN_OPS_LEGACY_DATABASE_URL: z
       .string()
-      .refine(isValidDatabaseUrl, "TASK_RUN_LEGACY_DATABASE_URL is invalid")
+      .refine(isValidDatabaseUrl, "RUN_OPS_LEGACY_DATABASE_URL is invalid")
       .optional(),
     // The NEW dedicated run-ops DB read replica. Optional; self-host never sets it.
     // Refined (unlike the unrefined control-plane DATABASE_READ_REPLICA_URL) so a malformed run-ops
     // replica URL fails boot loudly rather than silently degrading — do not align it down to the CP shape.
-    TASK_RUN_DATABASE_READ_REPLICA_URL: z
+    RUN_OPS_DATABASE_READ_REPLICA_URL: z
       .string()
-      .refine(isValidDatabaseUrl, "TASK_RUN_DATABASE_READ_REPLICA_URL is invalid")
+      .refine(isValidDatabaseUrl, "RUN_OPS_DATABASE_READ_REPLICA_URL is invalid")
       .optional(),
     // --- Control-plane datasource repoint. Additive-only. ---
     // Optional control-plane DB. Unset (self-host/single-DB) -> getClient()/getReplicaClient() fall back to
@@ -1725,9 +1713,9 @@ const EnvironmentSchema = z
 
     // --- Run-ops DB split — second replication source (the NEW dedicated run-ops DB). ---
     // Cloud-only; only consulted when isSplitEnabled() is true. Self-host never sets these.
-    // The NEW source's connection URL is runOpsNewDatabaseUrl (RUN_OPS_DATABASE_URL ?? TASK_RUN_DATABASE_URL);
-    // these add the NEW source's replication slot/publication and an explicit per-source enable so it can be
-    // brought up independently of the legacy source during the transition.
+    // The NEW source's connection URL is RUN_OPS_DATABASE_URL; these add the NEW source's replication
+    // slot/publication and an explicit per-source enable so it can be brought up independently of the
+    // legacy source during the transition.
     RUN_REPLICATION_NEW_SLOT_NAME: z.string().default("task_runs_to_clickhouse_v2"),
     RUN_REPLICATION_NEW_PUBLICATION_NAME: z
       .string()
@@ -2103,10 +2091,3 @@ const EnvironmentSchema = z
 
 export type Environment = z.infer<typeof EnvironmentSchema>;
 export const env = EnvironmentSchema.parse(process.env);
-
-// Canonical connection URL for the NEW dedicated run-ops DB. RUN_OPS_DATABASE_URL is the canonical
-// name; TASK_RUN_DATABASE_URL is the compatibility fallback. Every NEW-DB consumer (connect path,
-// split-decision predicates, replication source, migration runner) resolves through this single
-// value so they can never disagree about which physical database the split targets.
-export const runOpsNewDatabaseUrl: string | undefined =
-  env.RUN_OPS_DATABASE_URL ?? env.TASK_RUN_DATABASE_URL;

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

@@ -1,5 +1,5 @@
 import invariant from "tiny-invariant";
-import { env, runOpsNewDatabaseUrl } from "~/env.server";
+import { env } from "~/env.server";
 import { clickhouseFactory } from "~/services/clickhouse/clickhouseFactoryInstance.server";
 import { singleton } from "~/utils/singleton";
 import { isSplitEnabled } from "~/v3/runOpsMigration/splitMode.server";
@@ -172,7 +172,7 @@ function initializeRunsReplicationInstance() {
         const sources = buildReplicationSources({
           splitEnabled,
           legacyUrl: DATABASE_URL,
-          newUrl: runOpsNewDatabaseUrl,
+          newUrl: env.RUN_OPS_DATABASE_URL,
           newSourceOverride: env.RUN_REPLICATION_NEW_ENABLED === "disabled" ? false : undefined,
           legacySlotName: env.RUN_REPLICATION_SLOT_NAME,
           legacyPublicationName: env.RUN_REPLICATION_PUBLICATION_NAME,

apps/webapp/app/v3/runOpsMigration/controlPlaneResolver.server.ts

@@ -5,7 +5,7 @@ import type {
   RuntimeEnvironmentType,
 } from "@trigger.dev/database";
 import { prisma, $replica } from "~/db.server";
-import { env, runOpsNewDatabaseUrl } from "~/env.server";
+import { env } from "~/env.server";
 import {
   ControlPlaneCache,
   DEFAULT_CP_CACHE_MAX_ENTRIES,
@@ -449,7 +449,7 @@ export class ControlPlaneResolver {
 // run-ops topology factory uses); the async isSplitEnabled() distinct-DB sentinel is enforced
 // at boot elsewhere and is never awaited on a resolver hot path.
 const SPLIT_ENABLED =
-  env.RUN_OPS_SPLIT_ENABLED && !!runOpsNewDatabaseUrl && !!env.TASK_RUN_LEGACY_DATABASE_URL;
+  env.RUN_OPS_SPLIT_ENABLED && !!env.RUN_OPS_DATABASE_URL && !!env.RUN_OPS_LEGACY_DATABASE_URL;
 
 export const controlPlaneResolver = new ControlPlaneResolver({
   controlPlanePrimary: prisma,

apps/webapp/app/v3/runOpsMigration/splitMode.server.ts

@@ -4,7 +4,7 @@
  * infer split-vs-single from URL string-equality — distinctness is proven by the
  * runtime sentinel.
  */
-import { env, runOpsNewDatabaseUrl } from "~/env.server";
+import { env } from "~/env.server";
 import { logger } from "~/services/logger.server";
 import { probeDistinctDatabases as defaultProbe } from "./distinctDbSentinel.server";
 
@@ -30,7 +30,7 @@ export async function computeSplitEnabled(
   // Both URLs are required to even consider a split.
   if (!config.legacyUrl || !config.newUrl) {
     deps.logger?.warn(
-      "RUN_OPS_SPLIT_ENABLED is on but TASK_RUN_LEGACY_DATABASE_URL / TASK_RUN_DATABASE_URL are not both set; staying single-DB."
+      "RUN_OPS_SPLIT_ENABLED is on but RUN_OPS_LEGACY_DATABASE_URL / RUN_OPS_DATABASE_URL are not both set; staying single-DB."
     );
     return false;
   }
@@ -70,8 +70,8 @@ export function isSplitEnabled(): Promise<boolean> {
     cached = computeSplitEnabled(
       {
         flagEnabled: env.RUN_OPS_SPLIT_ENABLED,
-        legacyUrl: env.TASK_RUN_LEGACY_DATABASE_URL,
-        newUrl: runOpsNewDatabaseUrl,
+        legacyUrl: env.RUN_OPS_LEGACY_DATABASE_URL,
+        newUrl: env.RUN_OPS_DATABASE_URL,
       },
       { logger }
     );

apps/webapp/app/v3/runStore.server.ts

@@ -10,7 +10,7 @@ import {
   runOpsNewPrismaClient,
   runOpsNewReplicaClient,
 } from "~/db.server";
-import { env, runOpsNewDatabaseUrl } from "~/env.server";
+import { env } from "~/env.server";
 import { singleton } from "~/utils/singleton";
 
 type BuildRunStoreDeps = {
@@ -76,7 +76,7 @@ export function buildRunStore(deps: BuildRunStoreDeps): RunStore {
 // RUN_OPS_SPLIT_ENABLED. Reads must fan out across both DBs so a run that lives on the new
 // DB stays visible even with the flag off (matches the db.server topology factory). The flag
 // governs write/mint residency + migration via isSplitEnabled(), not read visibility.
-const ROUTING_ENABLED = !!runOpsNewDatabaseUrl && !!env.TASK_RUN_LEGACY_DATABASE_URL;
+const ROUTING_ENABLED = !!env.RUN_OPS_DATABASE_URL && !!env.RUN_OPS_LEGACY_DATABASE_URL;
 
 // Resolve the run-ops handles, tolerating contexts where they are absent — tests that mock
 // ~/db.server minimally omit them, and accessing a missing export under vi.mock throws. A

apps/webapp/test/runsReplicationInstance.test.ts

@@ -126,35 +126,19 @@ describe("buildReplicationSources (pure)", () => {
     expect(sources[0].id).toBe("legacy");
   });
 
-  it("RUN_OPS_DATABASE_URL takes precedence: new source pgConnectionUrl === RUN_OPS_DATABASE_URL when both are supplied", () => {
+  it("new source pgConnectionUrl === the provided RUN_OPS_DATABASE_URL", () => {
     const runOpsUrl = "postgres://run-ops-dedicated";
-    const taskRunUrl = "postgres://task-run-legacy-alias";
 
     const sources = buildReplicationSources({
       ...baseArgs,
       splitEnabled: true,
-      // Simulates env.RUN_OPS_DATABASE_URL ?? env.TASK_RUN_DATABASE_URL with RUN_OPS set
-      newUrl: runOpsUrl ?? taskRunUrl,
+      newUrl: runOpsUrl,
     });
 
     expect(sources).toHaveLength(2);
     expect(sources[1]!.id).toBe("new");
     expect(sources[1]!.pgConnectionUrl).toBe(runOpsUrl);
   });
-
-  it("falls back to TASK_RUN_DATABASE_URL when RUN_OPS_DATABASE_URL is absent", () => {
-    const taskRunUrl = "postgres://task-run-legacy-alias";
-
-    const sources = buildReplicationSources({
-      ...baseArgs,
-      splitEnabled: true,
-      // Simulates env.RUN_OPS_DATABASE_URL ?? env.TASK_RUN_DATABASE_URL with RUN_OPS unset
-      newUrl: undefined ?? taskRunUrl,
-    });
-
-    expect(sources).toHaveLength(2);
-    expect(sources[1]!.pgConnectionUrl).toBe(taskRunUrl);
-  });
 });
 
 describe("assertReplicationCoversSplit (boot gate-coupling)", () => {

docker/scripts/entrypoint.sh

@@ -15,7 +15,7 @@ fi
 
 # Run-ops split: migrate the dedicated NEW run-ops database only when it is configured. Single-DB
 # installs never set the URL, so this is a no-op there.
-if [ -n "$RUN_OPS_DATABASE_URL" ] || [ -n "$TASK_RUN_DATABASE_URL" ]; then
+if [ -n "$RUN_OPS_DATABASE_URL" ]; then
   if [ "$SKIP_RUN_OPS_MIGRATIONS" != "1" ]; then
     echo "Running run-ops migrations"
     pnpm --filter @internal/run-ops-database db:migrate:deploy
@@ -24,7 +24,7 @@ if [ -n "$RUN_OPS_DATABASE_URL" ] || [ -n "$TASK_RUN_DATABASE_URL" ]; then
     echo "SKIP_RUN_OPS_MIGRATIONS=1, skipping run-ops migrations."
   fi
 else
-  echo "RUN_OPS_DATABASE_URL/TASK_RUN_DATABASE_URL not set, skipping run-ops migrations."
+  echo "RUN_OPS_DATABASE_URL not set, skipping run-ops migrations."
 fi
 
 if [ "$SKIP_DASHBOARD_AGENT_MIGRATIONS" != "1" ]; then

internal-packages/run-ops-database/scripts/migrate.mjs

@@ -1,7 +1,7 @@
 // Run Prisma migrations against the dedicated NEW run-ops database (the second physical DB in the
 // split). It owns its own migration history, so it is migrated independently of the control-plane
-// DB. The connection is resolved the same way the webapp resolves it (RUN_OPS_DATABASE_URL, falling
-// back to TASK_RUN_DATABASE_URL) so migrations always target the DB the app connects to.
+// DB. Connects via RUN_OPS_DATABASE_URL — the same var the webapp uses — so migrations always
+// target the DB the app connects to.
 //
 // Usage: node scripts/migrate.mjs [deploy|status]   (defaults to deploy)
 import { spawnSync } from "node:child_process";
@@ -45,13 +45,13 @@ const redact = (url) => url.replace(/:\/\/[^@]*@/, "://***@");
 
 const subcommand = process.argv[2] === "status" ? "status" : "deploy";
 
-const databaseUrl = resolveVar("RUN_OPS_DATABASE_URL") || resolveVar("TASK_RUN_DATABASE_URL");
+const databaseUrl = resolveVar("RUN_OPS_DATABASE_URL");
 
 if (!databaseUrl) {
-  // Single-DB installs never set these — safe no-op. A genuinely-expected DB is gated on by the caller.
+  // Single-DB installs never set it — safe no-op. A genuinely-expected DB is gated on by the caller.
   console.log(
-    `run-ops migrate ${subcommand}: neither RUN_OPS_DATABASE_URL nor TASK_RUN_DATABASE_URL is set ` +
-      "(checked env and .env). No dedicated run-ops database configured — skipping."
+    `run-ops migrate ${subcommand}: RUN_OPS_DATABASE_URL is not set (checked env and .env). ` +
+      "No dedicated run-ops database configured — skipping."
   );
   process.exit(0);
 }