跳到主要內容

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 內建的 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 而不是 Prisma ORM 預設的 TABLE_pkey。內省這表示它們會被內省為 @id(map: "primary")。這將在 CockroachDB 22.1 中修正。
外鍵命名為 fk_COLUMN_ref_TABLE 而不是 Prisma ORM 預設的 TABLE_COLUMN_fkey。內省這表示它們會被內省為 @relation([...], map: "fk_COLUMN_ref_TABLE")。這將在 CockroachDB 22.1 中修正
不支援索引類型 Hash、Gist、SpGist 或 Brin。結構描述在 PostgreSQL 中，Prisma ORM 允許配置索引以使用不同的索引存取方法。CockroachDB 目前僅支援 BTree 和 Gin。
不支援推送到 Enum 類型Client目前 CockroachDB 中不支援 推送到 Enum 類型（例如 data: { enum { push: "A" }, }）
不支援在沒有全文索引的 String 欄位上搜尋Client目前 CockroachDB 中不支援 在沒有全文索引的 String 欄位上搜尋（例如 where: { text: { search: "cat & dog", }, },）
不支援整數除法Client目前 CockroachDB 中不支援 整數除法（例如 data: { int: { divide: 10, }, }）
對 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、遷移您的結構描述以及使用 Prisma Client 的過程。

更多參考資訊可在 CockroachDB 連接器文件 中找到。