# Prisma ORM Configuration

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

*Canonical: https://makerkit.dev/docs/nextjs-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 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 MakerKit." %}
[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
│   ├── 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:

```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, 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`:

```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 app creates a singleton `PrismaClient` using `@prisma/adapter-pg`.

## Database Connection

Configure `DATABASE_URL` in your environment:

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

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

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