メインコンテンツにスキップ

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 は PostgreSQL の VARCHAR の代わりに STRING データ型を使用します。

このデモンストレーションとして、次の 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) が注釈されていることに注意してください。これは、注釈が @db.VarChar(200) になる PostgreSQL とは異なります。

型のマッピングの完全なリストについては、コネクタドキュメント を参照してください。

CockroachDB でのデータベースキーの使用方法​

CockroachDB のような分散データベースでレコードの一意の識別子を生成する場合、連番 ID の使用は避けるのが最適です。詳細については、CockroachDB の インデックスキーの選択に関するブログ投稿 を参照してください。

代わりに、Prisma ORM は autoincrement() 属性関数を提供します。これは、一意の識別子を生成するために CockroachDB の unique_rowid() 関数 を使用します。たとえば、次の User モデルには、autoincrement() 関数を使用して生成された id プライマリキーがあります。

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

既存のデータベースとの互換性のために、固定された連番の整数キー値を生成する必要がある場合があります。このような場合は、CockroachDB 用の Prisma ORM の組み込み sequence() 関数を使用できます。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 データベースに接続する場合は、postgresql の代わりに cockroachdb コネクタを使用する必要があります。

接続の詳細​

CockroachDB は、接続 URL に PostgreSQL 形式を使用します。この形式の詳細と、オプションの引数については、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 ビット整数を自動的に生成します。これらの整数は増加しますが、連続ではありません。これは、生成された行 ID が連続しており、1 から始まる PostgreSQL とは対照的です。スキーマ生成された値の詳細については、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[]まだN/AJson[] は PostgreSQL でサポートされていますが、CockroachDB では現在サポートされていません

その他の制限事項​

次の表に、PostgreSQL と比較した CockroachDB のその他の既知の制限事項を示します。

問題領域注
プライマリキーは、Prisma ORM のデフォルトである TABLE_pkey ではなく、primary という名前が付けられます。イントロスペクションこれは、それらが @id(map: "primary") としてイントロスペクトされることを意味します。これは CockroachDB 22.1 で修正される予定です。
外部キーは、Prisma ORM のデフォルトである TABLE_COLUMN_fkey ではなく、fk_COLUMN_ref_TABLE という名前が付けられます。イントロスペクションこれは、それらが @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 から 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
配列型[]✔️

イントロスペクション は、まだサポートされていないネイティブデータベース型を Unsupported フィールドとして追加します。

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

Prisma ORM での CockroachDB の使用に関する詳細​

Prisma ORM で CockroachDB の使用を開始する最も速い方法は、はじめにドキュメントを参照することです。

これらのチュートリアルでは、CockroachDB への接続、スキーマの移行、および Prisma Client の使用のプロセスについて説明します。

詳細なリファレンス情報は、CockroachDB コネクタドキュメント で入手できます。