数据库映射
Prisma schema 包含允许您定义特定数据库对象名称的机制。您可以
映射集合/表名和字段/列名
有时,用于描述数据库中实体的名称可能与您在生成的 API 中偏好的名称不匹配。在 Prisma schema 中映射名称使您无需更改底层数据库名称即可影响 Client API 中的命名。
例如,在数据库中命名表/集合的常见方法是使用复数形式和 snake_case(蛇形命名法)。但是,我们推荐不同的命名约定(单数形式,PascalCase 帕斯卡命名法)。
@map
和 @@map
允许您通过将模型和字段名与底层数据库中的表名和列名解耦,从而调整您的 Prisma Client API 的形态。
映射集合/表名
例如,当您内省一个名为 comments
的数据库表时,生成的 Prisma 模型将如下所示
model comments {
// Fields
}
但是,您仍然可以通过使用@@map
属性,将 Comment
作为模型名称(例如,为了遵循命名约定),而无需重命名数据库中底层的 comments
表。
model Comment {
// Fields
@@map("comments")
}
有了这个修改后的模型定义,Prisma Client 会自动将 Comment
模型映射到底层数据库中的 comments
表。
映射字段/列名
您也可以@map
一个列/字段名
model Comment {
content String @map("comment_text")
email String @map("commenter_email")
type Enum @map("comment_type")
@@map("comments")
}
这样,comment_text
列在 Prisma Client API 中将不再通过 prisma.comment.comment_text
访问,而是可以通过 prisma.comment.content
访问。
映射枚举名和值
您也可以 @map
一个枚举值,或者 @@map
一个枚举
enum Type {
Blog,
Twitter @map("comment_twitter")
@@map("comment_source_enum")
}
约束和索引名
您可以选择使用 map
参数在 Prisma schema 中明确定义属性 @id
、@@id
、@unique
、@@unique
、@@index
和 @relation
的底层约束和索引名称。(此功能在 Prisma ORM 2.29.0 及更高版本 中可用。)
内省数据库时,map
参数仅当名称与 Prisma ORM 的索引和约束默认命名约定不同时才会在 schema 中呈现。
如果您在 2.29.0 之前的版本中使用 Prisma Migrate,并且希望在升级到新版本后保留现有的约束和索引名称,请不要立即运行 prisma migrate
或 prisma db push
。这样做会更改任何不遵循 Prisma ORM 约定的底层约束名称。请遵循允许您保留现有约束和索引名称的升级路径。
命名约束的用例
显式命名约束的一些用例包括
- 公司策略
- 其他工具的约定
Prisma ORM 索引和约束的默认命名约定
Prisma ORM 的命名约定选择与 PostgreSQL 对齐,因为它具有确定性。它还有助于最大程度地减少名称无需渲染的次数,因为许多现有数据库已经与此约定对齐。
Prisma ORM 在生成默认索引和约束名称时始终使用实体的数据库名称。如果模型通过 @@map
或 @map
在数据模型中被重新映射到不同的名称,默认名称生成仍将以数据库中的表名作为输入。字段和列名也是如此。
实体 | 约定 | 示例 |
---|---|---|
主键 | {tablename}_pkey | User_pkey |
唯一约束 | {tablename}_{column_names}_key | User_firstName_last_Name_key |
非唯一索引 | {tablename}_{column_names}_idx | User_age_idx |
外键 | {tablename}_{column_names}_fkey | User_childName_fkey |
由于大多数数据库对实体名称有长度限制,如果需要,名称将被截断以避免违反数据库限制。我们将根据需要缩短 _suffix
之前的部分,以便完整名称最长不超过允许的最大长度。
使用默认约束名称
当未通过 map
参数提供显式名称时,Prisma ORM 将根据默认命名约定生成索引和约束名称。
如果您内省一个数据库,索引和约束的名称将被添加到您的 schema 中,除非它们遵循 Prisma ORM 的命名约定。如果遵循,则不渲染这些名称以保持 schema 更具可读性。当您迁移这样的 schema 时,Prisma 将推断出默认名称并将其持久化到数据库中。
示例
以下 schema 定义了三个约束(@id
、@unique
和 @relation
)和一个索引(@@index
)
model User {
id Int @id @default(autoincrement())
name String @unique
posts Post[]
}
model Post {
id Int @id @default(autoincrement())
title String
authorName String @default("Anonymous")
author User? @relation(fields: [authorName], references: [name])
@@index([title, authorName])
}
由于没有通过 map
参数提供显式名称,Prisma 将假定它们遵循我们的默认命名约定。
下表列出了底层数据库中每个约束和索引的名称
约束或索引 | 遵循约定 | 底层约束或索引名称 |
---|---|---|
@id (在 User > id 字段上) | 是 | User_pk |
@@index (在 Post 上) | 是 | Post_title_authorName_idx |
@id (在 Post > id 字段上) | 是 | Post_pk |
@relation (在 Post > author 上) | 是 | Post_authorName_fkey |
使用自定义约束/索引名称
您可以使用 map
参数在底层数据库中定义自定义约束和索引名称。
示例
以下示例为其中一个 @id
和 @@index
添加了自定义名称
model User {
id Int @id(map: "Custom_Primary_Key_Constraint_Name") @default(autoincrement())
name String @unique
posts Post[]
}
model Post {
id Int @id @default(autoincrement())
title String
authorName String @default("Anonymous")
author User? @relation(fields: [authorName], references: [name])
@@index([title, authorName], map: "My_Custom_Index_Name")
}
下表列出了底层数据库中每个约束和索引的名称
约束或索引 | 遵循约定 | 底层约束或索引名称 |
---|---|---|
@id (在 User > id 字段上) | 否 | Custom_Primary_Key_Constraint_Name |
@@index (在 Post 上) | 否 | My_Custom_Index_Name |
@id (在 Post > id 字段上) | 是 | Post_pk |
@relation (在 Post > author 上) | 是 | Post_authorName_fkey |
相关:为 Prisma Client 命名索引和主键
除了 map
之外,@@id
和 @@unique
属性还接受一个可选的 name
参数,允许您自定义 Prisma Client API。
在像这样的模型上
model User {
firstName String
lastName String
@@id([firstName, lastName])
}
选择该主键的默认 API 使用字段的生成组合
const user = await prisma.user.findUnique({
where: {
firstName_lastName: {
firstName: 'Paul',
lastName: 'Panther',
},
},
})
指定 @@id([firstName, lastName], name: "fullName")
将使 Prisma Client API 变为如下所示
const user = await prisma.user.findUnique({
where: {
fullName: {
firstName: 'Paul',
lastName: 'Panther',
},
},
})