跳到主要内容

CockroachDB

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

信息

CockroachDB 连接器在 3.14.0 及更高版本中普遍可用。它最初作为一项 预览功能 在版本 3.9.0` 中首次添加，支持内省，而 Prisma Migrate 支持则在 3.11.0` 中添加。

什么是 CockroachDB？​

CockroachDB 是一个分布式数据库，专为可伸缩性和高可用性而设计。其功能包括：

  • 与 PostgreSQL 的兼容性：CockroachDB 与 PostgreSQL 兼容，允许与现有产品的庞大生态系统互操作
  • 内置伸缩：CockroachDB 具有自动化复制、故障转移和修复功能，可轻松实现应用程序的横向伸缩

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

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

需要考虑的差异​

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

如何在 CockroachDB 中使用 Prisma ORM​

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

如何使用 CockroachDB 的原生类型​

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

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

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 Schema 中将有一个新的 Post 模型

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

请注意，title 字段已用 @db.String(200) 进行标注——这与 PostgreSQL 不同，在 PostgreSQL 中标注将是 @db.VarChar(200)。

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

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

在分布式数据库（如 CockroachDB）中为记录生成唯一标识符时，最好避免使用顺序 ID——有关此内容的更多信息，请参阅 CockroachDB 的关于选择索引键的博客文章。

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

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

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

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

示例​

要连接到 CockroachDB 数据库服务器，你需要在 Prisma Schema 中配置一个 datasource 块

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

传递给 datasource 块的字段是：

  • provider：指定 cockroachdb 数据源连接器。
  • url：指定 CockroachDB 数据库服务器的连接 URL。在这种情况下，使用环境变量来提供连接 URL。
信息

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

连接详情​

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

CockroachDB 与 PostgreSQL 之间的差异​

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

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

CockroachDB 中的类型映射限制​

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

CockroachDB (类型 | 别名)Prisma ORM支持原生数据库类型属性备注
moneyDecimal暂不支持@db.MoneyPostgreSQL 支持，但CockroachDB 目前不支持
xmlString暂不支持@db.XmlPostgreSQL 支持，但CockroachDB 目前不支持
jsonb 数组Json[]暂不支持不适用PostgreSQL 支持 Json[]，但CockroachDB 目前不支持

其他限制​

下表列出了 CockroachDB 相较于 PostgreSQL 的其他当前已知限制：

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

CockroachDB 与 Prisma Schema 之间的类型映射​

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

另外，请参阅按 Prisma ORM 类型组织的类型映射的Prisma Schema 参考。

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

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

内省时从 CockroachDB 到 Prisma ORM 类型的映射​

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

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字段

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

更多关于使用 CockroachDB 与 Prisma ORM 的信息​

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

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

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

© . All rights reserved.