数据库映射

Prisma 架构包含允许你定义某些数据库对象名称的机制。你可以：

¥The Prisma schema includes mechanisms that allow you to define names of certain database objects. You can:

映射集合/表和字段/列名称

¥Mapping collection/table and field/column names

有时，用于描述数据库中实体的名称可能与你在生成的 API 中希望使用的名称不匹配。Prisma 架构中的映射名称允许你影响客户端 API 中的命名，而无需更改底层数据库名称。

¥Sometimes the names used to describe entities in your database might not match the names you would prefer in your generated API. Mapping names in the Prisma schema allows you to influence the naming in your Client API without having to change the underlying database names.

例如，在数据库中命名表/集合的常见方法是使用复数形式和蛇箱表示法。然而，我们推荐了不同的命名约定（单数形式，PascalCase）。

¥A common approach for naming tables/collections in databases for example is to use plural form and snake_case notation. However, we recommended a different naming convention (singular form, PascalCase).

@map 和 @@map 允许你通过将模型和字段名称与基础数据库中的表和列名称解耦来实现调整 Prisma 客户端 API 的形状。

¥@map and @@map allow you to tune the shape of your Prisma Client API by decoupling model and field names from table and column names in the underlying database.

映射集合/表名称

¥Map collection / table names

例如，当你 introspect 一个包含名为 comments 的表的数据库时，生成的 Prisma 模型将如下所示：

¥As an example, when you introspect a database with a table named comments, the resulting Prisma model will look like this:

model comments {
  // Fields
}

但是，你仍然可以选择 Comment 作为模型的名称（例如，遵循命名约定），而无需使用 @@map 属性重命名数据库中的基础 comments 表：

¥However, you can still choose Comment as the name of the model (e.g. to follow the naming convention) without renaming the underlying comments table in the database by using the @@map attribute:

model Comment {
  // Fields

  @@map("comments")
}

通过此修改后的模型定义，Prisma 客户端会自动将 Comment 模型映射到基础数据库中的 comments 表。

¥With this modified model definition, Prisma Client automatically maps the Comment model to the comments table in the underlying database.

映射字段/列名称

¥Map field / column names

你还可以 @map 列/字段名称：

¥You can also @map a column/field name:

model Comment {
  content String @map("comment_text")
  email   String @map("commenter_email")
  type    Enum   @map("comment_type")

  @@map("comments")
}

这样，comment_text 列在 Prisma 客户端 API 中的 prisma.comment.comment_text 下不可用，但可以通过 prisma.comment.content 访问。

¥This way the comment_text column is not available under prisma.comment.comment_text in the Prisma Client API, but can be accessed via prisma.comment.content.

映射枚举名称和值

¥Map enum names and values

你还可以 @map 一个枚举值，或 @@map 一个枚举：

¥You can also @map an enum value, or @@map an enum:

enum Type {
  Blog,
  Twitter @map("comment_twitter")

  @@map("comment_source_enum")
}

约束和索引名称

¥Constraint and index names

你可以选择使用 map 参数在 Prisma 架构中为属性 @id、@@id、@unique、@@unique、@@index 和 @relation 显式定义基础约束和索引名称。（这在 Prisma ORM 版本 2.29.0 及更高版本中可用。）

¥You can optionally use the map argument to explicitly define the underlying constraint and index names in the Prisma schema for the attributes @id, @@id, @unique, @@unique, @@index and @relation. (This is available in Prisma ORM version 2.29.0 and later.)

内省数据库时，只有当名称与 Prisma ORM 的索引和约束的默认约束命名约定不同时，map 参数才会在模式中渲染。

¥When introspecting a database, the map argument will only be rendered in the schema if the name differs from Prisma ORM's default constraint naming convention for indexes and constraints.

danger

如果你在 2.29.0 之前的版本中使用 Prisma Migrate，并且希望在升级到较新版本后保留现有的约束和索引名称，请不要立即运行 prisma migrate 或 prisma db push。这将更改任何不遵循 Prisma ORM 约定的底层约束名称。跟随允许你维护现有约束和索引名称的升级路径。

¥If you use Prisma Migrate in a version earlier than 2.29.0 and want to maintain your existing constraint and index names after upgrading to a newer version, do not immediately run prisma migrate or prisma db push. This will change any underlying constraint name that does not follow Prisma ORM's convention. Follow the upgrade path that allows you to maintain existing constraint and index names.

命名约束的用例

¥Use cases for named constraints

显式命名约束的一些用例包括：

¥Some use cases for explicitly named constraints include:

公司政策

¥Company policy
其他工具的约定

¥Conventions of other tools

Prisma ORM 索引和约束的默认命名约定

¥Prisma ORM's default naming conventions for indexes and constraints

选择 Prisma ORM 命名约定是为了与 PostgreSQL 保持一致，因为它是确定性的。它还有助于最大限度地增加不需要渲染名称的次数，因为许多数据库已经符合约定。

¥Prisma ORM naming convention was chosen to align with PostgreSQL since it is deterministic. It also helps to maximize the amount of times where names do not need to be rendered because many databases out there they already align with the convention.

Prisma ORM 在生成默认索引和约束名称时始终使用实体的数据库名称。如果通过 @@map 或 @map 将模型重新映射到数据模型中的不同名称，则默认名称生成仍将数据库中表的名称作为输入。对于字段和列也是如此。

¥Prisma ORM always uses the database names of entities when generating the default index and constraint names. If a model is remapped to a different name in the data model via @@map or @map, the default name generation will still take the name of the table in the database as input. The same is true for fields and columns.

实体	惯例	示例
首要的关键	{表名}_pkey	`User_pkey`
唯一约束	{表名}--{列名}_key	`User_firstName_last_Name_key`
非唯一索引	{表名}--{列名}_idx	`User_age_idx`
外键	{表名}--{列名}_fkey	`User_childName_fkey`

由于大多数数据库对实体名称有长度限制，因此如有必要，名称将被修剪，以免违反数据库限制。我们将根据需要缩短 _suffix 之前的部分，使全名不超过允许的最大长度。

¥Since most databases have a length limit for entity names, the names will be trimmed if necessary to not violate the database limits. We will shorten the part before the _suffix as necessary so that the full name is at most the maximum length permitted.

使用默认约束名称

¥Using default constraint names

当没有通过 map 参数提供显式名称时，Prisma ORM 将在默认命名约定后面生成索引和约束名称。

¥When no explicit names are provided via map arguments Prisma ORM will generate index and constraint names following the default naming convention.

如果你内省数据库，索引和约束的名称将添加到你的架构中，除非它们遵循 Prisma ORM 的命名约定。如果这样做，则不会渲染名称以保持架构更具可读性。当你迁移此类架构时，Prisma 将推断默认名称并将其保留在数据库中。

¥If you introspect a database the names for indexes and constraints will be added to your schema unless they follow Prisma ORM's naming convention. If they do, the names are not rendered to keep the schema more readable. When you migrate such a schema Prisma will infer the default names and persist them in the database.

示例

¥Example

以下架构定义了三个约束（@id、@unique 和 @relation）和一个索引（@@index）：

¥The following schema defines three constraints (@id, @unique, and @relation) and one index (@@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 将假设它们遵循我们的默认命名约定。

¥Since no explicit names are provided via map arguments Prisma will assume they follow our default naming convention.

下表列出了底层数据库中每个约束和索引的名称：

¥The following table lists the name of each constraint and index in the underlying database:

约束或索引	遵循惯例	底层约束或索引名称
`@id`（在 `User` > `id` 字段上）	是的	`User_pk`
`@@index`（`Post` 月）	是的	`Post_title_authorName_idx`
`@id`（在 `Post` > `id` 字段上）	是的	`Post_pk`
`@relation`（在 `Post` > `author` 上）	是的	`Post_authorName_fkey`

使用自定义约束/索引名称

¥Using custom constraint / index names

你可以使用 map 参数在基础数据库中定义自定义约束和索引名称。

¥You can use the map argument to define custom constraint and index names in the underlying database.

示例

¥Example

以下示例将自定义名称添加到 @id 和 @@index：

¥The following example adds custom names to one @id and the @@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")
}

下表列出了底层数据库中每个约束和索引的名称：

¥The following table lists the name of each constraint and index in the underlying database:

约束或索引	遵循惯例	底层约束或索引名称
`@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 客户端的命名索引和主键

¥Related: Naming indexes and primary keys for Prisma Client

除了 map 之外，@@id 和 @@unique 属性还采用可选的 name 参数，允许你自定义 Prisma 客户端 API。

¥Additionally to map, the @@id and @@unique attributes take an optional name argument that allows you to customize your Prisma Client API.

在这样的模型上：

¥On a model like:

model User {
  firstName String
  lastName  String

  @@id([firstName, lastName])
}

用于选择该主键的默认 API 使用生成的字段组合：

¥the default API for selecting on that primary key uses a generated combination of the fields:

const user = await prisma.user.findUnique({
  where: {
    firstName_lastName: {
      firstName: 'Paul',
      lastName: 'Panther',
    },
  },
})

指定 @@id([firstName, lastName], name: "fullName") 会将 Prisma 客户端 API 更改为：

¥Specifying @@id([firstName, lastName], name: "fullName") will change the Prisma Client API to this instead:

const user = await prisma.user.findUnique({
  where: {
    fullName: {
      firstName: 'Paul',
      lastName: 'Panther',
    },
  },
})

映射集合/表和字段/列名称​

映射集合/表名称​

映射字段/列名称​

映射枚举名称和值​

约束和索引名称​

命名约束的用例​

Prisma ORM 索引和约束的默认命名约定​

使用默认约束名称​

示例​

使用自定义约束/索引名称​

示例​

有关的：Prisma 客户端的命名索引和主键​