# Prisma ORM Configuration

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

*Canonical: https://makerkit.dev/docs/tanstack-prisma/database/prisma*

---

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](./overview) documentation.

{% callout title="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.
{% /callout %}

{% sequence title="Prisma Configuration" description="Understand the Prisma setup in the kit." %}
[Package Structure](#package-structure)

[Configuration Files](#configuration-files)

[Database Connection](#database-connection)

[Common Commands](#common-commands)
{% /sequence %}

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

```prisma {% title="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`:

```typescript {% title="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`:

```typescript {% title="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:

```bash {% title="./.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`.

{% callout title="Regenerate after updates" type="warning" %}
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:

```bash
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.
{% /callout %}

## 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 →](./schema)