Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Schema reference

Every type, attribute, and function available in schema.ruprizzle. See Dialect notes for backend-specific mappings and limitations.

Top-level blocks

datasource

datasource db {
  provider = "postgres" | "mysql" | "sqlite"
  url      = env("DATABASE_URL") | "literal://..."
  strict   = true
}
  • provider: the database backend. Supported: postgres, mysql, sqlite.
  • url: an environment variable name or a literal URL. env() is recommended; literal URLs are useful for quick tests.
  • strict: when true, the CLI and runtime reject constructs that the active provider cannot express well.

generator

generator client {
  output            = "src/db"
  module_name       = "db"
  max_include_depth = 3
}
  • output: directory where the Rust client is emitted.
  • module_name: the name your crate uses to mod the output.
  • max_include_depth: the deepest level of nested include the codegen will generate.

Scalars

TypePostgresMySQL / MariaDBSQLiteNotes
StringTEXTVARCHAR(255)TEXT
IntINTEGERINTINTEGER32-bit signed.
BigIntBIGINTBIGINTINTEGERSQLite stores in 64-bit INTEGER.
FloatDOUBLE PRECISIONDOUBLEREAL
DecimalNUMERICDECIMAL(65,30)TEXTAvoid arithmetic on SQLite.
BooleanBOOLEANTINYINT(1)INTEGERMySQL and SQLite use 0/1.
DateTimeTIMESTAMPTZDATETIME(6)TEXTISO-8601 in SQLite.
DateDATEDATETEXT
TimeTIMETIMETEXT
UuidUUIDCHAR(36)TEXT
JsonJSONBJSONTEXTSQLite stores as text; JSON1 filters work.
BytesBYTEABLOBBLOB

Native type annotations

Use @db.<native> to override the default physical type for the active dialect.

AnnotationPostgresMySQL / MariaDBSQLite
@db.UuidUUIDCHAR(36)TEXT
@db.VarChar(n)VARCHAR(n)VARCHAR(n)TEXT
@db.TextTEXTTEXTTEXT
@db.IntegerINTEGERINTINTEGER
@db.SmallIntSMALLINTSMALLINTINTEGER
@db.BigIntBIGINTBIGINTINTEGER
@db.SerialSERIALAUTO_INCREMENTINTEGER
@db.BigSerialBIGSERIALAUTO_INCREMENTINTEGER
@db.RealREALFLOATREAL
@db.DoubleDOUBLE PRECISIONDOUBLEREAL
@db.Decimal(p,s)NUMERIC(p,s)DECIMAL(p,s)TEXT
@db.BooleanBOOLEANTINYINT(1)INTEGER
@db.TimestampTIMESTAMPDATETIME(6)TEXT
@db.TimestamptzTIMESTAMPTZDATETIME(6)TEXT
@db.DateDATEDATETEXT
@db.TimeTIMETIMETEXT
@db.JsonJSONBJSONTEXT
@db.JsonbJSONBJSONTEXT
@db.BytesBYTEABLOBBLOB
@db.Generated("...")generated columngenerated columnstored as text

Field attributes

  • @id — primary key. Auto-detected for Int/BigInt/Uuid with @default.
  • @default(<expr>) — default value. See the expressions below.
  • @unique — single-column unique constraint.
  • @map("column_name") — override the physical column name.
  • @relation(...) — define the owner side of a relation.
  • @ignore — omit from the generated client.
  • @db.<native> — override the native type.
  • @updatedAt — automatically set to now() on every update (Postgres/MySQL).
  • @deletedAt — marks the model soft-deletable. The field must be DateTime?; the parser rejects any other type with a diagnostic. Generated queries then add WHERE <column> IS NULL by default — see soft deletes for the opt-outs.

Default expressions

ExpressionReturnsExample
autoincrement()integerid Int @id @default(autoincrement())
uuid7()Uuidid Uuid @id @default(uuid7())
now()DateTimecreatedAt DateTime @default(now())
dbgenerated("...")dialect-specifictoken String @default(dbgenerated("gen_random_uuid()"))
literal valuethe literalrole Role @default(USER)

Model-level attributes

  • @@map("table_name") — override the physical table name.
  • @@unique([a, b, ...]) — composite unique constraint.
  • @@index([a, b, ...]) — index on the listed fields.
  • @@id([a, b, ...]) — composite primary key.
  • @@ignore — omit the model from the generated client.

Index attributes

Basic index

@@index([email])

Named index

@@index([email, createdAt], name: "user_email_created_idx")

Index type

@@index([email], type: "Hash")   // Postgres only

Expression index

@@index([lower(email)])

Expression indexes are supported on Postgres and SQLite 3.31+ where the expression can be emitted directly.

Partial index

@@index([email], where: "verified = true")

Partial indexes are supported on Postgres and SQLite.

Generated columns

A generated column is computed from other columns or expressions:

model User {
  id       Int    @id @default(autoincrement())
  first    String
  last     String
  fullName String @db.Generated("first | ' ' | last")
}

On SQLite, generated columns are stored as text or as the underlying native representation, depending on the dialect.

Enums

enum Role {
  USER
  ADMIN
}

Postgres uses a native CREATE TYPE. MySQL and SQLite emulate enums with a CHECK constraint on TEXT.

Relations

Only the owner side of a relation carries @relation:

model Post {
  authorId Uuid @map("author_id")
  author   User @relation(fields: [authorId], references: [id], onDelete: Cascade)
}

model User {
  posts Post[]
}

@relation arguments

  • fields — the foreign-key column(s) on this model.
  • references — the target column(s) on the related model.
  • onDelete / onUpdate — referential action.
  • name — optional relation name, used for disambiguation.
  • map — override the physical foreign-key constraint name.

Referential actions

Supported: Cascade, Restrict, SetNull, SetDefault, NoAction.

Many-to-many

Many-to-many relations are explicit join models:

model Tag {
  id   Uuid    @id @default(uuid7())
  name String  @unique
  posts PostTag[]
}

model PostTag {
  id      Uuid  @id @default(uuid7())
  postId  Uuid  @map("post_id")
  tagId   Uuid  @map("tag_id")
  post    Post  @relation(fields: [postId], references: [id], onDelete: Cascade)
  tag     Tag   @relation(fields: [tagId], references: [id], onDelete: Cascade)

  @@unique([postId, tagId])
}

PostgreSQL extensions

datasource db {
  provider   = "postgres"
  url        = env("DATABASE_URL")
  extensions = ["uuid-ossp", "pgcrypto"]
}

uuid-ossp is required for uuid7()-style defaults unless another extension provides equivalent functionality.

Naming

  • Model and field identifiers use camelCase by convention.
  • @@map and @map are used to produce snake_case physical names.
  • Physical names are limited by the target database (Postgres: 63 bytes; MySQL: 64 characters; SQLite: no hard limit).

Example schema

datasource db {
  provider = "postgres"
  url      = env("DATABASE_URL")
  extensions = ["uuid-ossp"]
}

generator client {
  output      = "src/db"
  module_name = "db"
  max_include_depth = 3
}

model User {
  id        Uuid     @id @default(uuid7())
  email     String   @unique @db.VarChar(255)
  name      String?
  role      Role     @default(USER)
  metadata  Json?    @db.Jsonb
  createdAt DateTime @default(now()) @map("created_at") @db.Timestamptz
  posts     Post[]

  @@index([email, createdAt])
  @@map("users")
}

model Post {
  id        Uuid     @id @default(uuid7())
  title     String
  published Boolean  @default(false)
  authorId  Uuid     @map("author_id")
  author    User     @relation(fields: [authorId], references: [id], onDelete: Cascade)

  @@index([authorId], where: "published = true")
  @@map("posts")
}

enum Role {
  USER
  ADMIN
}