跳至主要内容

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 特定的差异

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

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

为了与现有数据库兼容，您有时可能仍然需要生成固定顺序的整数键值。在这种情况下，您可以使用 Prisma ORM 内置的 sequence() 函数用于 CockroachDB。有关 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 中，生成的 row ID 是连续的，从 1 开始。架构有关生成值的更多信息，请参见 CockroachDB 文档
@default(autoincrement()) 属性只能与 BigInt 字段类型一起使用。架构有关生成值的更多信息，请参见 CockroachDB 文档

CockroachDB 中的类型映射限制​

CockroachDB 连接器将 Prisma ORM 标量类型 从 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 中目前不支持

其他限制​

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

问题领域说明
主键命名为 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 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
数组类型[]✔️

内省 添加尚未支持的本机数据库类型，作为 不支持 字段

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

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

使用 Prisma ORM 与 CockroachDB 的最快方法是参考我们的入门文档

这些教程将指导您完成连接到 CockroachDB、迁移架构和使用 Prisma 客户端的过程。

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