Understanding postgres.js connection management in Trigger.dev v3

[leedia-tech]

I'm using postgres.js and noticed your Drizzle example creates the db instance outside the task.

I'm wondering:

1. Task isolation: Do tasks run in separate workers/processes, or share the same Node process?

2. Connection lifecycle: If I create a postgres instance outside the task:

   const sql = postgres(process.env.DATABASE_URL!)
   
   export const myTask = task({
     id: "my-task",
     run: async (payload) => {
       return sql`SELECT * FROM users`
     }
   })

   Is this instance shared across all executions, or does each worker get its own?

3. Connection cleanup: postgres.js requires sql.end() to properly close connections. Should I handle this cleanup or does the worker lifecycle manage it?

[sunnypatell]

@leedia-tech each task run gets its own child process via child_process.fork() (source). they don't share a Node process by default.

1. task isolation

by default, every run forks a fresh process. after the task completes, the process gets SIGTERM then SIGKILL. with processKeepAlive enabled, the same process can handle multiple sequential runs (up to maxExecutionsPerProcess, default 50).

2. connection lifecycle

without processKeepAlive: each run re-executes module-level code, so each gets its own sql instance. nothing is shared across runs.

with processKeepAlive: the module-level sql persists and is reused across runs on the same process, which is actually ideal for a connection pool.

your pattern matches the official drizzle guide which does the same (db instance at module level), so you're good.

3. cleanup

you don't need to manually call sql.end(). when the process is killed after the run, the OS reclaims all TCP connections. postgres.js connections are lazy (zero connections until first query) and auto-reconnect if a connection is lost.

one edge case: if you use waitpoints (triggerAndWait, wait.for), trigger.dev checkpoints the process via CRIU and restores it in a new network context. the old TCP connections will be dead, but postgres.js handles this transparently since it reconnects on the next query.

for explicit control, you can use the middleware pattern:

// init.ts (auto-loaded by trigger.dev)
import { tasks } from "@trigger.dev/sdk/v3";

tasks.middleware("db", async ({ next }) => {
  await next();
});

tasks.onWait("db", async () => {
  await sql.end({ timeout: 5 }); // free connections during checkpoint
});

tasks.onResume("db", async () => {
  // postgres.js reconnects lazily, nothing needed here
});

but honestly for postgres.js this is optional since it handles reconnection automatically.

ref: how it works | tasks overview (lifecycle hooks) | processKeepAlive changelog | postgres.js lazy connections

[KeuqS]

One practical caveat to add to the existing explanation: the module-level client is scoped to a worker process, not to the whole Trigger.dev project. With processKeepAlive enabled, that client can be reused by sequential runs handled by that process, so the effective database connection count is roughly the pool size multiplied by the number of warm workers.

For that reason, I would:

• keep the postgres.js client at module scope;
• size its max connections with the worker count in mind;
• avoid calling sql.end() in every task finally block, because that defeats reuse when processKeepAlive is enabled;
• close it in an onWait hook only when a task is checkpointed, then let postgres.js reconnect lazily on resume.

This keeps the connection lifecycle per-process and avoids accidentally creating a new pool for every execution while still releasing connections before a waitpoint checkpoint.

Useful references: task execution model, processKeepAlive, Drizzle guide, and postgres.js connections.