Next.js boilerplate with Prisma

One client, imported from one place

• src/db/prisma.ts exports the only PrismaClient in this repo. Import it: import { prisma } from "@/db/prisma";
• Never write new PrismaClient() anywhere else, not in a route handler, not in a helper, not in a test setup file. Each instance is its own connection pool, and in next dev a per-module instance is recreated on every hot reload until Postgres refuses new connections.
• Model types, enums and the Prisma namespace come from the generated client: import type { User, Prisma } from "@/generated/prisma/client";. Never import from @prisma/client. Since Prisma 7 it is only the runtime the generated client uses, and it exports no models.
• The client runs on the driver adapter in src/db/driver.ts. Do not build a second adapter, pg pool or Neon pool for Prisma somewhere else; change the pool settings there.
• Do not call prisma.$disconnect() in request-handling code. It belongs in one-shot scripts only, which use disconnect() from @/db/orm.
• @/db re-exports the same client as db, plus recordAudit(). Code that has to compile under either ORM imports from there and nowhere else: there is no ORM-neutral query layer in this repo, and @/db/orm (sql, ping, transaction, disconnect) is Prisma-specific by design.
• Feature queries import prisma directly and live next to the feature that owns the table.

Select only the fields you need

• Default to select. A bare findMany() fetches every column of every row, including the ones you added last week (password hashes, tokens, large JSON blobs) and then serialises them across the server/client boundary.
• Use select (not include) when you need a subset of a relation: select: { id: true, author: { select: { id: true, name: true } } }.
• Never return a raw Prisma model straight to a client component. Map it to an explicit response shape so a new column cannot leak by accident.
• Always bound a list query: take plus a cursor or skip. An unbounded findMany is a production incident waiting for your table to grow.

Do not hand-roll N+1

• Fetch relations in one query with include/select, or batch the ids and use where: { id: { in: ids } }. A findMany followed by await inside a for loop over the results is the bug this rule exists for.
• Promise.all over a hundred findUnique calls is still a hundred queries. It is faster than the loop and still wrong.
• For counts and sums use _count, aggregate or groupBy rather than loading rows and reducing in JavaScript.

Raw SQL

• Use the typed API first. When you genuinely need SQL, use the tagged template sql from @/db/orm or prisma.$queryRaw: values inside ${} become bind parameters.
• $queryRawUnsafe and $executeRawUnsafe are banned in this repo. There is no user input safe enough to concatenate into SQL.
• Raw results are not validated by Prisma. Type the return and check it before trusting the shape.

Transactions and writes

• Multi-table writes that must succeed together go through transaction() from @/db/orm.
• Keep transactions short and free of network calls. Charge the card, then open the transaction to record it, not the other way around.
• Prefer upsert over read-then-write for anything that can race, and rely on a unique constraint rather than a "does it exist?" query.

Timestamps are UTC

• Prisma 7's driver adapters send a DateTime as UTC text with no offset, and Postgres reads it in the session's time zone. So the database session must run in UTC. Hosted Neon and Supabase do, and src/db/driver.ts pins local sessions where it can. bun run verify fails on any other zone.
• A timestamp that looks shifted by your UTC offset is this problem. Fix the database's zone (alter database ... set timezone to 'UTC'), never the value in application code.

After a schema edit

Running the app before bun run db:generate gives you type errors that point at your call site and describe a model shape that no longer exists. Generate first, then debug.

prisma/schema.prisma is the source of truth for the database, and prisma/migrations/ is the history of how it got there. Both are code, both are reviewed, both are committed.

Changing the schema

• Edit schema.prisma, then immediately run bun run db:migrate. That regenerates the client, writes a migration and applies it locally. A schema edit without a migration is an unfinished change.
• Commit prisma/migrations/** in the same commit as the schema edit. Never add prisma/migrations to .gitignore, never delete or rewrite a migration that has already been pushed: production replays that exact directory.
• Never hand-edit a migration Prisma has already applied. To fix a mistake, write a new migration.
• When Prisma prints a data-loss warning during db:migrate, stop and read it. If the answer is a backfill, write the migration with bunx prisma migrate dev --create-only, add the SQL by hand, then apply.

Prisma 7 setup: leave it as it is

• The generator block stays provider = "prisma-client" with output = "../src/generated/prisma". That folder is git-ignored build output that postinstall rewrites. Never edit it, never commit it.
• No url in the datasource block. The app connects through src/db/driver.ts; the CLI reads the direct connection string from prisma.config.ts, which also loads .env.local.
• migrate dev and db push no longer regenerate the client, and nothing seeds automatically. The db:migrate and db:push scripts generate first; seed with bun run db:seed.
• The CLI may print "Update available" for a new major version. Ignore it. Moving to a new Prisma major is its own reviewed change, never a side effect.

db push is a local scratchpad

• bun run db:push is allowed only against a local or throwaway branch database, while you are still shaping a model.
• Never run db push against staging or production, and never against a database whose DATABASE_URL you did not set yourself in this shell. It writes no history and resolves a mismatch by dropping columns and tables.
• Production only ever gets prisma migrate deploy, and only from the build or a deliberate one-off command, never migrate dev, which can reset.

Writing models

• Model names are singular PascalCase (User, SubscriptionItem); use @@map to point them at snake_case table names, and @map for columns where the database name differs.
• Every foreign key needs an explicit relation and an index. Prisma indexes the implicit side of a one-to-many for you; a filtered or sorted column does not get one automatically: add @@index.
• Money is an Int count of minor units (amountCents Int), never Float and never Decimal. A currency's exponent is not always 2 (JPY and KRW have none, KWD has three) so store minor units and format with Intl.NumberFormat, which knows the exponent.
• Timestamps are DateTime @db.Timestamptz with no precision argument. @db.Timestamptz(3) truncates to milliseconds, and the Drizzle battery's timestamp(..., { withTimezone: true }) is bare TIMESTAMPTZ; a repo that switches ORM must not silently change its column types.
• Ids are String @id @default(cuid()) unless something external owns the id, or @default(dbgenerated("gen_random_uuid()")) @db.Uuid when you want the database to mint them: @default(uuid()) generates in the client instead, which is not the same column.
• @updatedAt on every table that is mutated, so drift is debuggable.
• Text that could be one of a fixed set is an enum, not a String with comments.

The slot marker

The generated block at the bottom of the schema is where the batteries you selected inserted their tables when this repo was generated. It is a normal comment now. Add your own models above or below it; do not delete tables that a battery owns (auth sessions, billing subscriptions) just because your feature does not use them.

The seed

prisma/seed.ts must stay idempotent and deterministic: upsert, no Date.now(), no random ids, no real customer data. Anyone should be able to run bun run db:seed twice and get the same database.