Skip to main content

CockroachDB

本指南讨论使用 Prisma ORM 和 CockroachDB 背后的概念，解释 CockroachDB 与其他数据库提供商之间的共性和差异，并引导你完成配置应用以与 CockroachDB 集成的过程。

¥This guide discusses the concepts behind using Prisma ORM and CockroachDB, explains the commonalities and differences between CockroachDB and other database providers, and leads you through the process for configuring your application to integrate with CockroachDB.

info

CockroachDB 连接器通常提供 3.14.0 及更高版本。它首先在版本 3.9.0 中作为 预览功能 添加，并支持 Introspection，并在 3.11.0 中添加了 Prisma Migrate 支持。

¥The CockroachDB connector is generally available in versions 3.14.0 and later. It was first added as a Preview feature in version 3.9.0 with support for Introspection, and Prisma Migrate support was added in 3.11.0.

什么是 CockroachDB？​

¥What is CockroachDB?

CockroachDB 是一个分布式数据库，专为可扩展性和高可用性而设计。特点包括：

¥CockroachDB is a distributed database that is designed for scalability and high availability. Features include:

  • 与 PostgreSQL 的兼容性：CockroachDB 与 PostgreSQL 兼容，允许与现有产品的大型生态系统进行互操作

    ¥Compatibility with PostgreSQL: CockroachDB is compatible with PostgreSQL, allowing interoperability with a large ecosystem of existing products

  • 内置缩放：CockroachDB 具有自动复制、故障转移和修复功能，可轻松水平扩展应用

    ¥Built-in scaling: CockroachDB comes with automated replication, failover and repair capabilities to allow easy horizontal scaling of your application

与其他数据库提供商的共同点​

¥Commonalities with other database providers

CockroachDB 与 PostgreSQL 很大程度上兼容，并且大部分可以以相同的方式与 Prisma ORM 一起使用。你仍然可以：

¥CockroachDB is largely compatible with PostgreSQL, and can mostly be used with Prisma ORM in the same way. You can still:

需要考虑的差异​

¥Differences to consider

使用 Prisma ORM 的 cockroachdb 连接器时，需要注意一些 CockroachDB 特定的差异：

¥There are some CockroachDB-specific differences to be aware of when working with Prisma ORM's cockroachdb connector:

如何将 Prisma ORM 与 CockroachDB 结合使用​

¥How to use Prisma ORM with CockroachDB

本节提供有关如何使用 CockroachDB 特定功能的更多详细信息。

¥This section provides more details on how to use CockroachDB-specific features.

如何使用 CockroachDB 的原生类型​

¥How to use CockroachDB's native types

CockroachDB 有自己的一套原生 数据类型，在 Prisma ORM 中受支持。例如，CockroachDB 使用 STRING 数据类型而不是 PostgreSQL 的 VARCHAR。

¥CockroachDB has its own set of native data types which are supported in Prisma ORM. For example, CockroachDB uses the STRING data type instead of PostgreSQL's VARCHAR.

作为演示，假设你使用以下 SQL 命令在 CockroachDB 数据库中创建一个 User 表：

¥As a demonstration of this, say you create a User table in your CockroachDB database using the following SQL command:

CREATE TABLE public."Post" (
  "id" INT8 NOT NULL,
  "title" VARCHAR(200) NOT NULL,
  CONSTRAINT "Post_pkey" PRIMARY KEY ("id" ASC),
  FAMILY "primary" ("id", "title")
);

使用 npx prisma db pull 检查数据库后，你的 Prisma 模式中将有一个新的 Post 模型：

¥After introspecting your database with npx prisma db pull, you will have a new Post model in your Prisma Schema:

schema.prisma
model Post {
  id    BigInt @id
  title String @db.String(200)
}

请注意，title 字段已用 @db.String(200) 进行了注释 - 这与 PostgreSQL 中的注释为 @db.VarChar(200) 不同。

¥Notice that the title field has been annotated with @db.String(200) — this differs from PostgreSQL where the annotation would be @db.VarChar(200).

有关类型映射的完整列表，请参阅我们的 连接器文档。

¥For a full list of type mappings, see our connector documentation.

如何在 CockroachDB 中使用数据库键​

¥How to use database keys with CockroachDB

当为像 CockroachDB 这样的分布式数据库中的记录生成唯一标识符时，最好避免使用顺序 ID – 有关这方面的更多信息，请参阅 CockroachDB 的 关于选择索引键的博客文章。

¥When generating unique identifiers for records in a distributed database like CockroachDB, it is best to avoid using sequential IDs – for more information on this, see CockroachDB's blog post on choosing index keys.

相反，Prisma ORM 提供了 autoincrement() 属性函数，该函数使用 CockroachDB 的 unique_rowid() 功能 来生成唯一标识符。例如，以下 User 模型具有使用 autoincrement() 函数生成的 id 主键：

¥Instead, Prisma ORM provides the autoincrement() attribute function, which uses CockroachDB's unique_rowid() function for generating unique identifiers. For example, the following User model has an id primary key, generated using the autoincrement() function:

schema.prisma
model User {
  id   BigInt @id @default(autoincrement())
  name String
}

为了与现有数据库兼容，有时你可能仍然需要生成固定的整数键值序列。在这些情况下，你可以使用 Prisma ORM 的 CockroachDB 内置 sequence() 函数。有关 sequence() 功能的可用选项列表，请参阅我们的 参考文档。

¥For compatibility with existing databases, you may sometimes still need to generate a fixed sequence of integer key values. In these cases, you can use Prisma ORM's inbuilt sequence() function for CockroachDB. For a list of available options for the sequence() function, see our reference documentation.

有关生成数据库密钥的更多信息，请参阅 CockroachDB 的 主键最佳实践 指南。

¥For more information on generating database keys, see CockroachDB's Primary key best practices guide.

示例​

¥Example

要连接到 CockroachDB 数据库服务器，你需要在 Prisma 架构 中配置 datasource 块：

¥To connect to a CockroachDB database server, you need to configure a datasource block in your Prisma schema:

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

传递到 datasource 块的字段是：

¥The fields passed to the datasource block are:

  • provider：指定 cockroachdb 数据源连接器。

    ¥provider: Specifies the cockroachdb data source connector.

  • url：指定 CockroachDB 数据库服务器的 连接网址。在本例中，使用环境变量 提供连接 URL。

    ¥url: Specifies the connection URL for the CockroachDB database server. In this case, an environment variable is used to provide the connection URL.

info

虽然 cockroachdb 和 postgresql 连接器类似，但从版本 5.0.0 连接到 CockroachDB 数据库时，必须使用 cockroachdb 连接器而不是 postgresql。

¥While cockroachdb and postgresql connectors are similar, it is mandatory to use the cockroachdb connector instead of postgresql when connecting to a CockroachDB database from version 5.0.0.

连接详情​

¥Connection details

CockroachDB 使用 PostgreSQL 格式作为其连接 URL。有关此格式及其采用的可选参数的详细信息，请参阅 PostgreSQL 连接器文档。

¥CockroachDB uses the PostgreSQL format for its connection URL. See the PostgreSQL connector documentation for details of this format, and the optional arguments it takes.

CockroachDB 和 PostgreSQL 之间的区别​

¥Differences between CockroachDB and PostgreSQL

下表列出了 CockroachDB 和 PostgreSQL 之间的差异：

¥The following table lists differences between CockroachDB and PostgreSQL:

问题区域注意
默认情况下，INT 类型是 CockroachDB 中 INT8 的别名，而在 PostgreSQL 中它是 INT4 的别名。这意味着 Prisma ORM 会将 CockroachDB 中的 INT 列内省为 BigInt，而在 PostgreSQL 中，Prisma ORM 会将其内省为 Int。模式有关 INT 类型的更多信息，请参阅 CockroachDB 文档
当在字段上使用 @default(autoincrement()) 时，CockroachDB 将自动为行 ID 生成 64 位整数。这些整数将递增但不连续。这与 PostgreSQL 不同，PostgreSQL 生成的行 ID 是连续的并且从 1 开始。模式有关生成值的更多信息，请参阅 CockroachDB 文档
@default(autoincrement()) 属性只能与 BigInt 字段类型一起使用。模式有关生成值的更多信息，请参阅 CockroachDB 文档

CockroachDB 中的类型映射限制​

¥Type mapping limitations in CockroachDB

CockroachDB 连接器将 标量类型 从 Prisma ORM 数据模型 映射到原生列类型。这些原生类型与 PostgreSQL 基本相同 - 有关详细信息，请参阅 从 Prisma ORM 到 CockroachDB 的原生类型映射。但是，也有一些限制：

¥The CockroachDB connector maps the scalar types from the Prisma ORM data model to native column types. These native types are mostly the same as for PostgreSQL — see the Native type mapping from Prisma ORM to CockroachDB for details. However, there are some limitations:

CockroachDB（类型 | 别名）Prisma ORM支持的原生数据库类型属性注意
moneyDecimal还没有@db.MoneyPostgreSQL 支持，但 目前不在 CockroachDB 中
xmlString还没有@db.XmlPostgreSQL 支持，但 目前不在 CockroachDB 中
jsonb 数组Json[]还没有不适用PostgreSQL 支持 Json[]，但 目前不在 CockroachDB 中

其他限制​

¥Other limitations

下表列出了 CockroachDB 与 PostgreSQL 相比的任何其他当前已知限制：

¥The following table lists any other current known limitations of CockroachDB compared to PostgreSQL:

问题区域注意
不支持索引类型 Hash、Gist、SpGist 或 Brin。模式在 PostgreSQL 中，Prisma ORM 允许 索引的配置 使用不同的索引访问方法。CockroachDB 目前仅支持 BTree 和 Gin。
不支持推送到 Enum 类型客户推送到 Enum 类型（例如 data: { enum { push: "A" }, }）目前是 CockroachDB 不支持
不支持在没有全文索引的情况下搜索 String 字段客户在没有全文索引（例如 where: { text: { search: "cat & dog", }, },）的 String 字段上搜索当前为 CockroachDB 不支持
不支持整数除法客户整数除法（例如 data: { int: { divide: 10, }, }）当前为 CockroachDB 不支持
对 Json 字段的有限过滤客户目前 CockroachDB 只支持 equals 和 not 对 Json 字段进行过滤

CockroachDB 和 Prisma 模式之间的类型映射​

¥Type mapping between CockroachDB and the Prisma schema

CockroachDB 连接器将 Prisma ORM 数据模型 中的 标量类型 映射到原生列类型，如下所示：

¥The CockroachDB connector maps the scalar types from the Prisma ORM data model as follows to native column types:

或者，请参阅 Prisma 架构参考 以了解按 Prisma ORM 类型组织的类型映射。

¥Alternatively, see the Prisma schema reference for type mappings organized by Prisma ORM type.

从 Prisma ORM 到 CockroachDB 的原生类型映射​

¥Native type mapping from Prisma ORM to CockroachDB

Prisma ORMCockroachDB
StringSTRING
BooleanBOOL
IntINT4
BigIntINT8
FloatFLOAT8
DecimalDECIMAL(65,30)
DateTimeTIMESTAMP(3)
JsonJSONB
BytesBYTES

在 Introspection 上从 CockroachDB 映射到 Prisma ORM 类型​

¥Mapping from CockroachDB to Prisma ORM types on Introspection

当内省 CockroachDB 数据库时，数据库类型根据下表映射到 Prisma ORM：

¥When introspecting a CockroachDB database, the database types are mapped to Prisma ORM according to the following table:

CockroachDB（类型 | 别名）Prisma ORM支持的原生数据库类型属性注意
INT | BIGINT, INTEGERBigInt✔️@db.Int8
BOOL | BOOLEANBool✔️@db.Bool*
TIMESTAMP | TIMESTAMP WITHOUT TIME ZONEDateTime✔️@db.Timestamp(x)
TIMESTAMPTZ | TIMESTAMP WITH TIME ZONEDateTime✔️@db.Timestamptz(x)
TIME | TIME WITHOUT TIME ZONEDateTime✔️@db.Time(x)
TIMETZ | TIME WITH TIME ZONEDateTime✔️@db.Timetz(x)
DECIMAL(p,s) | NUMERIC(p,s), DEC(p,s)Decimal✔️@db.Decimal(x, y)
REAL | FLOAT4, FLOATFloat✔️@db.Float4
DOUBLE PRECISION | FLOAT8Float✔️@db.Float8
INT2 | SMALLINTInt✔️@db.Int2
INT4Int✔️@db.Int4
CHAR(n) | CHARACTER(n)String✔️@db.Char(x)
"char"String✔️@db.CatalogSingleCharCockroachDB 目录表的内部类型，不适合终端用户。
STRING | TEXT, VARCHARString✔️@db.String
DATEDateTime✔️@db.Date
ENUMenum✔️不适用
INETString✔️@db.Inet
BIT(n)String✔️@Bit(x)
VARBIT(n) | BIT VARYING(n)String✔️@VarBit
OIDInt✔️@db.Oid
UUIDString✔️@db.Uuid
JSONB | JSONJson✔️@db.JsonB
数组类型[]✔️

内省 添加了 Unsupported 字段尚不支持的原生数据库类型：

¥Introspection adds native database types that are not yet supported as Unsupported fields:

schema.prisma
model Device {
  id       BigInt                  @id @default(autoincrement())
  interval Unsupported("INTERVAL")
}

有关将 CockroachDB 与 Prisma ORM 结合使用的更多信息​

¥More on using CockroachDB with Prisma ORM

开始将 CockroachDB 与 Prisma ORM 结合使用的最快方法是参考我们的入门文档：

¥The fastest way to start using CockroachDB with Prisma ORM is to refer to our Getting Started documentation:

这些教程将引导你完成连接到 CockroachDB、迁移架构和使用 Prisma Client 的过程。

¥These tutorials will take you through the process of connecting to CockroachDB, migrating your schema, and using Prisma Client.

更多参考信息可在 CockroachDB 连接器文档 中找到。

¥Further reference information is available in the CockroachDB connector documentation.