Next.js + Prisma + PostgreSQL

A full-stack Next.js 15 setup with Prisma ORM, PostgreSQL database, and Server Actions for mutations.

Recipe

1. Scaffold a Next.js 15 app with Tailwind and TypeScript:

   npx create-next-app@latest my-app --typescript --tailwind --app
   cd my-app

2. Install Prisma and the client:

   npm install prisma @prisma/client
   npm install -D prisma

3. Initialize Prisma with PostgreSQL:

   npx prisma init --datasource-provider postgresql

4. Define your schema in prisma/schema.prisma.
5. Set DATABASE_URL in .env.
6. Run your first migration:

   npx prisma migrate dev --name init

7. Create a Prisma client singleton at lib/prisma.ts to avoid exhausting connections during hot-reload.

Working Example

A complete Todo app with Prisma + PostgreSQL + Server Actions.

prisma/schema.prisma

generator client \{
  provider = "prisma-client-js"
\}
 
datasource db \{
  provider = "postgresql"
  url      = env("DATABASE_URL")
\}
 
model Todo \{
  id        String   @id @default(cuid())
  title     String
  completed Boolean  @default(false)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
\}

lib/prisma.ts (singleton)

import \{ PrismaClient \} from "@prisma/client";
 
const globalForPrisma = globalThis as unknown as \{
  prisma: PrismaClient | undefined;
\};
 
export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient(\{
    log: process.env.NODE_ENV === "development" ? ["query", "error", "warn"] : ["error"],
  \});
 
if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;

app/page.tsx (Server Component)

import \{ prisma \} from "@/lib/prisma";
import \{ addTodo \} from "./actions";
 
export default async function Home() \{
  const todos = await prisma.todo.findMany(\{
    orderBy: \{ createdAt: "desc" \},
  \});
 
  return (
    <main className="mx-auto max-w-xl p-8">
      <h1 className="text-2xl font-bold">Todos</h1>
 
      <form action=\{addTodo\} className="mt-4 flex gap-2">
        <input
          name="title"
          required
          className="flex-1 rounded border px-3 py-2"
          placeholder="New todo..."
        />
        <button type="submit" className="rounded bg-black px-4 py-2 text-white">
          Add
        </button>
      </form>
 
      <ul className="mt-6 space-y-2">
        \{todos.map((todo) => (
          <li key=\{todo.id\} className="rounded border p-3">
            \{todo.title\}
          </li>
        ))\}
      </ul>
    </main>
  );
\}

app/actions.ts (Server Action)

"use server";
 
import \{ prisma \} from "@/lib/prisma";
import \{ revalidatePath \} from "next/cache";
 
export async function addTodo(formData: FormData) \{
  const title = formData.get("title");
  if (typeof title !== "string" || title.trim() === "") return;
 
  await prisma.todo.create(\{
    data: \{ title: title.trim() \},
  \});
 
  revalidatePath("/");
\}

Deep Dive

How It Works

Prisma generates a fully typed client based on your schema. The Next.js Server Component runs on the server and queries Postgres directly through the Prisma client. Server Actions are POST endpoints created automatically by Next.js — form submissions invoke the action, which mutates the database and calls revalidatePath to purge the cached render so the new data appears on the next request.

The singleton pattern is critical in development. Next.js hot reload re-evaluates modules on every change, and without a singleton you would create a fresh PrismaClient per reload, quickly exhausting the database connection pool.

Variations

• Hosted PostgreSQL: Supabase, Neon, Railway, or Vercel Postgres all work — just paste their connection string into DATABASE_URL.
• Local development with SQLite: change provider = "sqlite" and use url = "file:./dev.db" for a zero-config local DB.
• Seeding: add a prisma/seed.ts script and register it under "prisma": \{ "seed": "tsx prisma/seed.ts" \} in package.json, then run npx prisma db seed.
• Prisma Studio: run npx prisma studio for a browser-based data browser and editor.
• Prisma Accelerate: connection pooling + global caching through a single prisma:// URL, ideal for serverless deployments.
• Alternative ORM: Drizzle ORM offers typed SQL and a lighter runtime.

TypeScript Notes

• Prisma auto-generates types for every model. Import with import \{ Todo \} from "@prisma/client".
• For query results with relations, use Prisma.TodoGetPayload<\{ include: \{ author: true \} \}> to derive an exact type of the returned shape.
• Server Actions can be typed as (formData: FormData) => Promise<void> or use the newer useActionState pattern with a prevState argument.
• Enable strict mode in tsconfig.json to catch nullable fields — Prisma honors ? in schema as T | null in TS.

Gotchas

1. Singleton or die. Without the globalThis singleton in lib/prisma.ts, Next.js dev mode will leak connections until Postgres refuses new ones.
2. Missing DATABASE_URL. Prisma won't even generate without it. Put it in .env (not just .env.local) because the Prisma CLI reads .env.
3. Forgetting prisma generate. After changing schema.prisma, regenerate the client or your types drift. prisma migrate dev does this automatically, but prisma db push and manual schema edits may not.
4. Production migrations. Use prisma migrate deploy in CI/CD, never prisma migrate dev — the latter can prompt interactively and drop data.
5. Binary targets for deployment. On platforms like Vercel or AWS Lambda you may need to add binaryTargets = ["native", "rhel-openssl-3.0.x"] to the generator block, or your deployment will fail with "Query engine binary not found."
6. Connection limits in serverless. Each Lambda/Edge invocation can open a fresh connection. Use PgBouncer, Prisma Accelerate, or a pooled connection string.
7. Edge runtime incompatibility. The standard Prisma client does not run on Edge. Use Prisma Accelerate or the Driver Adapters preview for edge support.

Alternatives

FAQs

generator client \{
  provider      = "prisma-client-js"
  binaryTargets = ["native", "rhel-openssl-3.0.x"]
\}

import \{ Prisma \} from "@prisma/client";
 
type TodoWithAuthor = Prisma.TodoGetPayload<\{
  include: \{ author: true \};
\}>;

export async function addTodo(formData: FormData): Promise<void> \{ /* ... */ \}

export async function addTodo(prevState: State, formData: FormData): Promise<State> \{ /* ... */ \}

Related

• Next.js Data: Server Actions
• React Libraries: Prisma
• Next.js Patterns: Environment Variables
• Next.js Data: Revalidation