CLAUDE.md

1# Database Package
2 
3Prisma 6.14.0 client and schema for PostgreSQL (`@trigger.dev/database`).
4 
5## Schema
6 
7Located at `prisma/schema.prisma`. Key models include TaskRun, BackgroundWorker, BackgroundWorkerTask, WorkerDeployment, RuntimeEnvironment, and Project.
8 
9### Engine Versions
10 
11```prisma
12enum RunEngineVersion {
13  V1  // Retired v3 engine - no longer executes; kept for historical rows and rejection
14  V2  // Current (run-engine + redis-worker)
15}
16```
17 
18New code should always target V2.
19 
20## Creating Migrations
21 
221. Edit `prisma/schema.prisma`
232. Generate migration:
24```bash
25   cd internal-packages/database
26   pnpm run db:migrate:dev:create --name "descriptive_name"
27```
283. **Clean up generated migration** - remove extraneous lines for:
29   - `_BackgroundWorkerToBackgroundWorkerFile`
30   - `_BackgroundWorkerToTaskQueue`
31   - `_TaskRunToTaskRunTag`
32   - `_WaitpointRunConnections`
33   - `_completedWaitpoints`
34   - `SecretStore_key_idx`
35   - Various `TaskRun` indexes (unless you added them)
364. Apply migration:
37```bash
38   pnpm run db:migrate:deploy && pnpm run generate
39```
40 
41## Index Migration Rules
42 
43When adding indexes to **existing tables**:
44 
45- Use `CREATE INDEX CONCURRENTLY IF NOT EXISTS` to avoid table locks in production
46- CONCURRENTLY indexes **must be in their own separate migration file** - they cannot be combined with other schema changes (PostgreSQL requirement)
47- Only add one index per migration file
48- Pre-apply the index manually in production before deploying the migration (Prisma will skip creation if the index already exists)
49 
50Indexes on **newly created tables** (in the same migration as `CREATE TABLE`) do not need CONCURRENTLY and can be in the same migration file.
51 
52When adding an index on a **new column on an existing table**, use two migrations:
531. First migration: `ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...` (the column)
542. Second migration: `CREATE INDEX CONCURRENTLY IF NOT EXISTS ...` (the index, in its own file)
55 
56See `README.md` in this directory and `ai/references/migrations.md` for the full index workflow.
57 
58## Read Replicas
59 
60Use `$replica` from `~/db.server` for read-heavy queries in the webapp.
61