Prisma ORM Configuration

Prisma is configured in the @kit/database package with the schema at packages/database/src/prisma/schema.prisma. The generated client lives in packages/database/src/prisma/generated and is exported via packages/database/src/client.ts for application use.

This guide is part of the Database Configuration documentation.

Prisma Client is an auto-generated, type-safe database client that Prisma creates from your schema. It provides methods like findMany(), create(), and update() with full TypeScript inference for all your models.

Package Structure

packages/database/
├── src/
│   ├── prisma/
│   │   ├── schema.prisma         # Data model definitions
│   │   ├── migrations/           # Version-controlled migrations
│   │   └── generated/            # Auto-generated Prisma Client
│   ├── client.ts                 # Exported database client
│   └── index.ts                  # Package exports
└── package.json

Configuration Files

Schema Definition

The Prisma schema at packages/database/src/prisma/schema.prisma defines:

generator client {
  provider      = "prisma-client-js"
  output        = "./generated"
  binaryTargets = ["native", "rhel-openssl-3.0.x"]
}
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}
// Models defined below...

Key points:

• output = "./generated" places the client in the same package for co-location
• binaryTargets includes rhel-openssl-3.0.x for deployment on Linux (Vercel, Railway)
• DATABASE_URL must be set in your environment

Client Export

The client is instantiated and exported in packages/database/src/client.ts:

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

This pattern prevents multiple Prisma Client instances during hot reload in development.

Database Connection

Configure DATABASE_URL in your environment:

# Local development with Docker
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres"
# Production (example for Neon)
DATABASE_URL="postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/dbname?sslmode=require"

Connection string format:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public

Common Commands

Run these from the project root:

Expected output for prisma:generate:

Environment variables loaded from .env
Prisma schema loaded from packages/database/src/prisma/schema.prisma
✔ Generated Prisma Client to ./packages/database/src/prisma/generated

When you update the MakerKit codebase (e.g., after git pull or updating to a new version), the Prisma schema may have changed. Always regenerate the Prisma client after updates:

pnpm --filter @kit/database prisma:generate

Failing to regenerate can cause TypeScript errors or runtime issues if your client is out of sync with the schema.

Common Pitfalls

• Not regenerating after codebase updates - After pulling updates or upgrading MakerKit, run pnpm --filter @kit/database prisma:generate to sync the client with any schema changes
• Running commands from wrong directory - Always use pnpm --filter @kit/database from the project root, not cd packages/database && pnpm prisma
• Missing binaryTargets - Deployment fails with "Query engine not found"; add the correct target for your deployment platform
• Multiple Prisma Client instances - Causes connection pool exhaustion; use the singleton pattern shown above
• Editing generated files - Changes are overwritten on next generate; modify schema.prisma instead

Next: Schema Overview →