Skip to main content

如何使用 Prisma ORM 的类型系统

本指南介绍了 Prisma ORM 的类型系统，并解释了如何内省数据库中现有的原生类型，以及在使用 Prisma Migrate 或 db push 将架构更改应用到数据库时如何使用类型。

¥This guide introduces Prisma ORM's type system and explains how to introspect existing native types in your database, and how to use types when you apply schema changes to your database with Prisma Migrate or db push.

Prisma ORM 的类型系统如何工作？​

¥How does Prisma ORM's type system work?

Prisma ORM 使用类型来定义字段可以保存的数据类型。为了方便入门，Prisma ORM 提供了少量的核心 标量类型，应该涵盖大多数默认用例。例如，采用以下博客文章模型：

¥Prisma ORM uses types to define the kind of data that a field can hold. To make it easy to get started, Prisma ORM provides a small number of core scalar types that should cover most default use cases. For example, take the following blog post model:

schema.prisma
datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model Post {
  id        Int      @id
  title     String
  createdAt DateTime
}

Post 模型的 title 字段使用 String 标量类型，而 createdAt 字段使用 DateTime 标量类型。

¥The title field of the Post model uses the String scalar type, while the createdAt field uses the DateTime scalar type.

数据库也有自己的类型系统，它定义列可以保存的值的类型。大多数数据库提供大量数据类型，以便对列可以存储的内容进行细粒度控制。例如，数据库可能提供对多种大小的整数或 XML 数据的内置支持。这些类型的名称因数据库而异。例如，在 PostgreSQL 中，布尔值的列类型是 boolean，而在 MySQL 中，通常使用 tinyint(1) 类型。

¥Databases also have their own type system, which defines the type of value that a column can hold. Most databases provide a large number of data types to allow fine-grained control over exactly what a column can store. For example, a database might provide inbuilt support for multiple sizes of integers, or for XML data. The names of these types vary between databases. For example, in PostgreSQL the column type for booleans is boolean, whereas in MySQL the tinyint(1) type is typically used.

在上面的博客文章示例中，我们使用 PostgreSQL 连接器。这是在 Prisma 模式的 datasource 块中指定的。

¥In the blog post example above, we are using the PostgreSQL connector. This is specified in the datasource block of the Prisma schema.

默认类型映射​

¥Default type mappings

为了让你开始使用我们的核心标量类型，Prisma ORM 提供了默认类型映射，将每个标量类型映射到底层数据库中的默认类型。例如：

¥To allow you to get started with our core scalar types, Prisma ORM provides default type mappings that map each scalar type to a default type in the underlying database. For example:

  • 默认情况下，Prisma ORM 的 String 类型映射到 PostgreSQL 的 text 类型和 MySQL 的 varchar 类型

    ¥by default Prisma ORM's String type gets mapped to PostgreSQL's text type and MySQL's varchar type

  • 默认情况下，Prisma ORM 的 DateTime 类型映射到 PostgreSQL 的 timestamp(3) 类型和 SQL Server 的 datetime2 类型

    ¥by default Prisma ORM's DateTime type gets mapped to PostgreSQL's timestamp(3) type and SQL Server's datetime2 type

有关给定数据库的默认类型映射，请参阅 Prisma ORM 的 数据库连接器页面。例如，此表格 给出 PostgreSQL 的默认类型映射。要查看特定给定 Prisma ORM 类型的所有数据库的默认类型映射，请参阅 Prisma 架构参考的 模型字段标量类型部分。例如，此表格 给出 Float 标量类型的默认类型映射。

¥See Prisma ORM's database connector pages for the default type mappings for a given database. For example, this table gives the default type mappings for PostgreSQL.\ To see the default type mappings for all databases for a specific given Prisma ORM type, see the model field scalar types section of the Prisma schema reference. For example, this table gives the default type mappings for the Float scalar type.

原生类型映射​

¥Native type mappings

有时你可能需要使用更具体的数据库类型，该类型不是 Prisma ORM 类型的默认类型映射之一。为此，Prisma ORM 提供了 原生类型属性 来细化核心标量类型。例如，在上面 Post 模型的 createdAt 字段中，你可能希望通过使用 date 类型而不是 timestamp(3) 的默认类型映射，在基础 PostgreSQL 数据库中使用仅日期列。为此，请将 @db.Date 原生类型属性添加到 createdAt 字段：

¥Sometimes you may need to use a more specific database type that is not one of the default type mappings for your Prisma ORM type. For this purpose, Prisma ORM provides native type attributes to refine the core scalar types. For example, in the createdAt field of your Post model above you may want to use a date-only column in your underlying PostgreSQL database, by using the date type instead of the default type mapping of timestamp(3). To do this, add a @db.Date native type attribute to the createdAt field:

schema.prisma
model Post {
  id        Int      @id
  title     String
  createdAt DateTime @db.Date
}

原生类型映射允许你表达数据库中的所有类型。但是，如果 Prisma ORM 默认值满足你的需求，则不需要使用它们。这将为常见用例提供更短、更易读的 Prisma 架构。

¥Native type mappings allow you to express all the types in your database. However, you do not need to use them if the Prisma ORM defaults satisfy your needs. This leads to a shorter, more readable Prisma schema for common use cases.

如何内省数据库类型​

¥How to introspect database types

当你对现有数据库进行 introspect 时，Prisma ORM 将获取每个表列的数据库类型，并使用相应模型字段的正确 Prisma ORM 类型在 Prisma 架构中表示它。如果数据库类型不是该 Prisma ORM 标量类型的默认数据库类型，Prisma ORM 还将添加原生类型属性。

¥When you introspect an existing database, Prisma ORM will take the database type of each table column and represent it in your Prisma schema using the correct Prisma ORM type for the corresponding model field. If the database type is not the default database type for that Prisma ORM scalar type, Prisma ORM will also add a native type attribute.

例如，以 PostgreSQL 数据库中的 User 表为例，其中：

¥As an example, take a User table in a PostgreSQL database, with:

  • 数据类型为 serial 的 id 列

    ¥an id column with a data type of serial

  • 数据类型为 text 的 name 列

    ¥a name column with a data type of text

  • 数据类型为 boolean 的 isActive 列

    ¥an isActive column with a data type of boolean

你可以使用以下 SQL 命令创建它：

¥You can create this with the following SQL command:

CREATE TABLE "public"."User" (
  id serial PRIMARY KEY NOT NULL,
  name text NOT NULL,
  "isActive" boolean NOT NULL
);

使用从项目的根目录运行以下命令来检查你的数据库：

¥Introspect your database with the following command run from the root directory of your project:

npx prisma db pull

你将获得以下 Prisma 架构：

¥You will get the following Prisma schema:

schema.prisma
model User {
  id       Int     @id @default(autoincrement())
  name     String
  isActive Boolean
}

数据库中的 id、name 和 isActive 列分别映射到 Int、String 和 Boolean Prisma ORM 类型。数据库类型是这些 Prisma ORM 类型的默认数据库类型，因此 Prisma ORM 不会添加任何原生类型属性。

¥The id, name and isActive columns in the database are mapped respectively to the Int, String and Boolean Prisma ORM types. The database types are the default database types for these Prisma ORM types, so Prisma ORM does not add any native type attributes.

现在，通过运行以下 SQL 命令将数据类型为 date 的 createdAt 列添加到数据库：

¥Now add a createdAt column to your database with a data type of date by running the following SQL command:

ALTER TABLE "public"."User"
ADD COLUMN "createdAt" date NOT NULL;

再次检查你的数据库：

¥Introspect your database again:

npx prisma db pull

你的 Prisma 架构现在包含新的 createdAt 字段，其 Prisma ORM 类型为 DateTime。createdAt 字段还有一个 @db.Date 原生类型属性，因为 PostgreSQL 的 date 不是 DateTime 类型的默认类型：

¥Your Prisma schema now includes the new createdAt field with a Prisma ORM type of DateTime. The createdAt field also has a @db.Date native type attribute, because PostgreSQL's date is not the default type for the DateTime type:

schema.prisma
model User {
  id        Int      @id @default(autoincrement())
  name      String
  isActive  Boolean
  createdAt DateTime @db.Date
}

将架构更改应用于数据库时如何使用类型​

¥How to use types when you apply schema changes to your database

当你使用 Prisma Migrate 或 db push 将架构更改应用到数据库时，Prisma ORM 将使用每个字段的 Prisma ORM 标量类型及其必须的任何原生属性来确定数据库中相应列的正确数据库类型。

¥When you apply schema changes to your database using Prisma Migrate or db push, Prisma ORM will use both the Prisma ORM scalar type of each field and any native attribute it has to determine the correct database type for the corresponding column in the database.

例如，使用以下 Post 模型创建 Prisma 架构：

¥As an example, create a Prisma schema with the following Post model:

schema.prisma
model Post {
  id        Int      @id
  title     String
  createdAt DateTime
  updatedAt DateTime @db.Date
}

该 Post 型号具有：

¥This Post model has:

  • Prisma ORM 类型为 Int 的 id 字段

    ¥an id field with a Prisma ORM type of Int

  • Prisma ORM 类型为 String 的 title 字段

    ¥a title field with a Prisma ORM type of String

  • Prisma ORM 类型为 DateTime 的 createdAt 字段

    ¥a createdAt field with a Prisma ORM type of DateTime

  • 具有 DateTime Prisma ORM 类型和 @db.Date 原生类型属性的 updatedAt 字段

    ¥an updatedAt field with a Prisma ORM type of DateTime and a @db.Date native type attribute

现在，使用以下命令将这些更改应用到空的 PostgreSQL 数据库，从项目的根目录运行：

¥Now apply these changes to an empty PostgreSQL database with the following command, run from the root directory of your project:

npx prisma db push

你将看到数据库有一个新创建的 Post 表，其中：

¥You will see that the database has a newly created Post table, with:

  • 数据库类型为 integer 的 id 列

    ¥an id column with a database type of integer

  • 数据库类型为 text 的 title 列

    ¥a title column with a database type of text

  • 数据库类型为 timestamp(3) 的 createdAt 列

    ¥a createdAt column with a database type of timestamp(3)

  • 数据库类型为 date 的 updatedAt 列

    ¥an updatedAt column with a database type of date

请注意，@db.Date 原生类型属性将 updatedAt 列的数据库类型修改为 date，而不是默认的 timestamp(3)。

¥Notice that the @db.Date native type attribute modifies the database type of the updatedAt column to date, rather than the default of timestamp(3).

有关使用 Prisma ORM 类型系统的更多信息​

¥More on using Prisma ORM's type system

有关使用 Prisma ORM 类型系统的更多参考信息，请参阅以下资源：

¥For further reference information on using Prisma ORM's type system, see the following resources:

  • 每个数据库提供程序的 数据库连接器 页面都有一个类型映射部分，其中包含 Prisma ORM 类型和数据库类型之间的默认类型映射表，以及数据库类型及其在 Prisma ORM 中相应的原生类型属性的表。例如，PostgreSQL 的类型映射部分是 此处。

    ¥The database connector page for each database provider has a type mapping section with a table of default type mappings between Prisma ORM types and database types, and a table of database types with their corresponding native type attribute in Prisma ORM. For example, the type mapping section for PostgreSQL is here.

  • Prisma 架构参考的 模型字段标量类型 部分针对每个 Prisma ORM 标量类型都有一个小节。这包括每个数据库中 Prisma ORM 类型的默认映射表，以及每个数据库的表，列出了 Prisma ORM 中相应的数据库类型及其原生类型属性。例如，String Prisma ORM 类型的条目是 此处。

    ¥The model field scalar types section of the Prisma schema reference has a subsection for each Prisma ORM scalar type. This includes a table of default mappings for that Prisma ORM type in each database, and a table for each database listing the corresponding database types and their native type attributes in Prisma ORM. For example, the entry for the String Prisma ORM type is here.