跳至主要内容

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 模式语言 对您的数据库进行建模。
  • 使用 Prisma ORM 的 cockroachdb 数据库连接器 连接到您的数据库。
  • 如果您的项目已拥有 CockroachDB 数据库，则可以使用 内省。
  • 使用 Prisma Migrate 将您的数据库模式迁移到新版本。
  • 在您的应用程序中使用 Prisma Client，根据您的 Prisma 模式以类型安全的方式查询您的数据库。

需要考虑的差异​

在使用 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 模式中将有一个新的 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
}

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

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

示例​

要连接到 CockroachDB 数据库服务器，您需要在 Prisma 模式 中配置一个 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。模式有关 INT 类型的更多信息，请参阅CockroachDB 文档
在字段上使用 @default(autoincrement()) 时，CockroachDB 将自动为行 ID 生成 64 位整数。这些整数将递增，但不是连续的。这与 PostgreSQL 形成对比，在 PostgreSQL 中，生成的行 ID 是连续的，从 1 开始。模式有关生成值的更多信息，请参阅CockroachDB 文档
@default(autoincrement()) 属性只能与 BigInt 字段类型一起使用。模式有关生成值的更多信息，请参阅CockroachDB 文档

CockroachDB 中的类型映射限制​

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

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

其他限制​

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

问题领域说明
主键命名为 primary 而不是 TABLE_pkey（Prisma ORM 的默认值）。内省这意味着它们被解读为 @id(map: "primary")。这将在CockroachDB 22.1 中修复。
外键命名为 fk_COLUMN_ref_TABLE 而不是 TABLE_COLUMN_fkey（Prisma ORM 的默认值）。内省这意味着它们被解读为 @relation([...], map: "fk_COLUMN_ref_TABLE")。这将在CockroachDB 22.1 中修复。
不支持 Hash、Gist、SpGist 或 Brin 索引类型。模式在 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 模式之间的类型映射​

CockroachDB 连接器将 Prisma ORM 数据模型 中的标量类型映射到以下原生列类型。

或者，请参阅Prisma 模式参考，了解按 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✔️N/A
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、迁移模式以及使用 Prisma Client 的过程。

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