feat: add ttl support at task and config levels (#3196)

Add TTL (time-to-live) defaults at task-level and config-level, with
precedence: per-trigger > task > config > dev default (10m).

Docs PR: #3200 (merge after packages are released)

Author: nicktrn

.changeset/quiet-dogs-fly.md

@@ -0,0 +1,7 @@
+---
+"@trigger.dev/sdk": patch
+"@trigger.dev/core": patch
+"trigger.dev": patch
+---
+
+Add support for setting TTL (time-to-live) defaults at the task level and globally in trigger.config.ts, with per-trigger overrides still taking precedence

apps/webapp/CLAUDE.md

@@ -99,6 +99,17 @@ The `app/v3/` directory name is misleading - most code is actively used by V2. O
 
 Some services (e.g., `cancelTaskRun.server.ts`, `batchTriggerV3.server.ts`) branch on `RunEngineVersion` to support both V1 and V2. When editing these, only modify V2 code paths.
 
+## Performance: Trigger Hot Path
+
+The `triggerTask.server.ts` service is the **highest-throughput code path** in the system. Every API trigger call goes through it. Keep it fast:
+
+- **Do NOT add database queries** to `triggerTask.server.ts` or `batchTriggerV3.server.ts`. Task defaults (TTL, etc.) are resolved via `backgroundWorkerTask.findFirst()` in the queue concern (`queues.server.ts`) - one query per request, in mutually exclusive branches depending on locked/non-locked path. Piggyback on the existing query instead of adding new ones.
+- **Two-stage resolution pattern**: Task metadata is resolved in two stages by design:
+  1. **Trigger time** (`triggerTask.server.ts`): Only TTL is resolved from task defaults. Everything else uses whatever the caller provides.
+  2. **Dequeue time** (`dequeueSystem.ts`): Full `BackgroundWorkerTask` is loaded and retry config, machine config, maxDuration, etc. are resolved against task defaults.
+- If you need to add a new task-level default, **add it to the existing `select` clause** in the `backgroundWorkerTask.findFirst()` query — do NOT add a second query. If the default doesn't need to be known at trigger time, resolve it at dequeue time instead.
+- Batch triggers (`batchTriggerV3.server.ts`) follow the same pattern — keep batch paths equally fast.
+
 ## Prisma Query Patterns
 
 - **Always use `findFirst` instead of `findUnique`.** Prisma's `findUnique` has an implicit DataLoader that batches concurrent calls into a single `IN` query. This batching cannot be disabled and has active bugs even in Prisma 6.x: uppercase UUIDs returning null (#25484, confirmed 6.4.1), composite key SQL correctness issues (#22202), and 5-10x worse performance than manual DataLoader (#6573, open since 2021). `findFirst` is never batched and avoids this entire class of issues.

apps/webapp/app/runEngine/concerns/queues.server.ts

@@ -73,19 +73,20 @@ export class DefaultQueueManager implements QueueManager {
   ): Promise<QueueProperties> {
     let queueName: string;
     let lockedQueueId: string | undefined;
+    let taskTtl: string | null | undefined;
 
     // Determine queue name based on lockToVersion and provided options
     if (lockedBackgroundWorker) {
       // Task is locked to a specific worker version
       const specifiedQueueName = extractQueueName(request.body.options?.queue);
+
       if (specifiedQueueName) {
-        // A specific queue name is provided
+        // A specific queue name is provided, validate it exists for the locked worker
         const specifiedQueue = await this.prisma.taskQueue.findFirst({
-          // Validate it exists for the locked worker
           where: {
             name: specifiedQueueName,
             runtimeEnvironmentId: request.environment.id,
-            workers: { some: { id: lockedBackgroundWorker.id } }, // Ensure the queue is associated with any task of the locked worker
+            workers: { some: { id: lockedBackgroundWorker.id } },
           },
         });
 
@@ -95,11 +96,26 @@ export class DefaultQueueManager implements QueueManager {
             }'.`
           );
         }
+
         // Use the validated queue name directly
         queueName = specifiedQueue.name;
         lockedQueueId = specifiedQueue.id;
+
+        // Only fetch task for TTL if caller didn't provide a per-trigger TTL
+        if (request.body.options?.ttl === undefined) {
+          const lockedTask = await this.prisma.backgroundWorkerTask.findFirst({
+            where: {
+              workerId: lockedBackgroundWorker.id,
+              runtimeEnvironmentId: request.environment.id,
+              slug: request.taskId,
+            },
+            select: { ttl: true },
+          });
+
+          taskTtl = lockedTask?.ttl;
+        }
       } else {
-        // No specific queue name provided, use the default queue for the task on the locked worker
+        // No queue override - fetch task with queue to get both default queue and TTL
         const lockedTask = await this.prisma.backgroundWorkerTask.findFirst({
           where: {
             workerId: lockedBackgroundWorker.id,
@@ -118,6 +134,8 @@ export class DefaultQueueManager implements QueueManager {
           );
         }
 
+        taskTtl = lockedTask.ttl;
+
         if (!lockedTask.queue) {
           // This case should ideally be prevented by earlier checks or schema constraints,
           // but handle it defensively.
@@ -131,6 +149,7 @@ export class DefaultQueueManager implements QueueManager {
             }'.`
           );
         }
+
         // Use the task's default queue name
         queueName = lockedTask.queue.name;
         lockedQueueId = lockedTask.queue.id;
@@ -145,7 +164,9 @@ export class DefaultQueueManager implements QueueManager {
       }
 
       // Get queue name using the helper for non-locked case (handles provided name or finds default)
-      queueName = await this.getQueueName(request);
+      const taskInfo = await this.getTaskQueueInfo(request);
+      queueName = taskInfo.queueName;
+      taskTtl = taskInfo.taskTtl;
     }
 
     // Sanitize the final determined queue name once
@@ -161,21 +182,27 @@ export class DefaultQueueManager implements QueueManager {
     return {
       queueName,
       lockedQueueId,
+      taskTtl,
     };
   }
 
-  async getQueueName(request: TriggerTaskRequest): Promise<string> {
+  private async getTaskQueueInfo(
+    request: TriggerTaskRequest
+  ): Promise<{ queueName: string; taskTtl?: string | null }> {
     const { taskId, environment, body } = request;
     const { queue } = body.options ?? {};
 
     // Use extractQueueName to handle double-wrapped queue objects
-    const queueName = extractQueueName(queue);
-    if (queueName) {
-      return queueName;
-    }
+    const overriddenQueueName = extractQueueName(queue);
 
     const defaultQueueName = `task/${taskId}`;
 
+    // When caller provides both a queue override and a per-trigger TTL,
+    // we don't need any DB queries - the per-trigger TTL takes precedence
+    if (overriddenQueueName && body.options?.ttl !== undefined) {
+      return { queueName: overriddenQueueName, taskTtl: undefined };
+    }
+
     // Find the current worker for the environment
     const worker = await findCurrentWorkerFromEnvironment(environment, this.prisma);
 
@@ -185,7 +212,21 @@ export class DefaultQueueManager implements QueueManager {
         environmentId: environment.id,
       });
 
-      return defaultQueueName;
+      return { queueName: overriddenQueueName ?? defaultQueueName, taskTtl: undefined };
+    }
+
+    // When queue is overridden, we only need TTL from the task (no queue join needed)
+    if (overriddenQueueName) {
+      const task = await this.prisma.backgroundWorkerTask.findFirst({
+        where: {
+          workerId: worker.id,
+          runtimeEnvironmentId: environment.id,
+          slug: taskId,
+        },
+        select: { ttl: true },
+      });
+
+      return { queueName: overriddenQueueName, taskTtl: task?.ttl };
     }
 
     const task = await this.prisma.backgroundWorkerTask.findFirst({
@@ -205,7 +246,7 @@ export class DefaultQueueManager implements QueueManager {
         environmentId: environment.id,
       });
 
-      return defaultQueueName;
+      return { queueName: defaultQueueName, taskTtl: undefined };
     }
 
     if (!task.queue) {
@@ -215,10 +256,10 @@ export class DefaultQueueManager implements QueueManager {
         queueConfig: task.queueConfig,
       });
 
-      return defaultQueueName;
+      return { queueName: defaultQueueName, taskTtl: task.ttl };
     }
 
-    return task.queue.name ?? defaultQueueName;
+    return { queueName: task.queue.name ?? defaultQueueName, taskTtl: task.ttl };
   }
 
   async validateQueueLimits(

apps/webapp/app/runEngine/services/triggerTask.server.ts

@@ -191,11 +191,6 @@ export class RunEngineTriggerTaskService {
         }
       }
 
-      const ttl =
-        typeof body.options?.ttl === "number"
-          ? stringifyDuration(body.options?.ttl)
-          : body.options?.ttl ?? (environment.type === "DEVELOPMENT" ? "10m" : undefined);
-
       // Get parent run if specified
       const parentRun = body.options?.parentRunId
         ? await this.prisma.taskRun.findFirst({
@@ -251,10 +246,23 @@ export class RunEngineTriggerTaskService {
           })
         : undefined;
 
-      const { queueName, lockedQueueId } = await this.queueConcern.resolveQueueProperties(
-        triggerRequest,
-        lockedToBackgroundWorker ?? undefined
-      );
+      const { queueName, lockedQueueId, taskTtl } =
+        await this.queueConcern.resolveQueueProperties(
+          triggerRequest,
+          lockedToBackgroundWorker ?? undefined
+        );
+
+      // Resolve TTL with precedence: per-trigger > task-level > dev default
+      let ttl: string | undefined;
+
+      if (body.options?.ttl !== undefined) {
+        ttl =
+          typeof body.options.ttl === "number"
+            ? stringifyDuration(body.options.ttl)
+            : body.options.ttl;
+      } else {
+        ttl = taskTtl ?? (environment.type === "DEVELOPMENT" ? "10m" : undefined);
+      }
 
       if (!options.skipChecks) {
         const queueSizeGuard = await this.queueConcern.validateQueueLimits(

apps/webapp/app/runEngine/types.ts

@@ -48,6 +48,7 @@ export type QueueValidationResult =
 export type QueueProperties = {
   queueName: string;
   lockedQueueId?: string;
+  taskTtl?: string | null;
 };
 
 export type LockedBackgroundWorker = Pick<
@@ -61,7 +62,6 @@ export interface QueueManager {
     request: TriggerTaskRequest,
     lockedBackgroundWorker?: LockedBackgroundWorker
   ): Promise<QueueProperties>;
-  getQueueName(request: TriggerTaskRequest): Promise<string>;
   validateQueueLimits(
     env: AuthenticatedEnvironment,
     queueName: string,

apps/webapp/app/v3/services/createBackgroundWorker.server.ts

@@ -6,7 +6,7 @@ import {
   QueueManifest,
   TaskResource,
 } from "@trigger.dev/core/v3";
-import { BackgroundWorkerId } from "@trigger.dev/core/v3/isomorphic";
+import { BackgroundWorkerId, stringifyDuration } from "@trigger.dev/core/v3/isomorphic";
 import type { BackgroundWorker, TaskQueue, TaskQueueType } from "@trigger.dev/database";
 import cronstrue from "cronstrue";
 import { $transaction, Prisma, PrismaClientOrTransaction } from "~/db.server";
@@ -286,6 +286,8 @@ async function createWorkerTask(
         triggerSource: task.triggerSource === "schedule" ? "SCHEDULED" : "STANDARD",
         fileId: tasksToBackgroundFiles?.get(task.id) ?? null,
         maxDurationInSeconds: task.maxDuration ? clampMaxDuration(task.maxDuration) : null,
+        ttl:
+          typeof task.ttl === "number" ? stringifyDuration(task.ttl) ?? null : task.ttl ?? null,
         queueId: queue.id,
         payloadSchema: task.payloadSchema as any,
       },

internal-packages/database/prisma/migrations/20260309120000_add_ttl_to_background_worker_task/migration.sql

@@ -0,0 +1,2 @@
+-- AlterTable
+ALTER TABLE "public"."BackgroundWorkerTask" ADD COLUMN IF NOT EXISTS "ttl" TEXT;

internal-packages/database/prisma/schema.prisma

@@ -648,6 +648,8 @@ model BackgroundWorkerTask {
 
   maxDurationInSeconds Int?
 
+  ttl String?
+
   triggerSource TaskTriggerSource @default(STANDARD)
 
   payloadSchema Json?

packages/cli-v3/src/entryPoints/dev-index-worker.ts

@@ -132,6 +132,20 @@ if (typeof config.maxDuration === "number") {
   });
 }
 
+// If the config has a TTL, we need to apply it to all tasks that don't have a TTL
+if (config.ttl !== undefined) {
+  tasks = tasks.map((task) => {
+    if (task.ttl === undefined) {
+      return {
+        ...task,
+        ttl: config.ttl,
+      } satisfies TaskManifest;
+    }
+
+    return task;
+  });
+}
+
 // If the config has a machine preset, we need to apply it to all tasks that don't have a machine preset
 if (typeof config.machine === "string") {
   tasks = tasks.map((task) => {

packages/cli-v3/src/entryPoints/managed-index-worker.ts

@@ -132,6 +132,20 @@ if (typeof config.maxDuration === "number") {
   });
 }
 
+// If the config has a TTL, we need to apply it to all tasks that don't have a TTL
+if (config.ttl !== undefined) {
+  tasks = tasks.map((task) => {
+    if (task.ttl === undefined) {
+      return {
+        ...task,
+        ttl: config.ttl,
+      } satisfies TaskManifest;
+    }
+
+    return task;
+  });
+}
+
 // If the config has a machine preset, we need to apply it to all tasks that don't have a machine preset
 if (typeof config.machine === "string") {
   tasks = tasks.map((task) => {