跳到主要内容

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 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 内置的 sequence() 函数用于 CockroachDB。有关 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 之间的差异

问题区域注释
默认情况下，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 中的类型映射限制​

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

CockroachDB (类型 | 别名)Prisma ORM支持原生数据库类型属性注释
moneyDecimal尚未@db.MoneyPostgreSQL 中支持，但 目前在 CockroachDB 中尚不支持
xmlString尚未@db.XmlPostgreSQL 中支持，但 目前在 CockroachDB 中尚不支持
jsonb 数组Json[]尚未不适用PostgreSQL 中支持 Json[]，但 目前在 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 类型客户端目前 CockroachDB 不支持 推送到 Enum 类型（例如 data: { enum { push: "A" }, }）
不支持在没有全文索引的 String 字段上搜索客户端目前 CockroachDB 不支持 在没有全文索引的 String 字段上搜索（例如 where: { text: { search: "cat & dog", }, },）
不支持整数除法客户端目前 CockroachDB 不支持 整数除法（例如 data: { int: { divide: 10, }, }）
对 Json 字段的过滤有限客户端目前 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")
}

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

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

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

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