Understanding Prisma Schema Structure
1. Defining Datasource Block
| Field | Required | Notes |
|---|---|---|
provider | Yes | DB engine name |
url | Yes | Connection string or env("...") |
directUrl | No | Bypass pooler for migrations |
shadowDatabaseUrl | No | For migration shadow DB |
relationMode | No | "foreignKeys" | "prisma" |
schemas | No | PG multi-schema (preview) |
2. Configuring Generator Block
| Field | Description |
|---|---|
provider | prisma-client-js, prisma-client (ESM), custom |
output | Path to write generated client |
previewFeatures | Array of opt-in feature names |
binaryTargets | Compile targets |
engineType | library | binary | client |
3. Creating Model Definitions
| Element | Syntax |
|---|---|
| Keyword | model ModelName { ... } |
| Field | name Type modifier? @attribute |
| Naming | PascalCase models, camelCase fields |
| DB mapping | @@map("table_name") |
Example: Minimal model
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
createdAt DateTime @default(now())
posts Post[]
@@map("users")
}4. Defining Enum Types
| Aspect | Notes |
|---|---|
| Syntax | enum Name { VALUE1 VALUE2 } |
| Naming | PascalCase enum, UPPER_SNAKE values |
| Mapping | VALUE @map("db_value") |
| SQLite | Not supported (use String) |
5. Using Comments and Documentation
| Syntax | Purpose |
|---|---|
// comment | Developer comment (ignored) |
/// doc comment | Triple-slash, appears in client JSDoc |
6. Understanding Schema Syntax Rules
| Rule | Detail |
|---|---|
| One datasource | Only a single datasource block allowed |
| Multiple generators | Allowed (e.g., client + erd) |
| No semicolons | Whitespace-delimited |
| Case sensitive | Identifiers and attributes |
| Reserved names | Avoid PrismaClient, Prisma as model names |
7. Organizing Multi-File Schemas
| Concept | Notes |
|---|---|
| Preview feature | prismaSchemaFolder |
| Layout | prisma/schema/*.prisma |
| Cross-file refs | Models across files resolve automatically |
| CLI | --schema prisma/schema |
8. Validating Schema Syntax
npx prisma validate
npx prisma validate --schema=./prisma/schema.prisma| Check | Detected |
|---|---|
| Syntax errors | Bad tokens, missing braces |
| Missing relations | Dangling back-references |
| Type mismatches | Incompatible @db types |
9. Formatting Schema Files
| Command | Effect |
|---|---|
prisma format | Aligns columns, normalizes whitespace |
| VS Code | Prisma extension formats on save |
10. Using Schema Extensions
| Extension | Use |
|---|---|
PostgreSQL extensions | Declare via extensions = [pgcrypto, citext] (preview) |
| Custom generators | e.g., prisma-erd-generator, prisma-zod-generator |