跳到主要内容

Prisma schema 参考

datasource

在 Prisma schema 中定义数据源

字段

datasource 块接受以下字段

名称必需类型描述
provider字符串 (postgresql, mysql, sqlite, sqlserver, mongodb, cockroachdb)描述使用哪个数据源连接器。
url字符串 (URL)包含身份验证信息的连接 URL。大多数连接器使用数据库提供的语法
shadowDatabaseUrl字符串 (URL)Prisma Migrate 使用的影子数据库的连接 URL。允许您使用云托管数据库作为影子数据库。
directUrl字符串 (URL)直接连接到数据库的连接 URL。

如果您在 url 参数中使用连接池 URL(例如,如果您使用 Prisma Accelerate 或 pgBouncer),则需要直接连接到数据库的 Prisma CLI 命令会使用 directUrl 参数中的 URL。

Prisma Studio 从 5.1.0 版本起支持 directUrl 属性。

使用 Prisma Postgres 数据库时不需要 directUrl 属性。
relationMode字符串 (foreignKeys, prisma)设置参照完整性是由数据库中的外键强制执行还是在 Prisma Client 中模拟执行。

在 3.1.1 及更高版本中为预览功能。在 4.5.0 及更高版本中,该字段名为 relationMode,之前名为 referentialIntegrity
extensions字符串列表 (PostgreSQL 扩展名称)允许您在 schema 中表示 PostgreSQL 扩展。仅在 Prisma ORM 4.5.0 及更高版本中作为 PostgreSQL 的预览功能提供。

以下 provider 可用

备注

  • 一个 schema 中只能有 一个 datasource 块。
  • datasource db 是约定俗成的名称 - 但是,您可以为您的数据源指定任何名称 - 例如,datasource mysqldatasource data

示例

指定 PostgreSQL 数据源

在此示例中,目标数据库可使用以下凭据访问

  • 用户: johndoe
  • 密码: mypassword
  • 主机: localhost
  • 端口: 5432
  • 数据库名称: mydb
  • Schema 名称: public
datasource db {
provider = "postgresql"
url = "postgresql://johndoe:mypassword@localhost:5432/mydb?schema=public"
}

在此处了解更多关于 PostgreSQL 连接字符串的信息:here

通过环境变量指定 PostgreSQL 数据源

在此示例中,目标数据库可使用以下凭据访问

  • 用户: johndoe
  • 密码: mypassword
  • 主机: localhost
  • 端口: 5432
  • 数据库名称: mydb
  • Schema 名称: public
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
}

运行需要数据库连接 URL 的 Prisma CLI 命令时(例如 prisma generate),您需要确保已设置 DATABASE_URL 环境变量。

一种方法是创建一个包含以下内容的 .env 文件。请注意,该文件必须与您的 schema.prisma 文件位于同一目录中,以便 Prisma CLI 自动识别。

DATABASE_URL=postgresql://johndoe:mypassword@localhost:5432/mydb?schema=public

指定 MySQL 数据源

在此示例中,目标数据库可使用以下凭据访问

  • 用户: johndoe
  • 密码: mypassword
  • 主机: localhost
  • 端口: 3306
  • 数据库名称: mydb
datasource db {
provider = "mysql"
url = "mysql://johndoe:mypassword@localhost:3306/mydb"
}

在此处了解更多关于 MySQL 连接字符串的信息:here

指定 MongoDB 数据源

  • 用户: root
  • 密码: password
  • 主机: cluster1.test1.mongodb.net
  • 端口: 不适用
  • 数据库名称: testing
datasource db {
provider = "mongodb"
url = "mongodb+srv://root:password@cluster1.test1.mongodb.net/testing?retryWrites=true&w=majority"
}

在此处了解更多关于 MongoDB 连接字符串的信息:here

指定 SQLite 数据源

在此示例中,目标数据库位于名为 dev.db 的文件中

datasource db {
provider = "sqlite"
url = "file:./dev.db"
}

在此处了解更多关于 SQLite 连接字符串的信息:here

指定 CockroachDB 数据源

在此示例中,目标数据库可使用以下凭据访问

  • 用户: johndoe
  • 密码: mypassword
  • 主机: localhost
  • 端口: 26257
  • 数据库名称: mydb
  • Schema 名称: public
datasource db {
provider = "cockroachdb"
url = "postgresql://johndoe:mypassword@localhost:26257/mydb?schema=public"
}

连接字符串的格式与 PostgreSQL 相同。在此处了解更多关于 PostgreSQL 连接字符串的信息:here

generator

在 Prisma schema 中定义生成器

prisma-client-js provider 的字段

generator 块接受以下字段

名称必需类型描述
provider字符串 (文件路径) 或 prisma-client-js描述要使用哪个生成器。它可以指向实现生成器的文件,或直接指定内置生成器。
output否*字符串 (文件路径)确定生成客户端的位置,了解更多默认: node_modules/.prisma/client
previewFeatures枚举列表使用智能提示查看当前可用的预览特性列表(在 Visual Studio Code 中按 Ctrl+Space)。默认: 无
engineType枚举 (librarybinary)定义要下载和使用的查询引擎类型。默认: library
binaryTargets枚举列表 (见下文)指定 Prisma Client 将运行的操作系统,以确保与查询引擎的兼容性。默认: native
重要

我们建议定义自定义输出路径,将该路径添加到 .gitignore,然后确保通过自定义构建脚本或 postinstall hook 运行 prisma generate

prisma-client provider 的字段 (抢先体验)

generator 块接受以下字段

名称必需类型描述
provider字符串 (文件路径) 或 prisma-client描述要使用哪个生成器。它可以指向实现生成器的文件,或直接指定内置生成器。
output字符串 (文件路径)确定生成客户端的位置,了解更多
previewFeatures枚举列表使用智能提示查看当前可用的预览特性列表(在 Visual Studio Code 中按 Ctrl+Space)。默认: 无
runtime枚举 (nodejs (别名 node), deno, bun, deno-deploy, workerd (别名 cloudflare), edge-light (别名 vercel), react-native)目标运行时环境。默认: nodejs
moduleFormat枚举 (esmcjs)确定生成的代码支持 ESM(使用 import)还是 CommonJS(使用 require(...))模块。除非您有充分理由使用 cjs,否则我们始终推荐 esm默认: 从环境中推断。
generatedFileExtension枚举 (tsmtscts)生成的 TypeScript 文件的文件扩展名。默认: ts
importFileExtension枚举 (ts,mts,cts,js,mjs,cjs, 空 (用于裸导入))import 语句中使用的文件扩展名。默认: 从环境中推断。

binaryTargets 选项

下表列出了所有支持的操作系统及其在binaryTargets 中指定的平台名称。

除非另有说明,否则默认支持的 CPU 架构为 x86_64。

macOS
构建操作系统Prisma 引擎构建名称
macOS Intel x86_64darwin
macOS ARM64darwin-arm64
Windows
构建操作系统Prisma 引擎构建名称
Windowswindows
Linux (x86_64 架构上的 Alpine)
构建操作系统Prisma 引擎构建名称OpenSSL
Alpine (3.17 及更新版本)linux-musl-openssl-3.0.x*3.0.x
Alpine (3.16 及更旧版本)linux-musl1.1.x

* 在 Prisma ORM 4.8.0 及更高版本中可用。

Linux (ARM64 架构上的 Alpine)
构建操作系统Prisma 引擎构建名称OpenSSL
Alpine (3.17 及更新版本)linux-musl-arm64-openssl-3.0.x*3.0.x
Alpine (3.16 及更旧版本)linux-musl-arm64-openssl-1.1.x*1.1.x

* 在 Prisma ORM 4.10.0 及更高版本中可用。

Linux (Debian), x86_64
构建操作系统Prisma 引擎构建名称OpenSSL
Debian 8 (Jessie)debian-openssl-1.0.x1.0.x
Debian 9 (Stretch)debian-openssl-1.1.x1.1.x
Debian 10 (Buster)debian-openssl-1.1.x1.1.x
Debian 11 (Bullseye)debian-openssl-1.1.x1.1.x
Debian 12 (Bookworm)debian-openssl-3.0.x3.0.x
Linux (Ubuntu), x86_64
构建操作系统Prisma 引擎构建名称OpenSSL
Ubuntu 14.04 (trusty)debian-openssl-1.0.x1.0.x
Ubuntu 16.04 (xenial)debian-openssl-1.0.x1.0.x
Ubuntu 18.04 (bionic)debian-openssl-1.1.x1.1.x
Ubuntu 19.04 (disco)debian-openssl-1.1.x1.1.x
Ubuntu 20.04 (focal)debian-openssl-1.1.x1.1.x
Ubuntu 21.04 (hirsute)debian-openssl-1.1.x1.1.x
Ubuntu 22.04 (jammy)debian-openssl-3.0.x3.0.x
Ubuntu 23.04 (lunar)debian-openssl-3.0.x3.0.x
Linux (CentOS), x86_64
构建操作系统Prisma 引擎构建名称OpenSSL
CentOS 7rhel-openssl-1.0.x1.0.x
CentOS 8rhel-openssl-1.1.x1.1.x
Linux (Fedora), x86_64
构建操作系统Prisma 引擎构建名称OpenSSL
Fedora 28rhel-openssl-1.1.x1.1.x
Fedora 29rhel-openssl-1.1.x1.1.x
Fedora 30rhel-openssl-1.1.x1.1.x
Fedora 36rhel-openssl-3.0.x3.0.x
Fedora 37rhel-openssl-3.0.x3.0.x
Fedora 38rhel-openssl-3.0.x3.0.x
Linux (Linux Mint), x86_64
构建操作系统Prisma 引擎构建名称OpenSSL
Linux Mint 18debian-openssl-1.0.x1.0.x
Linux Mint 19debian-openssl-1.1.x1.1.x
Linux Mint 20debian-openssl-1.1.x1.1.x
Linux Mint 21debian-openssl-3.0.x3.0.x
Linux (Arch Linux), x86_64
构建操作系统Prisma 引擎构建名称OpenSSL
Arch Linux 2019.09.01debian-openssl-1.1.x1.1.x
Arch Linux 2023.04.23debian-openssl-3.0.x3.0.x
Linux ARM64 (所有主要发行版,Alpine 除外)
构建操作系统Prisma 引擎构建名称OpenSSL
基于 glibc 的 Linux ARM64 发行版linux-arm64-openssl-1.0.x1.0.x
基于 glibc 的 Linux ARM64 发行版linux-arm64-openssl-1.1.x1.1.x
基于 glibc 的 Linux ARM64 发行版linux-arm64-openssl-3.0.x3.0.x

示例

使用默认的 outputpreviewFeaturesengineTypebinaryTargets 指定 prisma-client-js 生成器

generator client {
provider = "prisma-client-js"
}

请注意,上述 generator 定义与以下定义是等效的,因为它使用了 outputengineTypebinaryTargets 的默认值(以及隐式的 previewFeatures

generator client {
provider = "prisma-client-js"
output = "node_modules/.prisma/client"
engineType = "library"
binaryTargets = ["native"]
}

为 Prisma Client 指定自定义 output 位置

此示例展示了如何定义生成资源的自定义 output 位置,以覆盖默认位置。

generator client {
provider = "prisma-client-js"
output = "../src/generated/client"
}

指定自定义 binaryTargets 以确保与操作系统的兼容性

此示例展示了如何根据上表配置 Prisma Client 在 Ubuntu 19.04 (disco) 上运行。

generator client {
provider = "prisma-client-js"
binaryTargets = ["debian-openssl-1.1.x"]
}

指定指向自定义生成器实现的 provider

此示例展示了如何使用位于名为 my-generator 目录中的自定义生成器。

generator client {
provider = "./my-generator"
}

model

定义 Prisma 模型

备注

  • 模型的每个记录必须是唯一可识别的。您必须为每个模型定义至少一个以下属性

命名约定

  • 模型名称必须符合以下正则表达式: [A-Za-z][A-Za-z0-9_]*
  • 模型名称必须以字母开头,通常使用帕斯卡命名法(PascalCase)拼写
  • 模型名称应使用单数形式(例如,User 而不是 userusersUsers
  • Prisma ORM 有一些保留字,它们在内部使用,因此不能用作模型名称。您可以在此处此处找到保留字。

注意: 您可以使用@@map 属性将模型(例如 User)映射到与模型命名约定不符的另一个名称的表(例如 users)。

字段顺序

  • 在 2.3.0 及更高版本中,自省列出的模型字段顺序与数据库中相应列的顺序相同。关系字段列在标量字段之后。

示例

一个名为 User 且包含两个标量字段的模型

model User {
email String @unique // `email` can not be optional because it's the only unique field on the model
name String?
}

model 字段

字段是模型的属性。

备注

命名约定

  • 必须以字母开头
  • 通常使用驼峰命名法(camelCase)拼写
  • 必须符合以下正则表达式: [A-Za-z][A-Za-z0-9_]*

注意: 您可以使用@map 属性将字段名称映射到与字段命名约定不符的另一个名称的列:例如 myField @map("my_field")

model 字段标量类型

数据源连接器决定了每个 Prisma ORM 标量类型映射到什么原生数据库类型。类似地,生成器决定了这些类型中的每一个映射到目标编程语言中的什么类型

Prisma 模型还具有定义模型之间关系的模型字段类型

String

可变长度文本。

默认类型映射

连接器默认映射
PostgreSQLtext
SQL Servernvarchar(1000)
MySQLvarchar(191)
MongoDBString
SQLiteTEXT
CockroachDBSTRING

PostgreSQL

原生数据库类型原生数据库类型属性注意
text@db.Text
char(x)@db.Char(x)
varchar(x)@db.VarChar(x)
bit(x)@db.Bit(x)
varbit@db.VarBit
uuid@db.Uuid
xml@db.Xml
inet@db.Inet
citext@db.Citext仅在启用 Citext 扩展后可用。

MySQL

原生数据库类型原生数据库类型属性
VARCHAR(x)@db.VarChar(x)
TEXT@db.Text
CHAR(x)@db.Char(x)
TINYTEXT@db.TinyText
MEDIUMTEXT@db.MediumText
LONGTEXT@db.LongText

您可以使用 Prisma Migrate 将 @db.Bit(1) 映射到 String

model Model {
/* ... */
myField String @db.Bit(1)
}

MongoDB

String

原生数据库类型属性注意
@db.String
@db.ObjectId如果底层 BSON 类型是 OBJECT_ID(ID 字段、关系标量),则必需

Microsoft SQL Server

原生数据库类型原生数据库类型属性
char(x)@db.Char(x)
nchar(x)@db.NChar(x)
varchar(x)@db.VarChar(x)
nvarchar(x)@db.NVarChar(x)
text@db.Text
ntext@db.NText
xml@db.Xml
uniqueidentifier@db.UniqueIdentifier

SQLite

TEXT

CockroachDB

原生数据库类型原生数据库类型属性注意
STRING(x) | TEXT(x) | VARCHAR(x)@db.String(x)
CHAR(x)@db.Char(x)
"char"@db.CatalogSingleChar
BIT(x)@db.Bit(x)
VARBIT@db.VarBit
UUID@db.Uuid
INET@db.Inet

请注意,CockroachDB 目前不支持 PostgreSQL 中支持的 xmlcitext 类型。

客户端

Prisma Client JS
string

Boolean

真或假值。

默认类型映射

连接器默认映射
PostgreSQLboolean
SQL Serverbit
MySQLTINYINT(1)
MongoDBBool
SQLiteINTEGER
CockroachDBBOOL

PostgreSQL

原生数据库类型原生数据库类型属性注意
boolean@db.Boolean

MySQL

原生数据库类型原生数据库类型属性注意
TINYINT(1)@db.TinyInt(1)如果最大长度大于 1(例如 TINYINT(2)默认值不是 10NULL,则 TINYINT 映射到 Int
BIT(1)@db.Bit

MongoDB

Bool

Microsoft SQL Server

原生数据库类型原生数据库类型属性注意
bit@db.Bit

SQLite

INTEGER

CockroachDB

原生数据库类型原生数据库类型属性注意
BOOL@db.Bool

客户端

Prisma Client JS
boolean

Int

默认类型映射

连接器默认映射
PostgreSQLinteger
SQL Serverint
MySQLINT
MongoDBInt
SQLiteINTEGER
CockroachDBINT

PostgreSQL

原生数据库类型原生数据库类型属性注意
integer | int, int4@db.Integer
smallint | int2@db.SmallInt
smallserial | serial2@db.SmallInt @default(autoincrement())
serial | serial4@db.Int @default(autoincrement())
oid@db.Oid

MySQL

原生数据库类型原生数据库类型属性注意
INT@db.Int
INT UNSIGNED@db.UnsignedInt
SMALLINT@db.SmallInt
SMALLINT UNSIGNED@db.UnsignedSmallInt
MEDIUMINT@db.MediumInt
MEDIUMINT UNSIGNED@db.UnsignedMediumInt
TINYINT@db.TinyInt如果最大长度大于 1(例如 TINYINT(2)默认值不是 10NULL,则 TINYINT 映射到 IntTINYINT(1) 映射到 Boolean
TINYINT UNSIGNED@db.UnsignedTinyIntTINYINT(1) UNSIGNED 映射到 Int,而不是 Boolean
YEAR@db.Year

MongoDB

Int

原生数据库类型属性注意
@db.Int
@db.Long

Microsoft SQL Server

原生数据库类型原生数据库类型属性注意
int@db.Int
smallint@db.SmallInt
tinyint@db.TinyInt
bit@db.Bit

SQLite

INTEGER

CockroachDB

原生数据库类型原生数据库类型属性注意
INTEGER | INT | INT8@db.Int8请注意,这与 PostgreSQL 不同,在 PostgreSQL 中 integerintint4 的别名,并映射到 @db.Integer
INT4@db.Int4
INT2 | SMALLINT@db.Int2
SMALLSERIAL | SERIAL2@db.Int2 @default(autoincrement())
SERIAL | SERIAL4@db.Int4 @default(autoincrement())
SERIAL8 | BIGSERIAL@db.Int8 @default(autoincrement())

客户端

Prisma Client JS
number

BigInt

BigInt2.17.0 及更高版本中可用。

默认类型映射

连接器默认映射
PostgreSQLbigint
SQL Serverint
MySQLBIGINT
MongoDBLong
SQLiteINTEGER
CockroachDBINTEGER

PostgreSQL

原生数据库类型原生数据库类型属性注意
bigint | int8@db.BigInt
bigserial | serial8@db.BigInt @default(autoincrement())

MySQL

原生数据库类型原生数据库类型属性注意
BIGINT@db.BigInt
SERIAL@db.UnsignedBigInt @default(autoincrement())

MongoDB

Long

Microsoft SQL Server

原生数据库类型原生数据库类型属性注意
bigint@db.BigInt

SQLite

INTEGER

CockroachDB

原生数据库类型原生数据库类型属性注意
BIGINT | INT | INT8@db.Int8请注意,这与 PostgreSQL 不同,在 PostgreSQL 中 intint4 的别名
bigserial | serial8@db.Int8 @default(autoincrement())

客户端

客户端类型描述
Prisma Client JSBigInt参阅使用 BigInt 的示例

Float

浮点数。

Float2.17.0 及更高版本中映射到 Double - 有关此更改的更多信息,请参阅 发行说明视频:Prisma ORM 2.17.0 中 Float 默认映射的变化

默认类型映射

连接器默认映射
PostgreSQLdouble precision
SQL Serverfloat(53)
MySQLDOUBLE
MongoDBDouble
SQLiteREAL
CockroachDBDOUBLE PRECISION

PostgreSQL

原生数据库类型原生数据库类型属性注意
double precision@db.DoublePrecision
real@db.Real

MySQL

原生数据库类型原生数据库类型属性注意
FLOAT@db.Float
DOUBLE@db.Double

MongoDB

Double

Microsoft SQL Server

原生数据库类型原生数据库类型属性
float@db.Float
money@db.Money
smallmoney@db.SmallMoney
real@db.Real

SQLite 连接器

REAL

CockroachDB

原生数据库类型原生数据库类型属性注意
DOUBLE PRECISION | FLOAT8@db.Float8
REAL | FLOAT4 | FLOAT@db.Float4

客户端

Prisma Client JS
number

Decimal

默认类型映射

连接器默认映射
PostgreSQLdecimal(65,30)
SQL Serverdecimal(32,16)
MySQLDECIMAL(65,30)
MongoDB不支持
SQLiteDECIMAL
CockroachDBDECIMAL

PostgreSQL

原生数据库类型原生数据库类型属性注意
decimal | numeric@db.Decimal(p, s)
money@db.Money
  • p (精度),要存储的最大十进制数字总数。s (小数位数),小数点右侧存储的十进制数字位数。

MySQL

原生数据库类型原生数据库类型属性注意
DECIMAL | NUMERIC@db.Decimal(p, s)
  • p (精度),要存储的最大十进制数字总数。s (小数位数),小数点右侧存储的十进制数字位数。

MongoDB

不支持.

Microsoft SQL Server

原生数据库类型原生数据库类型属性注意
decimal | numeric@db.Decimal(p, s)
  • p (精度),要存储的最大十进制数字总数。s (小数位数),小数点右侧存储的十进制数字位数。

SQLite

DECIMAL (在 2.17.0 版本中从 REAL 更改)

CockroachDB

原生数据库类型原生数据库类型属性注意
DECIMAL | DEC | NUMERIC@db.Decimal(p, s)
money暂不支持CockroachDB 暂不支持 PostgreSQL 的 money 类型
  • p (精度),要存储的最大十进制数字总数。s (小数位数),小数点右侧存储的十进制数字位数。

客户端

客户端类型描述
Prisma Client JSDecimal查看 使用 Decimal 的示例

DateTime

备注

  • Prisma Client 将所有 DateTime 作为原生 Date 对象返回。
  • 目前,Prisma ORM 不支持 MySQL 中的 零日期0000-00-00 00:00:000000-00-0000:00:00)。
  • 当前存在一个 bug,不允许将 DateTime 值作为字符串传入,否则会产生运行时错误。DateTime 值需要作为 Date 对象传入(即 new Date('2024-12-04'),而不是 '2024-12-04')。

你可以在本节找到更多信息和示例: 使用 DateTime

默认类型映射

连接器默认映射
PostgreSQLtimestamp(3)
SQL Serverdatetime2
MySQLDATETIME(3)
MongoDBTimestamp
SQLiteNUMERIC
CockroachDBTIMESTAMP

PostgreSQL

原生数据库类型原生数据库类型属性注意
timestamp(x)@db.Timestamp(x)
timestamptz(x)@db.Timestamptz(x)
date@db.Date
time(x)@db.Time(x)
timetz(x)@db.Timetz(x)

MySQL

原生数据库类型原生数据库类型属性注意
DATETIME(x)@db.DateTime(x)
DATE(x)@db.Date(x)
TIME(x)@db.Time(x)
TIMESTAMP(x)@db.Timestamp(x)

你也可以将 MySQL 的 YEAR 类型与 Int 一起使用

yearField     Int    @db.Year

MongoDB

Timestamp

Microsoft SQL Server

原生数据库类型原生数据库类型属性注意
date@db.Date
time@db.Time
datetime@db.DateTime
datetime2@db.DateTime2
smalldatetime@db.SmallDateTime
datetimeoffset@db.DateTimeOffset

SQLite

NUMERICSTRING。如果底层数据类型是 STRING,你必须使用以下格式之一

  • RFC 3339 (1996-12-19T16:39:57-08:00)
  • RFC 2822 (Tue, 1 Jul 2003 10:52:37 +0200)

CockroachDB

原生数据库类型原生数据库类型属性注意
TIMESTAMP(x)@db.Timestamp(x)
TIMESTAMPTZ(x)@db.Timestamptz(x)
DATE@db.Date
TIME(x)@db.Time(x)
TIMETZ(x)@db.Timetz(x)

客户端

Prisma Client JS
Date

Json

一个 JSON 对象。

默认类型映射

连接器默认映射
PostgreSQLjsonb
SQL Server不支持
MySQLJSON
MongoDB一个有效的 BSON 对象(宽松模式)
SQLiteJSONB
CockroachDBJSONB

PostgreSQL

原生数据库类型原生数据库类型属性注意
json@db.Json
jsonb@db.JsonB

MySQL

原生数据库类型原生数据库类型属性注意
JSON@db.Json

MongoDB

一个有效的 BSON 对象(宽松模式)

Microsoft SQL Server

Microsoft SQL Server 没有特定的 JSON 数据类型。但是,有许多 用于读取和修改 JSON 的内置函数

SQLite

不支持

CockroachDB

原生数据库类型原生数据库类型属性注意
JSON | JSONB@db.JsonB

客户端

Prisma Client JS
object

Bytes

Bytes2.17.0 及更高版本中可用。

默认类型映射

连接器默认映射
PostgreSQLbytea
SQL Servervarbinary
MySQLLONGBLOB
MongoDBBinData
SQLiteBLOB
CockroachDBBYTES

PostgreSQL

原生数据库类型原生数据库类型属性
bytea@db.ByteA

MySQL

原生数据库类型原生数据库类型属性注意
LONGBLOB@db.LongBlob
BINARY@db.Binary
VARBINARY@db.VarBinary
TINYBLOB@db.TinyBlob
BLOB@db.Blob
MEDIUMBLOB@db.MediumBlob
BIT@db.Bit

MongoDB

BinData

原生数据库类型属性注意
@db.ObjectId如果底层 BSON 类型是 OBJECT_ID(ID 字段、关系标量),则必需
@db.BinData

Microsoft SQL Server

原生数据库类型原生数据库类型属性注意
binary@db.Binary
varbinary@db.VarBinary
image@db.Image

SQLite

BLOB

CockroachDB

原生数据库类型原生数据库类型属性
BYTES | BYTEA | BLOB@db.Bytes

客户端

客户端类型描述
Prisma Client JSUint8Array查看 使用 Bytes 的示例
Prisma Client JS(v6 之前)Buffer查看 使用 Bytes 的示例

Unsupported

警告

MongoDB 不支持
MongoDB 连接器 不支持 Unsupported 类型。

Unsupported 类型在 2.17.0 中引入,它允许你在 Prisma schema 中表示 Prisma Client 不支持的数据类型。Unsupported 类型的字段可以在使用 prisma db pull 进行内省时创建,或者手动编写,也可以使用 Prisma Migrate 或 db push 在数据库中创建。

备注

  • 具有 Unsupported 类型的字段在生成的客户端中不可用。

  • 如果 model 包含 必需的 Unsupported 类型字段,则 Prisma Client 不支持 prisma.model.create(..)prisma.model.update(...)prisma.model.upsert(...) 方法。

  • 当你内省包含不受支持类型的数据库时,Prisma ORM 将提供以下警告

    *** WARNING ***

    These fields are not supported by Prisma Client, because Prisma does not currently support their types.
    * Model "Post", field: "circle", original data type: "circle"

示例

model Star {
id Int @id @default(autoincrement())
position Unsupported("circle")?
example1 Unsupported("circle")
circle Unsupported("circle")? @default(dbgenerated("'<(10,4),11>'::circle"))
}

model 字段类型修饰符

[] 修饰符

使字段成为列表。

备注

  • 不能是可选的(例如 Post[]?)。
关系型数据库
  • 只有当你的数据库原生支持标量列表(数组)时,它们才在数据模型中受支持。因此,目前仅在使用 PostgreSQL 或 CockroachDB 时支持标量列表(因为 MySQL 和 SQLite 原生不支持标量列表)。
MongoDB
  • 支持标量列表

示例

定义一个标量列表
model User {
id Int @id @default(autoincrement())
favoriteColors String[]
}
定义具有默认值的标量列表

在 4.0.0 及更高版本中可用。

model User {
id Int @id @default(autoincrement())
favoriteColors String[] @default(["red", "blue", "green"])
}

? 修饰符

使字段成为可选的。

备注

  • 不能用于列表字段(例如,Posts[]

示例

可选的 name 字段
model User {
id Int @id @default(autoincrement())
name String?
}

属性

属性修改 字段 或块(例如 models)的行为。有两种方式将属性添加到你的数据模型中

  • 字段属性以 @ 为前缀
  • 块属性以 @@ 为前缀

一些属性接受参数。属性中的参数总是命名的,但在大多数情况下,可以省略参数名称

注意:签名中的前导下划线表示可以省略参数名称

@id

定义 model 上的单字段 ID。

备注

通用
  • 不能在关联字段上定义
  • 不能是可选的
关系型数据库
MongoDB
  • 对应的数据库构造:任何有效的 BSON 类型,数组除外

  • 每个 model 都必须定义一个 @id 字段

  • 底层 ID 字段名始终是 _id,并且必须使用 @map("_id") 进行映射

  • 可以在任何标量字段上定义(StringIntenum),除非你想在数据库中使用 ObjectId

  • 要使用 ObjectId 作为 ID,你必须

    • 使用 StringBytes 字段类型

    • 使用 @db.ObjectId 标注你的字段

      id   String  @db.ObjectId  @map("_id")
    • 可选地,使用 @default 属性标注你的字段,该属性使用 auto() 函数 自动生成 ObjectId

      id   String  @db.ObjectId  @map("_id") @default(auto())
  • 支持 cuid()uuid()ulid(),但它们不会生成有效的 ObjectId - 对于 @id,请改用 auto()

  • 不支持 autoincrement()

参数

名称必需类型描述
mapString数据库中底层主键约束的名称。

MySQL 或 MongoDB 不支持。
lengthnumber允许你指定要索引的值子部分的 最大长度。

仅 MySQL 支持。在 3.5.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。
sortString允许你指定 ID 条目在数据库中的存储顺序。可用选项包括 AscDesc

仅 SQL Server 支持。在 3.5.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。
clusteredBoolean定义 ID 是聚集索引还是非聚集索引。默认为 true

仅 SQL Server 支持。在 3.13.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。

签名

@id(map: String?, length: number?, sort: String?, clustered: Boolean?)

注意:在 4.0.0 版本之前,或在 3.5.0 版本中启用 extendedIndexes 预览功能时,签名如下

@id(map: String?)

注意:在 3.0.0 版本之前,签名如下

@id

示例

在大多数情况下,你希望数据库创建 ID。为此,请使用 @default 属性标注 ID 字段,并使用 函数 初始化该字段。

生成自增整数作为 ID(仅关系型数据库)
model User {
id Int @id @default(autoincrement())
name String
}
生成 ObjectId 作为 ID(仅 MongoDB)
model User {
id String @id @default(auto()) @map("_id") @db.ObjectId
name String
}
生成 cuid() 值作为 ID
model User {
id String @id @default(cuid())
name String
}
生成 uuid() 值作为 ID
model User {
id String @id @default(uuid())
name String
}
生成 ulid() 值作为 ID
model User {
id String @id @default(ulid())
name String
}
没有默认值的单字段 ID

在以下示例中,id 没有默认值

model User {
id String @id
name String
}

注意:在上述情况下,在使用 Prisma Client 创建 User model 的新记录时,你必须提供自己的 ID 值,例如

const newUser = await prisma.user.create({
data: {
id: 1,
name: "Alice",
},
});
在不带默认值的关联标量字段上指定 ID

在以下示例中,authorId 既是关联标量,也是 Profile 的 ID

model Profile {
authorId Int @id
author User @relation(fields: [authorId], references: [id])
bio String
}

model User {
id Int @id
email String @unique
name String?
profile Profile?
}

在这种情况下,你不能只创建 Profile - 你必须使用 Prisma Client 的 嵌套写入 创建 User 将 profile 连接到现有用户。

以下示例创建一个 user 和一个 profile

const userWithProfile = await prisma.user.create({
data: {
id: 3,
email: "bob@prisma.io",
name: "Bob Prismo",
profile: {
create: {
bio: "Hello, I'm Bob Prismo and I love apples, blue nail varnish, and the sound of buzzing mosquitoes.",
},
},
},
});

以下示例将新的 profile 连接到一个 user

const profileWithUser = await prisma.profile.create({
data: {
bio: "Hello, I'm Bob and I like nothing at all. Just nothing.",
author: {
connect: {
id: 22,
},
},
},
});

@@id

警告

MongoDB 不支持
MongoDB 连接器 不支持复合 ID。

定义 model 上的多字段 ID(复合 ID)。

备注

  • 对应的数据库类型:PRIMARY KEY
  • 可以使用 @default 属性进行标注,该属性使用 函数 自动生成 ID
  • 不能是可选的
  • 可以在任何标量字段上定义(StringIntenum
  • 不能在关联字段上定义
  • Prisma Client 中复合 ID 字段的名称遵循以下模式:field1_field2_field3

参数

名称必需类型描述
fieldsFieldReference[]字段名列表 - 例如,["firstname", "lastname"]
nameStringPrisma Client 为包含所有字段的参数公开的名称,例如 fullName: { firstName: "First", lastName: "Last"} 中的 fullName
mapString数据库中底层主键约束的名称。

MySQL 不支持。
lengthnumber允许你指定要索引的值子部分的 最大长度。

仅 MySQL 支持。在 3.5.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。
sortString允许你指定 ID 条目在数据库中的存储顺序。可用选项包括 AscDesc

仅 SQL Server 支持。在 3.5.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。
clusteredBoolean定义 ID 是聚集索引还是非聚集索引。默认为 true

仅 SQL Server 支持。在 3.13.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。

@@id 属性上 fields 参数的名称可以省略

@@id(fields: [title, author])
@@id([title, author])

签名

@@id(_ fields: FieldReference[], name: String?, map: String?)

注意:直到 3.0.0 版本,签名如下

@@id(_ fields: FieldReference[])

示例

在两个 String 字段上指定多字段 ID(仅关系型数据库)
model User {
firstName String
lastName String
email String @unique
isAdmin Boolean @default(false)

@@id([firstName, lastName])
}

当你创建一个 user 时,你必须提供 firstNamelastName 的唯一组合

const user = await prisma.user.create({
data: {
firstName: "Alice",
lastName: "Smith",
},
});

要检索 user,使用生成的复合 ID 字段(firstName_lastName

const user = await prisma.user.findUnique({
where: {
firstName_lastName: {
firstName: "Alice",
lastName: "Smith",
},
},
});
在两个 String 字段和一个 Boolean 字段上指定多字段 ID(仅关系型数据库)
model User {
firstName String
lastName String
email String @unique
isAdmin Boolean @default(false)

@@id([firstName, lastName, isAdmin])
}

创建新的 User 记录时,你现在必须提供 firstNamelastNameisAdmin 的唯一组合值

const user = await prisma.user.create({
data: {
firstName: "Alice",
lastName: "Smith",
isAdmin: true,
},
});
指定包含关联字段的多字段 ID(仅关系型数据库)
model Post {
title String
published Boolean @default(false)
author User @relation(fields: [authorId], references: [id])
authorId Int

@@id([authorId, title])
}

model User {
id Int @default(autoincrement())
email String @unique
name String?
posts Post[]
}

创建新的 Post 记录时,你现在必须提供 authorId(外键)和 title 的唯一组合值

const post = await prisma.post.create({
data: {
title: "Hello World",
author: {
connect: {
email: "alice@prisma.io",
},
},
},
});

@default

定义 字段 的默认值。

备注

  • 无法在 Prisma schema 中表示的默认值,在使用 内省 时,会通过 dbgenerated() 函数 表示。
  • 在 Prisma schema 中,关系字段不允许设置默认值。但请注意,您仍然可以在支持关系的字段上定义默认值(在 @relation 属性的 fields 参数中列出的字段)。在支持关系的字段上设置默认值意味着该关系将自动填充。
  • 在原生支持标量列表的数据库中,可以使用默认值。
关系型数据库
  • 对应的数据库构造:DEFAULT
  • 默认值可以是静态值(4, "hello"),也可以是以下函数之一
  • 使用内省时, Prisma schema 中尚不能表示的默认值通过 dbgenerated(...) 函数表示。
  • 在 Prisma schema 中,关系字段不允许设置默认值。但请注意,您仍然可以在支持关系的字段上定义默认值(在 @relation 属性的 fields 参数中列出的字段)。在支持关系的字段上设置默认值意味着该关系将自动填充。
  • 在原生支持标量列表的数据库中,可以使用默认值。
  • JSON 数据。请注意,JSON 在 @default 属性中需要用双引号括起来,例如:@default("[]")。如果您想提供一个 JSON 对象,您需要用双引号将其括起来,然后使用反斜杠转义任何内部的双引号,例如:@default("{ \"hello\": \"world\" }")
MongoDB
  • 默认值可以是静态值(4, "hello"),也可以是以下函数之一

参数

名称必需类型描述
value一个表达式(例如 5, true, now()
mapString仅 SQL Server。

@default 属性上 value 参数的名称可以省略

id Int @id @default(value: autoincrement())
id Int @id @default(autoincrement())

签名

@default(_ value: Expression, map: String?)

注意:直到 3.0.0 版本,签名如下

@default(_ value: Expression)

示例

Int 的默认值
model User {
email String @unique
profileViews Int @default(0)
}
Float 的默认值
model User {
email String @unique
number Float @default(1.1)
}
Decimal 的默认值
model User {
email String @unique
number Decimal @default(22.99)
}
BigInt 的默认值
model User {
email String @unique
number BigInt @default(34534535435353)
}
String 的默认值
model User {
email String @unique
name String @default("")
}
Boolean 的默认值
model User {
email String @unique
isAdmin Boolean @default(false)
}
DateTime 的默认值

请注意,DateTime 的静态默认值基于 ISO 8601 标准。

model User {
email String @unique
data DateTime @default("2020-03-19T14:21:00+02:00")
}
Bytes 的默认值
model User {
email String @unique
secret Bytes @default("SGVsbG8gd29ybGQ=")
}
enum 的默认值
enum Role {
USER
ADMIN
}
model User {
id Int @id @default(autoincrement())
email String @unique
name String?
role Role @default(USER)
posts Post[]
profile Profile?
}
标量列表的默认值
model User {
id Int @id @default(autoincrement())
posts Post[]
favoriteColors String[] @default(["red", "yellow", "purple"])
roles Role[] @default([USER, DEVELOPER])
}

enum Role {
USER
DEVELOPER
ADMIN
}

@unique

为此字段定义一个唯一约束。

备注

通用
  • 标注了 @unique 的字段可以是可选的或必需的
  • 如果一个模型没有 @id / @@id,并且 @unique 字段是该模型上唯一的唯一约束,则该字段必须是必需的
  • 一个模型可以有任意数量的唯一约束
  • 可以在任何标量字段上定义
  • 不能在关系字段上定义
关系型数据库
  • 对应的数据库构造:UNIQUE
  • NULL 值被认为是不同的(同一列中允许有多行具有 NULL 值)
  • 添加唯一约束会自动为指定的列添加相应的唯一索引
MongoDB

参数

名称必需类型描述
mapString
lengthnumber允许你指定要索引的值子部分的 最大长度。

仅 MySQL 支持。在 3.5.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。
sortString允许您指定约束条目在数据库中的存储顺序。可用选项为 AscDesc

在版本 3.5.0 及更高版本中处于预览状态,并在版本 4.0.0 及更高版本中普遍可用。
clusteredBoolean定义约束是聚集的还是非聚集的。默认为 false

仅 SQL Server 支持。在 3.13.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。
  • ¹ 某些索引和字段类型可能要求。

签名

@unique(map: String?, length: number?, sort: String?)

注意:在 4.0.0 版本之前,或在 3.5.0 版本中启用 extendedIndexes 预览功能时,签名如下

@unique(map: String?)

注意:在 3.0.0 版本之前,签名如下

@unique

示例

在必填的 String 字段上指定唯一属性
model User {
email String @unique
name String
}
在可选的 String 字段上指定唯一属性
model User {
id Int @id @default(autoincrement())
email String? @unique
name String
}
在关系标量字段 authorId 上指定唯一属性
model Post {
author User @relation(fields: [authorId], references: [id])
authorId Int @unique
title String
published Boolean @default(false)
}

model User {
id Int @id @default(autoincrement())
email String? @unique
name String
Post Post[]
}
指定具有 cuid() 值作为默认值的唯一属性
model User {
token String @unique @default(cuid())
name String
}

@@unique

为指定的字段定义一个复合唯一约束

备注

通用
  • 构成唯一约束的所有字段必须是强制性字段。以下模型无效,因为 id 可能为 null

    model User {
    firstname Int
    lastname Int
    id Int?

    @@unique([firstname, lastname, id])
    }

    此行为的原因是所有连接器都将 null 值视为不同的,这意味着两行看起来相同但包含 null 值的行被认为是唯一的

     firstname  | lastname | id
    -----------+----------+------
    John | Smith | null
    John | Smith | null
  • 一个模型可以有任意数量的 @@unique

关系型数据库
  • 对应的数据库构造:UNIQUE
  • 如果一个模型没有 @id / @@id,并且 @@unique 块是该模型上唯一的唯一约束,则该块是必需的
  • 添加唯一约束会自动为指定的列添加相应的唯一索引
MongoDB

参数

名称必需类型描述
fieldsFieldReference[]字段名称列表 - 例如,["firstname", "lastname"]。字段必须是强制性的 - 请参见备注。
nameString字段唯一组合的名称 - 默认为 fieldName1_fieldName2_fieldName3
mapString
lengthnumber允许你指定要索引的值子部分的 最大长度。

仅 MySQL 支持。在 3.5.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。
sortString允许您指定约束条目在数据库中的存储顺序。可用选项为 AscDesc

在版本 3.5.0 及更高版本中处于预览状态,并在版本 4.0.0 及更高版本中普遍可用。
clusteredBoolean定义约束是聚集的还是非聚集的。默认为 false

仅 SQL Server 支持。在 3.13.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。

@@unique 属性上 fields 参数的名称可以省略

@@unique(fields: [title, author])
@@unique([title, author])
@@unique(fields: [title, author], name: "titleAuthor")

lengthsort 参数添加到相关的字段名称中

@@unique(fields: [title(length:10), author])
@@unique([title(sort: Desc), author(sort: Asc)])

签名

@@unique(_ fields: FieldReference[], name: String?, map: String?)

注意:在版本 4.0.0 之前,或在版本 3.5.0 之前且启用了 extendedIndexes 预览特性时,签名为

@@unique(_ fields: FieldReference[], name: String?, map: String?)

注意:在 3.0.0 版本之前,签名如下

@@unique(_ fields: FieldReference[], name: String?)

示例

在两个 String 字段上指定多字段唯一属性
model User {
id Int @default(autoincrement())
firstName String
lastName String
isAdmin Boolean @default(false)

@@unique([firstName, lastName])
}

要检索用户,请使用生成的字段名(firstname_lastname

const user = await prisma.user.findUnique({
where: {
firstName_lastName: {
firstName: "Alice",
lastName: "Smith",
isAdmin: true,
},
},
});
在两个 String 字段和一个 Boolean 字段上指定多字段唯一属性
model User {
id Int @default(autoincrement())
firstName String
lastName String
isAdmin Boolean @default(false)

@@unique([firstName, lastName, isAdmin])
}
指定包含关系字段的多字段唯一属性
model Post {
id Int @default(autoincrement())
author User @relation(fields: [authorId], references: [id])
authorId Int
title String
published Boolean @default(false)

@@unique([authorId, title])
}

model User {
id Int @id @default(autoincrement())
email String @unique
posts Post[]
}
为多字段唯一属性指定自定义 name
model User {
id Int @default(autoincrement())
firstName String
lastName String
isAdmin Boolean @default(false)

@@unique(fields: [firstName, lastName, isAdmin], name: "admin_identifier")
}

要检索用户,请使用自定义字段名(admin_identifier

const user = await prisma.user.findUnique({
where: {
admin_identifier: {
firstName: "Alice",
lastName: "Smith",
isAdmin: true,
},
},
});

@@index

在数据库中定义一个索引。

备注

关系型数据库
  • 对应的数据库构造:INDEX
  • 还有一些其他索引配置选项尚不能通过 Prisma schema 提供。这些选项包括
    • PostgreSQL 和 CockroachDB
      • 将索引字段定义为表达式(例如 CREATE INDEX title ON public."Post"((lower(title)) text_ops);
      • 使用 WHERE 定义部分索引
      • 使用 CONCURRENTLY 并发创建索引
信息

虽然您无法在 Prisma schema 中配置这些选项,但您仍然可以直接在数据库层面配置它们。

MongoDB
  • 在版本 3.12.0 及更高版本中,您可以使用语法 @@index([compositeType.field])复合类型的字段上定义索引。有关更多详细信息,请参阅定义复合类型索引

参数

名称必需类型描述
fieldsFieldReference[]字段名列表 - 例如,["firstname", "lastname"]
nameStringPrisma Client 为包含所有字段的参数公开的名称,例如 fullName: { firstName: "First", lastName: "Last"} 中的 fullName
mapmap底层数据库中索引的名称(如果您未指定名称,Prisma 会生成一个遵守标识符长度限制的索引名称。Prisma 使用以下命名约定:tablename.field1_field2_field3_unique
lengthnumber允许你指定要索引的值子部分的 最大长度。

仅 MySQL 支持。在 3.5.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。
sortString允许您指定索引或约束条目在数据库中的存储顺序。可用选项为 ascdesc

在版本 3.5.0 及更高版本中处于预览状态,并在版本 4.0.0 及更高版本中普遍可用。
clusteredBoolean定义索引是聚集的还是非聚集的。默认为 false

仅 SQL Server 支持。在 3.5.0 及更高版本中是预览功能,在 4.0.0 及更高版本中是正式可用功能。
typeidentifier允许您指定索引访问方法。默认为 BTree

仅 PostgreSQL 和 CockroachDB。在版本 3.6.0 及更高版本中,使用 Hash 索引访问方法处于预览状态,并在 3.14.0 中添加了 Gist, Gin, SpGistBrin 方法。在版本 4.0.0 及更高版本中普遍可用。
opsidentifierfunction允许您定义某些索引类型的索引操作符。

仅 PostgreSQL。在版本 3.14.0 及更高版本中处于预览状态,并在版本 4.0.0 及更高版本中普遍可用。

@@index 属性上 fields 参数的名称可以省略

@@index(fields: [title, author])
@@index([title, author])

lengthsort 参数添加到相关的字段名称中

@@index(fields: [title(length:10), author])
@@index([title(sort: Asc), author(sort: Desc)])

签名

@@index(_ fields: FieldReference[], map: String?)

注意:直到 3.0.0 版本,签名如下

@@index(_ fields: FieldReference[], name: String?)

为了避免破坏性更改,旧的 name 参数仍然会被接受。

示例

假设您想为 Post 模型的 title 字段添加一个索引

定义单列索引(仅关系型数据库)
model Post {
id Int @id @default(autoincrement())
title String
content String?

@@index([title])
}
定义多列索引(仅关系型数据库)
model Post {
id Int @id @default(autoincrement())
title String
content String?

@@index([title, content])
}
定义带有名称的索引(仅关系型数据库)
model Post {
id Int @id @default(autoincrement())
title String
content String?

@@index(fields: [title, content], name: "main_index")
}
在复合类型字段上定义索引(仅关系型数据库)
type Address {
street String
number Int
}

model User {
id Int @id
email String
address Address

@@index([address.number])
}

@relation

定义关系的元信息。了解更多

备注

关系型数据库
  • 对应的数据库构造:FOREIGN KEY / REFERENCES
MongoDB
  • 如果您的模型的底层数据库主键类型是 ObjectId,则主键和外键都必须具有 @db.ObjectId 属性

参数

名称类型必需描述示例
nameString有时(例如为了消除关系的歧义)定义关系的名称。在一个 m-n 关系中,它还决定了底层关系表的名称。"CategoryOnPost", "MyRelation"
fieldsFieldReference[]标注的关系字段上当前模型的字段列表["authorId"], ["authorFirstName, authorLastName"]
referencesFieldReference[]标注的关系字段上关系另一侧模型的字段列表["id"], ["firstName, lastName"]
mapString定义数据库中外键的自定义名称["id"], ["firstName, lastName"]
onUpdate枚举。值请参见参照操作的类型定义当引用模型中引用的条目被更新时要执行的参照操作Cascade, NoAction
onDelete枚举。值请参见参照操作的类型定义当引用模型中引用的条目被删除时要执行的参照操作Cascade, NoAction

@relation 属性上 name 参数的名称可以省略(references 是必需的)

@relation(name: "UserOnPost", references: [id])
@relation("UserOnPost", references: [id])

// or

@relation(name: "UserOnPost")
@relation("UserOnPost")

签名

@relation(_ name: String?, fields: FieldReference[]?, references: FieldReference[]?, onDelete: ReferentialAction?, onUpdate: ReferentialAction?, map: String?)

对于 SQLite,签名变为

@relation(_ name: String?, fields: FieldReference[]?, references: FieldReference[]?, onDelete: ReferentialAction?, onUpdate: ReferentialAction?)

注意:直到 3.0.0 版本,签名如下

@relation(_ name: String?, fields: FieldReference[]?, references: FieldReference[]?)

示例

参见:@relation 属性

@map

将 Prisma schema 中的字段名或枚举值映射到数据库中具有不同名称的列或文档字段。如果您不使用 @map,Prisma 字段名将与列名或文档字段名完全匹配。

请参阅使用自定义模型和字段名,了解 @map@@map 如何更改生成的 Prisma Client。

备注

通用
MongoDB

您的 @id 字段必须包含 @map("_id")。例如

model User {
id String @default(auto()) @map("_id") @db.ObjectId
}

参数

名称类型必需描述示例
nameString数据库列(关系型数据库)或文档字段(MongoDB)的名称。"comments", "someFieldName"

@map 属性上 name 参数的名称可以省略

@map(name: "is_admin")
@map("users")

签名

@map(_ name: String)

示例

firstName 字段映射到名为 first_name 的列
model User {
id Int @id @default(autoincrement())
firstName String @map("first_name")
}

生成的客户端

await prisma.user.create({
data: {
firstName: "Yewande", // first_name --> firstName
},
});
将名为 ADMIN 的枚举映射到名为 admin 的数据库枚举
enum Role {
ADMIN @map("admin")
CUSTOMER
}

@@map

将 Prisma schema 模型名称映射到数据库中具有不同名称的表(关系型数据库)或集合(MongoDB),或将枚举名称映射到数据库中不同的底层枚举。如果您不使用 @@map,模型名称将与表(关系型数据库)或集合(MongoDB)名称完全匹配。

请参阅使用自定义模型和字段名,了解 @map@@map 如何更改生成的 Prisma Client。

参数

名称类型必需描述示例
nameString数据库表(关系型数据库)或集合(MongoDB)的名称。"comments", "someTableOrCollectionName"

@@map 属性上 name 参数的名称可以省略

@@map(name: "users")
@@map("users")

签名

@@map(_ name: String)

示例

User 模型映射到名为 users 的数据库表/集合
model User {
id Int @id @default(autoincrement())
name String

@@map("users")
}

生成的客户端

await prisma.user.create({
// users --> user
data: {
name: "Yewande",
},
});
Role 枚举映射到数据库中名为 _Role 的原生枚举,并将其值映射到数据库中的小写值
enum Role {
ADMIN @map("admin")
CUSTOMER @map("customer")

@@map("_Role")
}

@updatedAt

自动存储记录最后更新的时间。如果您自己不提供时间,Prisma Client 将自动为此属性的字段设置值。

备注

  • DateTime 字段兼容
  • 在 Prisma ORM 层面实现
警告

如果您还使用 now(),如果您的数据库和应用程序具有不同的时区,时间可能与 @updatedAt 值不同。这是因为 @updatedAt 在 Prisma ORM 层面操作,而 now() 在数据库层面操作。

注意

如果您传递一个空的更新子句,@updatedAt 值将保持不变。例如

await prisma.user.update({
where: {
id: 1,
},
data: {}, //<- Empty update clause
});

参数

签名

@updatedAt

示例

model Post {
id String @id
updatedAt DateTime @updatedAt
}

@ignore

@ignore 添加到您想从 Prisma Client 中排除的字段(例如,您不想让 Prisma Client 用户更新的字段)。被忽略的字段将从生成的 Prisma Client 中排除。当对没有 @default必填字段执行此操作时,模型的 create 方法将被禁用(因为数据库在没有该数据的情况下无法创建条目)。

备注

  • 2.17.0 及更高版本中,当您执行内省时,Prisma ORM 会自动将 @ignore 添加到引用无效模型的字段。

示例

以下示例演示手动添加 @ignore 以将 email 字段从 Prisma Client 中排除

schema.prisma
model User {
id Int @id
name String
email String @ignore // this field will be excluded
}

@@ignore

@@ignore 添加到您想从 Prisma Client 中排除的模型(例如,您不想让 Prisma 用户更新的模型)。被忽略的模型将从生成的 Prisma Client 中排除。

备注

  • 2.17.0 及更高版本中,Prisma ORM 会将 @@ignore 添加到一个无效模型。(它还会将 @ignore 添加到指向此类模型的关系)

示例

在以下示例中,Post 模型无效,因为它没有唯一标识符。使用 @@ignore 将其从生成的 Prisma Client API 中排除

schema.prisma
/// The underlying table does not contain a valid unique identifier and can therefore currently not be handled by Prisma Client.
model Post {
id Int @default(autoincrement()) // no unique identifier
author User @relation(fields: [authorId], references: [id])
authorId Int

@@ignore
}

在以下示例中,Post 模型无效,因为它没有唯一标识符;User 上的 posts 关系字段无效,因为它引用了无效的 Post 模型。在 Post 模型上使用 @@ignore,并在 Userposts 关系字段上使用 @ignore,以将模型和关系字段都从生成的 Prisma Client API 中排除

schema.prisma
/// The underlying table does not contain a valid unique identifier and can therefore currently not be handled by Prisma Client.
model Post {
id Int @default(autoincrement()) // no unique identifier
author User @relation(fields: [authorId], references: [id])
authorId Int

@@ignore
}

model User {
id Int @id @default(autoincrement())
name String?
posts Post[] @ignore
}

@@schema

警告

要使用此属性,您必须启用 multiSchema 预览特性。目前,多数据库 schema 支持适用于 PostgreSQL、CockroachDB 和 SQL Server 连接器。

@@schema 添加到模型,以指定数据库中的哪个 schema 应该包含与该模型关联的表。

参数

名称类型必需描述示例
nameString数据库 schema 的名称。"base", "auth"

@@schema 属性上 name 参数的名称可以省略

@@schema(name: "auth")
@@schema("auth")

签名

@@schema(_ name: String)

示例

User 模型映射到名为 auth 的数据库 schema
generator client {
provider = "prisma-client-js"
previewFeatures = ["multiSchema"]
}

datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
schemas = ["auth"]
}

model User {
id Int @id @default(autoincrement())
name String

@@schema("auth")
}
信息

有关使用 multiSchema 特性的更多信息,请参阅本指南

属性函数

auto()

警告
此函数仅在 MongoDB 上可用。

表示由数据库自动生成的默认值

备注

MongoDB

用于为 @id 字段生成 ObjectId

id  String  @map("_id") @db.ObjectId @default(auto())
关系型数据库

auto() 函数在关系型数据库上不可用。

示例

生成 ObjectId (仅 MongoDB)
model User {
id String @id @default(auto()) @map("_id") @db.ObjectId
name String?
}

autoincrement()

警告

MongoDB 不支持
MongoDB 连接器不支持 autoincrement() 函数。

在底层数据库中创建一个整数序列,并根据该序列将递增的值分配给创建记录的 ID 值。

备注

  • 在大多数数据库中兼容 Int 类型(在 CockroachDB 中为 BigInt

  • 在数据库级别实现,这意味着它体现在数据库模式中,可以通过内省(introspection)识别。数据库实现

    数据库实现
    PostgreSQLSERIAL 类型
    MySQLAUTO_INCREMENT 属性
    SQLiteAUTOINCREMENT 关键字
    CockroachDBSERIAL 类型

示例

生成自增整数作为 ID(仅限关系型数据库)
model User {
id Int @id @default(autoincrement())
name String
}

sequence()

信息

仅由 CockroachDB 支持
sequence 函数仅由 CockroachDB 连接器支持。

在底层数据库中创建整数序列,并根据该序列将递增的值分配给创建记录的值。

可选参数

参数示例
virtual@default(sequence(virtual))
Virtual sequence 是一种不生成单调递增值,而是生成类似于内置函数 unique_rowid() 所生成值序列。
cache@default(sequence(cache: 20))
在会话中缓存到内存中以供重用的序列值数量。缓存大小为 1 表示没有缓存,小于 1 的缓存大小无效。
increment@default(sequence(increment: 4))
序列递增的新值。负数创建递减序列,正数创建递增序列。
minValue@default(sequence(minValue: 10))
序列的新最小值。
maxValue@default(sequence(maxValue: 3030303))
序列的新最大值。
start@default(sequence(start: 2))
序列开始的值,如果在重启时或序列达到 maxValue 时。

示例

生成序列整数作为 ID
model User {
id Int @id @default(sequence(maxValue: 4294967295))
name String
}

cuid()

根据 cuid 规范生成一个全局唯一标识符。

如果您想使用 cuid2 值,可以将 2 作为参数传递给 cuid 函数:cuid(2)

备注

  • 兼容 String 类型。
  • 由 Prisma ORM 实现,因此在底层数据库模式中不可见。在使用内省(introspection)时,您仍然可以通过手动更改您的 Prisma 模式和生成 Prisma Client 来使用 cuid(),在这种情况下,值将由 Prisma 的查询引擎生成。
  • 由于 cuid() 输出的长度根据 cuid 创建者定义为不确定,因此安全的字段大小为 30 个字符,以便为非常大的值留出足够的字符。如果您将字段大小设置为小于 30,然后由 cuid() 生成了一个更大的值,您可能会看到 Prisma Client 错误,例如 Error: The provided value for the column is too long for the column's type.
  • 对于 MongoDBcuid() 不生成有效的 ObjectId。如果您想在底层数据库中使用 ObjectId,可以使用 @db.ObjectId 语法。但是,如果您的 _id 字段不是 ObjectId 类型,您仍然可以使用 cuid()

示例

生成 cuid() 值作为 ID
model User {
id String @id @default(cuid())
name String
}
根据 cuid2 规范生成 cuid(2) 值作为 ID
model User {
id String @id @default(cuid(2))
name String
}

uuid()

根据 UUID 规范生成一个全局唯一标识符。Prisma ORM 支持版本 4(默认)和 7。

备注

  • 兼容 String 类型。
  • 由 Prisma ORM 实现,因此在底层数据库模式中不可见。在使用内省(introspection)时,您仍然可以通过手动更改您的 Prisma 模式和生成 Prisma Client 来使用 uuid(),在这种情况下,值将由 Prisma ORM 的查询引擎生成。
  • 对于关系型数据库:如果您不想使用 Prisma ORM 的 uuid() 函数,可以使用 带有 dbgenerated 的原生数据库函数
  • 对于 MongoDBuuid() 不生成有效的 ObjectId。如果您想在底层数据库中使用 ObjectId,可以使用 @db.ObjectId 语法。但是,如果您的 _id 字段不是 ObjectId 类型,您仍然可以使用 uuid()

示例

使用 UUID v4 生成 uuid() 值作为 ID
model User {
id String @id @default(uuid())
name String
}
使用 UUID v7 生成 uuid(7) 值作为 ID
model User {
id String @id @default(uuid(7))
name String
}

ulid()

根据 ULID 规范生成一个全局唯一的、按字典顺序可排序的标识符。

备注

  • ulid() 将生成一个 128 位随机标识符,表示为一个 26 个字符长的字母数字字符串,例如:01ARZ3NDEKTSV4RRFFQ69G5FAV

示例

生成 ulid() 值作为 ID
model User {
id String @id @default(ulid())
name String
}

nanoid()

根据 Nano ID 规范生成值。nanoid() 接受一个介于 2 到 255 之间的整数值,指定生成的 ID 值的长度,例如 nanoid(16) 将生成 16 个字符的 ID。如果您不为 nanoid() 函数提供值,默认值为 21。

信息

Nano ID 与 UUID v4(基于随机)非常相似。它们在 ID 中具有相似数量的随机位(Nano ID 为 126 位,UUID 为 122 位),因此碰撞概率相似。

要达到十亿分之一的重复几率,必须生成 103 万亿个版本 4 的 ID。

Nano ID 和 UUID v4 之间有两个主要区别

  • Nano ID 使用更大的字符集,因此相似数量的随机位只需 21 个符号即可表示,而不是 36 个。
  • Nano ID 代码比 uuid/v4 包小 4 倍:130 字节而不是 423 字节。

备注

  • 兼容 String 类型。
  • 由 Prisma ORM 实现,因此在底层数据库模式中不可见。在使用内省(introspection)时,您仍然可以通过手动更改您的 Prisma 模式和生成 Prisma Client 来使用 uuid(),在这种情况下,值将由 Prisma ORM 的查询引擎生成。
  • 对于 MongoDBnanoid() 不生成有效的 ObjectId。如果您想在底层数据库中使用 ObjectId,可以使用 @db.ObjectId 语法。但是,如果您的 _id 字段不是 ObjectId 类型,您仍然可以使用 nanoid()

示例

生成包含 21 个字符的 nanoid() 值作为 ID
model User {
id String @id @default(nanoid())
name String
}
生成包含 16 个字符的 nanoid() 值作为 ID
model User {
id String @id @default(nanoid(16))
name String
}

now()

设置记录创建时的时间戳。

备注

通用
警告

如果您同时使用 @updatedAt,如果您的数据库和应用程序时区不同,时间可能与 now() 的值有所不同。这是因为 @updatedAt 在 Prisma ORM 级别运行,而 now() 在数据库级别运行。

关系型数据库
  • 在数据库级别实现,这意味着它体现在数据库模式中,可以通过内省(introspection)识别。数据库实现

    数据库实现
    PostgreSQLCURRENT_TIMESTAMP 以及 now() 等别名
    MySQLCURRENT_TIMESTAMP 以及 now() 等别名
    SQLiteCURRENT_TIMESTAMP 以及 date('now') 等别名
    CockroachDBCURRENT_TIMESTAMP 以及 now() 等别名
MongoDB
  • 在 Prisma ORM 层面实现

示例

设置记录创建时的当前时间戳值
model User {
id String @id
createdAt DateTime @default(now())
}

dbgenerated(...)

表示 Prisma 模式中无法表达的默认值(例如 random())。

备注

关系型数据库
  • 兼容任何标量类型

  • 2.21.0 及更高版本中,不能是空字符串 dbgenerated("")

  • 2.17.0 及更高版本中接受 String 值,这允许您

  • dbgenerated(...) 中的字符串值可能与数据库返回的默认值不匹配,因为字符串等值可能被显式转换(例如 'hello'::STRING)。当存在不匹配时,Prisma Migrate 会提示仍然需要进行迁移。您可以使用 prisma db pull 来推断正确的值以解决差异。(相关问题

示例

Unsupported 类型设置默认值
circle     Unsupported("circle")?   @default(dbgenerated("'<(10,4),11>'::circle"))
覆盖支持类型的默认值行为

您还可以使用 dbgenerated(...) 为支持的类型设置默认值。例如,在 PostgreSQL 中,您可以在数据库级别生成 UUID,而不是依赖 Prisma ORM 的 uuid()

model User {
id String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
id String @id @default(uuid()) @db.Uuid
test String?
}
信息

注意gen_random_uuid() 是一个 PostgreSQL 函数。要在 PostgreSQL 12.13 及更早版本中使用它,您必须启用 pgcrypto 扩展。

在 Prisma ORM 4.5.0 及更高版本中,您可以在 Prisma 模式中使用 postgresqlExtensions 预览功能 声明 pgcrypto 扩展。

属性参数类型

FieldReference[]

一个 字段 名称数组:[id][firstName, lastName]

String

双引号中的变长文本:"""Hello World""Alice"

Expression

Prisma ORM 可评估的表达式:42.0""Bobnow()cuid()

enum

警告

Microsoft SQL Server 不支持
Microsoft SQL Server 连接器不支持 enum 类型。

定义一个 枚举类型(enum)

备注

  • 枚举类型(Enums)原生支持 PostgreSQLMySQL
  • 枚举类型(Enums)在 SQLite 和 MongoDB 中由 Prisma ORM 级别实现并强制执行

命名约定

  • 枚举名称必须以字母开头(通常使用 PascalCase 拼写)
  • 枚举必须使用单数形式(例如 Role,而不是 rolerolesRoles)。
  • 必须符合以下正则表达式: [A-Za-z][A-Za-z0-9_]*

示例

指定一个包含两个可能值的 enum

enum Role {
USER
ADMIN
}

model User {
id Int @id @default(autoincrement())
role Role
}

指定一个包含两个可能值并设置默认值的 enum

enum Role {
USER
ADMIN
}

model User {
id Int @id @default(autoincrement())
role Role @default(USER)
}

type

警告

复合类型(Composite types)仅适用于 MongoDB

信息

复合类型(Composite types)在 3.12.0 及更高版本中可用,如果您启用 mongodb 预览功能标志,则在 3.10.0 及更高版本中也可用。

定义一个 复合类型(composite type)

命名约定

类型名称必须

  • 以字母开头(通常使用 PascalCase 拼写)
  • 遵循以下正则表达式:[A-Za-z][A-Za-z0-9_]*

示例

定义一个包含 Photo 复合类型列表的 Product 模型

model Product {
id String @id @default(auto()) @map("_id") @db.ObjectId
name String
photos Photo[]
}

type Photo {
height Int
width Int
url String
}