Prisma ORM Configuration

Configure Prisma ORM for type-safe database operations and schema management in MakerKit.

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.

Definition

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.

Prisma Configuration

Understand the Prisma setup in MakerKit.

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:

packages/database/src/prisma/schema.prisma

generator client {
  provider = "prisma-client"
  output   = "./generated"
}
datasource db {
  provider = "postgresql"
}
// Models defined below...

Key points:

output = "./generated" places the client in the same package for co-location
the repo uses prisma.config.ts for schema, migrations, and datasource configuration
DATABASE_URL must be set in your environment, or Prisma falls back to the local dev URL defined in packages/database/prisma.config.ts

Client Export

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

packages/database/src/client.ts

export * from './adapters/postgres';

The actual Prisma client setup lives in packages/database/src/adapters/postgres.ts, where the app creates a singleton PrismaClient using @prisma/adapter-pg.

Database Connection

Configure DATABASE_URL in your environment:

./.env.local

# 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:

Command	Description
`pnpm --filter @kit/database prisma:generate`	Regenerate client after schema changes
`pnpm --filter @kit/database prisma:migrate`	Create and apply migrations
`pnpm --filter @kit/database prisma:studio`	Open Prisma Studio GUI at `localhost:5555`
`pnpm --filter @kit/database prisma:push`	Push schema without creating migration (dev only)

Expected output for prisma:generate:

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

Regenerate after updates

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
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 →