<!-- Generated from models/_canonical by scripts/build-model-variants.js. Edit the canonical source, not this file. Behavioural profile for ChatGPT: scripts/model-profiles.json -->

#Scope contract

FILE_ISOLATION: Modify only files inside the scope the task names. Reading elsewhere is allowed; writing outside it is not, and a needed out-of-scope change is reported, not made. SIGNATURE_PINNING: Before implementing, write the exact signatures you will add or change (name, parameters, return type). Implement to those signatures; if one must change, say so before changing it. TYPE_CONTRACTS: Every public function carries explicit parameter and return types. No any, untyped dict, or interface{} at a module boundary.

---

#Purpose

Rules for Prisma specifically. General ORM discipline is Database/orm; this covers Prisma's own sharp edges — the client lifecycle, prisma migrate, and the places where the generated SQL differs from what the schema implies.

---

#One client, module scope

ts
// src/lib/prisma.ts
import { PrismaClient } from "@prisma/client";

const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({ log: ["warn", "error"] });

if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

The globalThis cache is not a hack — Next.js and most dev servers hot-reload modules, and a fresh PrismaClient per reload exhausts max_connections within minutes.

Never construct a PrismaClient inside a request handler or a serverless function body. Each instance opens its own pool.

In serverless, additionally set a pooled connection string and a small limit:

ini
DATABASE_URL="postgresql://…/db?pgbouncer=true&connection_limit=1&pool_timeout=20"
DIRECT_URL="postgresql://…/db"     # migrations bypass the pooler

pgbouncer=true disables prepared statements, which transaction-mode pooling cannot support. directUrl in the datasource block is what prisma migrate uses — migrations must not go through a transaction pooler. → Database/postgres

---

#Schema modelling

prisma
model Order {
  id        String      @id @default(uuid(7)) @db.Uuid
  tenantId  String      @map("tenant_id") @db.Uuid
  status    OrderStatus @default(PENDING)
  totalCents BigInt     @map("total_cents")
  currency  String      @db.Char(3)
  createdAt DateTime    @default(now())    @map("created_at") @db.Timestamptz(3)
  updatedAt DateTime    @updatedAt         @map("updated_at") @db.Timestamptz(3)
  tenant    Tenant      @relation(fields: [tenantId], references: [id], onDelete: Cascade)

  @@index([tenantId, createdAt(sort: Desc)])
  @@map("orders")
}

Never create an index manually in the database without also declaring it in schema.prisma. prisma migrate dev diffs against the schema and will generate a DROP INDEX.

Prisma does not support CREATE INDEX CONCURRENTLY. On a large table, edit the generated migration SQL by hand. → Database/migration

---

#Migration workflow

Never run prisma migrate dev against a shared or production database. It can drop and recreate the schema when it detects drift.

Never use prisma db push on anything with data you care about. It has no history and no rollback path.

Review the generated migration.sql in the pull request. Prisma will emit a column drop or a type change that rewrites the table without flagging the cost.

---

#Queries

ts
// Explicit projection — never return the whole entity to an API caller
const users = await prisma.user.findMany({
  where: { tenantId },
  select: { id: true, email: true },
  orderBy: { createdAt: "desc" },
  take: 20,
});

• include and select are mutually exclusive at one level. Nest select inside include to project a relation.
• Prisma issues separate queries per relation by default and joins in the client. Use relationJoinType: "query" vs "join" (relationJoins preview / GA depending on version) deliberately, and read the logged SQL either way.
• findMany with no take will happily return the whole table. Always paginate.
• Deep pagination: use cursor + take, not skip.

ts
// Keyset pagination — constant cost at any depth
prisma.order.findMany({ take: 20, skip: 1, cursor: { id: lastId }, orderBy: { id: "asc" } });

Nested writes are a single transaction — use them rather than hand-rolling one:

ts
await prisma.order.create({ data: { tenantId, items: { create: lineItems } } });

$transaction([...]) with an array runs sequentially in one transaction; $transaction(async (tx) => …) gives you the interactive form. Keep network calls out of both. → Database/transactions

---

#Anti-patterns

---

#Checklist

• A single module-scope PrismaClient, cached on globalThis in development
• Serverless deployments use a pooled URL with pgbouncer=true and directUrl
• @db.Timestamptz on every DateTime; BigInt minor units for money
• onDelete declared on every relation
• Every index is declared in schema.prisma
• Concurrent index creation is hand-edited into migrations for large tables
• migrate deploy is the only migration command used outside local dev
• db push is not used against data that matters
• Generated migration.sql is reviewed in the pull request
• All list queries paginate; deep pagination uses cursor
• Responses are projected with select, never the raw model
• Transactions contain no network calls