107 lines
4.6 KiB
Markdown
107 lines
4.6 KiB
Markdown
# Welcome to Prisma ORM!
|
|
|
|
Prisma ORM lets you query your database in simple, easy-to-read TypeScript. Define what your data looks like, and Prisma ORM gives you a fully typed client — with autocomplete for every table, column, and relation.
|
|
|
|
This project is set up for PostgreSQL. Prisma ORM also supports other databases.
|
|
|
|
## Requirements
|
|
|
|
- **PostgreSQL 15 or newer.** Older servers are not supported. Run `SELECT version()` against your server to verify.
|
|
- The CLI never connects to your database without explicit consent. Pass `--probe-db` to `npx prisma orm init` if you want `init` to verify the server version itself.
|
|
|
|
## Your data contract
|
|
|
|
Your data contract is the heart of your application. It lives at [`src/prisma/contract.prisma`](src/prisma/contract.prisma) and describes your models:
|
|
|
|
```prisma
|
|
model User {
|
|
id Int @id @default(autoincrement())
|
|
email String @unique
|
|
username String?
|
|
name String?
|
|
}
|
|
```
|
|
|
|
Every model you define in your contract can be queried from your app. Your editor will autocomplete the query methods and show you what type each model field is:
|
|
|
|
```typescript
|
|
import { db } from './src/prisma/db';
|
|
|
|
const user = await db.orm.public.User
|
|
.where({ email: '[email protected]' })
|
|
.first();
|
|
|
|
// Your editor will show the type of user as
|
|
// { id: number; email: string; username: string | null; name: string | null; createdAt: Date; posts: Post[] } | null
|
|
```
|
|
|
|
Your contract has two companion files in the same directory:
|
|
|
|
- **`contract.json`** — this tells your application what models exist, just like `package-lock.json` tells your package manager what dependencies your project has
|
|
- **`contract.d.ts`** — this powers autocomplete and type checking in your editor
|
|
|
|
Commit both files to git. When you change your contract, run `npx prisma contract emit` to update them.
|
|
|
|
If you use a framework like Next.js or Vite, the Prisma ORM plugin will do this for you automatically.
|
|
|
|
## Configuration
|
|
|
|
[`prisma.config.ts`](prisma.config.ts) tells the CLI where your contract lives and how to connect to your database. It loads environment variables from `.env` automatically:
|
|
|
|
```typescript
|
|
import 'dotenv/config';
|
|
import { definePrismaConfig } from '@prisma/cli-engine';
|
|
import { defineConfig as ormConfig } from '@prisma/orm-postgres/config';
|
|
|
|
export default definePrismaConfig({
|
|
orm: ormConfig({
|
|
contract: './src/prisma/contract.prisma',
|
|
db: {
|
|
connection: process.env['DATABASE_URL']!,
|
|
},
|
|
}),
|
|
});
|
|
```
|
|
|
|
Notice the `DATABASE_URL` above? It's defined in your [`.env`](./.env) file:
|
|
|
|
```env
|
|
DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
|
|
```
|
|
|
|
You can customize how your environment variables are loaded by changing or removing the `import 'dotenv/config'` line.
|
|
|
|
## Quick reference
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
npx prisma contract emit # Update contract.json and contract.d.ts
|
|
npx prisma db init # Create tables in the database
|
|
npx prisma migration status # Show migration status
|
|
```
|
|
|
|
### Files
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| [`src/prisma/contract.prisma`](src/prisma/contract.prisma) | Your data contract — define your models here |
|
|
| [`prisma.config.ts`](prisma.config.ts) | CLI configuration |
|
|
| [`src/prisma/db.ts`](src/prisma/db.ts) | Database client — `import { db } from './src/prisma/db'` |
|
|
| `src/prisma/contract.json` | Compiled contract (generated) |
|
|
| `src/prisma/contract.d.ts` | Contract types (generated) |
|
|
|
|
### Workflow
|
|
|
|
1. Edit [`src/prisma/contract.prisma`](src/prisma/contract.prisma) to add or change models.
|
|
2. Run `npx prisma contract emit` to regenerate the contract.
|
|
3. Query your models — your IDE will autocomplete everything.
|
|
|
|
## Monorepo notes (pnpm workspaces)
|
|
|
|
If this project lives inside a pnpm workspace, a few things are worth knowing:
|
|
|
|
- **Catalogs.** When the workspace's `pnpm-workspace.yaml` defines a `catalogs` entry for `prisma` or `@prisma/orm-postgres`, pnpm uses the catalog version everywhere — `init` does too. If you wanted the published `latest` instead, update or remove the catalog entry, then re-run `pnpm install`.
|
|
- **`pnpm dlx`.** `pnpm dlx prisma@latest orm init …` works in any directory. Inside a workspace, pnpm still resolves dependencies through the workspace's catalog/overrides rather than the registry; expect the installed Prisma ORM packages to reflect the workspace's catalog rather than `latest`.
|
|
- **`pnpm` → `npm` fallback.** If `pnpm` ever fails to install Prisma ORM with a `workspace:*` or `catalog:` resolution error (a leak in a published artefact), `init` falls back to `npm install` and surfaces a warning. Once the offending package republishes a clean version you can switch back with `pnpm install`.
|