Prisma ORM Configuration

Configure Prisma ORM for type-safe database operations and schema management in the TanStack Start Prisma SaaS Kit.

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 as db 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 the kit.

Package Structure

packages/database/
├── src/
│   ├── prisma/
│   │   ├── schema.prisma         # Data model definitions
│   │   ├── migrations/           # Version-controlled migrations
│   │   └── generated/            # Auto-generated Prisma Client
│   ├── adapters/
│   │   └── postgres.ts           # Singleton PrismaClient setup
│   ├── client.ts                 # Exported database client
│   └── index.ts                  # Package exports
├── prisma.config.ts              # Prisma configuration
└── 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 path, migrations path, 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

Prisma Config

Prisma reads packages/database/prisma.config.ts:

packages/database/prisma.config.ts

import path from 'node:path';
import type { PrismaConfig } from 'prisma';
export default {
  schema: path.join('src', 'prisma', 'schema.prisma'),
  migrations: {
    path: path.join('src', 'prisma', 'migrations'),
  },
  datasource: {
    url:
      process.env.DATABASE_URL ||
      'postgresql://postgres:postgres@127.0.0.1:54333/postgres',
  },
} satisfies PrismaConfig;

Client Export

The client is instantiated and exported through 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 kit creates a singleton PrismaClient using the @prisma/adapter-pg driver adapter over a pg connection pool. It is re-exported as db from @kit/database.

Database Connection

Configure DATABASE_URL in your environment:

./.env.local

# Local development with Docker (default host port 54333)
DATABASE_URL="postgresql://postgres:postgres@127.0.0.1:54333/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 (`prisma migrate dev`)
`pnpm --filter @kit/database prisma:studio`	Open Prisma Studio GUI
`pnpm --filter @kit/database prisma:reset`	Drop and recreate the database, re-applying all migrations
`pnpm --filter @kit/database prisma:push`	Push schema without creating a migration (dev only)

You can also reset the database from the root with pnpm run db:reset.

Regenerate after updates

When you update the 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, run pnpm --filter @kit/database prisma:generate to sync the client with any schema changes
Running commands from the wrong directory - Always use pnpm --filter @kit/database from the project root
Multiple Prisma Client instances - Causes connection pool exhaustion; use the singleton db export
Editing generated files - Changes are overwritten on next generate; modify schema.prisma instead

Next: Schema Overview →