Prisma + PostgreSQL with Next.js: Setup and Best Practices

Prisma is the most ergonomic way to talk to a Postgres database from a Next.js app. A few setup details make the difference between a smooth experience and mysterious production errors.

The schema is your source of truth

Everything starts with `schema.prisma`. Model your domain there — users, products, orders — and let Prisma generate a fully-typed client. Well-named models with the right indexes now save painful migrations later.

Use a client singleton

In development, Next.js hot-reload will create a new Prisma client on every change and exhaust your connection pool. Cache the client on `globalThis` in non-production so you reuse one instance. This is the single most common Prisma-in-Next.js gotcha.

Migrations vs db push

• Use `prisma migrate dev` to create versioned migration files you commit — best for teams and production.
• Use `prisma db push` for rapid prototyping when you don't need migration history.
• Pick one workflow and stick to it; mixing them causes drift that's annoying to reconcile.

Pooling for serverless

Serverless functions open many short-lived connections, which can overwhelm Postgres. Use a pooled connection string (PgBouncer, or a provider like Neon or Supabase's pooler) for the runtime, and a direct connection for migrations.

KitCraft templates come with a production-ready Prisma setup — a client singleton, a sensible schema, and pooled connections configured — so your data layer works reliably from local dev to serverless production.