跳到主要內容

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 聯結器文件中找到。

© . This site is unofficial and not affiliated with Prisma Data, Inc.