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

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は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は、一意の識別子を生成するためにCockroachDBのunique_rowid()関数を使用するautoincrement()属性関数を提供します。例えば、以下の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の相違点を示しています。

問題領域備考
デフォルトでは、CockroachDBではINT型はINT8のエイリアスですが、PostgreSQLではINT4のエイリアスです。これは、Prisma ORMがCockroachDBのINT列をBigIntとしてイントロスペクションするのに対し、PostgreSQLでは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/APostgreSQLではJson[]がサポートされていますが、現在CockroachDBではサポートされていません

その他の制限事項​

以下の表は、CockroachDBとPostgreSQLを比較した場合の、その他の現在既知の制限事項をリストしています。

問題領域備考
インデックス型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のさらに詳しい使用方法​

CockroachDBをPrisma ORMですぐに使い始めるには、入門ドキュメントを参照してください。

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

さらなる参考情報は、CockroachDBコネクタドキュメントで入手できます。

© . All rights reserved.