CockroachDB

本指南討論了使用 Prisma ORM 和 CockroachDB 背後的概念，解釋了 CockroachDB 與其他資料庫提供者之間的共通點與差異，並引導您完成應用程式整合 CockroachDB 的配置過程。

資訊

CockroachDB 連接器在 3.14.0 及更高版本中已正式發布（GA）。它最初在 3.9.0 版本中作為預覽功能（Preview feature）加入並支援內省（Introspection），而對 Prisma Migrate 的支援則在 3.11.0 版本中加入。

什麼是 CockroachDB？

CockroachDB 是一款分散式資料庫，專為可擴展性（scalability）和高可用性（high availability）而設計。其功能包括：

• 與 PostgreSQL 相容： CockroachDB 與 PostgreSQL 相容，可與現有產品的大型生態系統進行互通。
• 內建擴展： CockroachDB 具有自動複製、故障轉移和修復功能，讓您的應用程式能輕鬆進行水平擴展。

與其他資料庫提供者的共通點

CockroachDB 在很大程度上與 PostgreSQL 相容，且大多數情況下能以相同的方式搭配 Prisma ORM 使用。您仍然可以：

• 使用 Prisma Schema 語言建立您的資料庫模型
• 使用 Prisma ORM 的 cockroachdb 資料庫連接器連接到您的資料庫
• 對於現有專案，如果您已經有 CockroachDB 資料庫，可以使用內省 (Introspection)
• 使用 Prisma Migrate 將您的資料庫結構描述（schema）遷移至新版本
• 在您的應用程式中使用 Prisma Client，根據您的 Prisma Schema 以類型安全（type safe）的方式查詢資料庫

需考慮的差異

使用 Prisma ORM 的 cockroachdb 連接器時，需要注意一些 CockroachDB 特有的差異：

• Cockroach 特有的原生類型： Prisma ORM 的 cockroachdb 資料庫連接器支援 CockroachDB 的原生資料類型。欲了解更多資訊，請參閱如何使用 CockroachDB 的原生類型。

• 建立資料庫鍵（keys）： Prisma ORM 允許您使用 autoincrement() 函數為每條記錄生成唯一識別碼。欲了解更多資訊，請參閱如何在 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 關於選擇索引鍵（index keys）的部落格文章。

相反地，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 配置在 prisma.config.ts 中：

prisma.config.ts

import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL'),
  },
})

資訊

使用 Prisma CLI 命令時，環境變數不會自動載入。您需要使用像 dotenv 這樣的套件從 .env 檔案載入環境變數，或確保您的環境變數已在您的 shell 中設定。

傳遞給 datasource 區塊的欄位有：

• provider：指定 cockroachdb 資料來源連接器。
• url 欄位在 prisma.config.ts 中配置，並指定 CockroachDB 資料庫伺服器的連接 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。	結構描述 (Schema)	欲了解更多關於 INT 類型的資訊，請參閱 CockroachDB 文件
在欄位上使用 @default(autoincrement()) 時，CockroachDB 會自動為資料列 ID 生成 64 位元整數。這些整數會遞增但非連續。這與 PostgreSQL 不同，在 PostgreSQL 中生成的資料列 ID 是連續的且從 1 開始。	結構描述 (Schema)	欲了解更多關於生成值的資訊，請參閱 CockroachDB 文件
@default(autoincrement()) 屬性只能與 BigInt 欄位類型搭配使用。	結構描述 (Schema)	欲了解更多關於生成值的資訊，請參閱 CockroachDB 文件

CockroachDB 中的類型映射限制

CockroachDB 連接器將 Prisma ORM 資料模型中的純量類型 (scalar types) 映射到原生欄位類型。這些原生類型大多與 PostgreSQL 相同 —— 詳情請參閱從 Prisma ORM 到 CockroachDB 的原生類型映射。然而，仍存在一些限制：

CockroachDB (類型 | 別名)	Prisma ORM	支援	原生資料庫類型屬性	註解
money	Decimal	尚未支援	@db.Money	PostgreSQL 支援，但目前 CockroachDB 尚未支援
xml	String	尚未支援	@db.Xml	PostgreSQL 支援，但目前 CockroachDB 尚未支援
jsonb 陣列	Json[]	尚未支援	不適用	Json[] 在 PostgreSQL 中支援，但目前 CockroachDB 尚未支援

其他限制

下表列出了 CockroachDB 相對於 PostgreSQL 的其他已知限制：

議題	領域	註解
不支援 Hash、Gist、SpGist 或 Brin 索引類型。	結構描述 (Schema)	在 PostgreSQL 中，Prisma ORM 允許配置索引以使用不同的索引存取方法。CockroachDB 目前僅支援 BTree 和 Gin。
不支援推送到 Enum 類型	Client	推送到 Enum 類型（例如 data: { enum { push: "A" }, }）目前在 CockroachDB 中不支援
不支援在沒有全文索引的情況下搜尋 String 欄位	Client	在沒有全文索引的情況下搜尋 String 欄位（例如 where: { text: { search: "cat & dog", }, },）目前在 CockroachDB 中不支援
不支援整數除法	Client	整數除法（例如 data: { int: { divide: 10, }, }）目前在 CockroachDB 中不支援
Json 欄位的篩選限制	Client	目前 CockroachDB 對 Json 欄位僅支援 equals 和 not 篩選

CockroachDB 與 Prisma schema 之間的類型映射

CockroachDB 連接器將 Prisma ORM 資料模型中的純量類型 (scalar types) 映射到原生欄位類型如下：

或者，請參閱Prisma schema 參考文件中按 Prisma ORM 類型組織的類型映射。

從 Prisma ORM 到 CockroachDB 的原生類型映射

Prisma ORM	CockroachDB
String	STRING
Boolean	BOOL
Int	INT4
BigInt	INT8
Float	FLOAT8
Decimal	DECIMAL(65,30)
DateTime	TIMESTAMP(3)
Json	JSONB
Bytes	BYTES

內省時從 CockroachDB 到 Prisma ORM 類型的映射

內省 CockroachDB 資料庫時，資料庫類型會根據下表映射到 Prisma ORM：

CockroachDB (類型 | 別名)	Prisma ORM	支援	原生資料庫類型屬性	註解
INT | BIGINT, INTEGER	BigInt	✔️	@db.Int8
BOOL | BOOLEAN	Bool	✔️	@db.Bool*
TIMESTAMP | TIMESTAMP WITHOUT TIME ZONE	DateTime	✔️	@db.Timestamp(x)
TIMESTAMPTZ | TIMESTAMP WITH TIME ZONE	DateTime	✔️	@db.Timestamptz(x)
TIME | TIME WITHOUT TIME ZONE	DateTime	✔️	@db.Time(x)
TIMETZ | TIME WITH TIME ZONE	DateTime	✔️	@db.Timetz(x)
DECIMAL(p,s) | NUMERIC(p,s), DEC(p,s)	Decimal	✔️	@db.Decimal(x, y)
REAL | FLOAT4, FLOAT	Float	✔️	@db.Float4
DOUBLE PRECISION | FLOAT8	Float	✔️	@db.Float8
INT2 | SMALLINT	Int	✔️	@db.Int2
INT4	Int	✔️	@db.Int4
CHAR(n) | CHARACTER(n)	String	✔️	@db.Char(x)
"char"	String	✔️	@db.CatalogSingleChar	CockroachDB 目錄表 (catalog tables) 的內部類型，不供終端使用者使用。
STRING | TEXT, VARCHAR	String	✔️	@db.String
DATE	DateTime	✔️	@db.Date
ENUM	enum	✔️	不適用
INET	String	✔️	@db.Inet
BIT(n)	String	✔️	@Bit(x)
VARBIT(n) | BIT VARYING(n)	String	✔️	@VarBit
OID	Int	✔️	@db.Oid
UUID	String	✔️	@db.Uuid
JSONB | JSON	Json	✔️	@db.JsonB
陣列類型 (Array types)	[]	✔️

內省 (Introspection) 會將尚未支援的原生資料庫類型添加為 Unsupported 欄位

schema.prisma

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

更多關於搭配 Prisma ORM 使用 CockroachDB 的資訊

開始搭配 Prisma ORM 使用 CockroachDB 的最快方法是參考我們的「入門指南 (Getting Started)」文件：

• 從頭開始
• 加入現有專案

這些教學將帶領您完成連接 CockroachDB、遷移結構描述 (schema) 以及使用 Prisma Client 的過程。

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