跳到主要内容

CockroachDB

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

信息

CockroachDB 连接器在版本 3.14.0 及更高版本中普遍可用。它最初在版本 预览特性 中添加为 3.9.0 并支持自省，并在 3.11.0 中添加了对 Prisma Migrate 的支持。

什么是 CockroachDB？​

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

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

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

CockroachDB 在很大程度上与 PostgreSQL 兼容，并且在使用 Prisma ORM 时也基本相同。您仍然可以

需要考虑的差异​

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

如何使用 Prisma ORM 连接 CockroachDB​

本节提供有关如何使用 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 模型有一个使用 autoincrement() 函数生成的 id 主键

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

为了与现有数据库兼容，您有时可能仍然需要生成固定的整数键值序列。在这些情况下，您可以对 CockroachDB 使用 Prisma ORM 内置的 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 中，Prisma ORM 将其自省为 Int。Schema有关 INT 类型的更多信息，请参阅 CockroachDB 文档
在字段上使用 @default(autoincrement()) 时，CockroachDB 将自动为行 ID 生成 64 位整数。这些整数将是递增的，但不连续。这与 PostgreSQL 不同，在 PostgreSQL 中生成的行 ID 是连续的，从 1 开始。Schema有关生成值的更多信息，请参阅 CockroachDB 文档
@default(autoincrement()) 属性只能与 BigInt 字段类型一起使用。Schema有关生成值的更多信息，请参阅 CockroachDB 文档

CockroachDB 中的类型映射限制​

CockroachDB 连接器将 Prisma ORM 数据模型 中的 标量类型 映射到原生列类型，如下所示。这些原生类型大多与 PostgreSQL 相同 — 详情请参阅 从 Prisma ORM 到 CockroachDB 的原生类型映射。但是，存在一些限制

CockroachDB（类型 | 别名）Prisma ORM支持原生数据库类型属性备注
moneyDecimal暂不支持@db.Money在 PostgreSQL 中支持，但 当前在 CockroachDB 中不支持
xmlString暂不支持@db.Xml在 PostgreSQL 中支持，但 当前在 CockroachDB 中不支持
jsonb 数组Json[]暂不支持不适用Json[] 在 PostgreSQL 中支持，但 当前在 CockroachDB 中不支持

其他限制​

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

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

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

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

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

从 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")
}

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

开始使用 Prisma ORM 和 CockroachDB 最快的方式是参考我们的入门文档

这些教程将引导您完成连接到 CockroachDB、迁移您的 schema 以及使用 Prisma Client 的过程。

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