PostgreSQLにおけるスキーマの非互換性
概要
このページの各セクションでは、Prisma 1からPrisma ORM 2.x以降にアップグレードする際の潜在的な問題について説明し、利用可能な回避策を解説します。
デフォルト値がデータベースに反映されない
問題
Prisma 1のデータモデルに@default
ディレクティブを追加すると、このフィールドのデフォルト値はPrisma 1サーバーによってランタイム時に生成されます。データベースの列にはDEFAULT
制約が追加されません。この制約がデータベース自体に反映されないため、Prisma ORM 2.x以降のイントロスペクションでは認識できません。
例
Prisma 1データモデル
type Post {
id: ID! @id
published: Boolean @default(value: false)
}
Prisma 1生成SQLマイグレーション
CREATE TABLE "Post" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
published BOOLEAN NOT NULL
);
Prisma ORMバージョン2.x以降でのイントロスペクションの結果
model Post {
id String @id
published Boolean
}
Prisma 1データモデルをprisma deploy
でデータベースにマッピングする際にDEFAULT
制約がデータベースに追加されていないため、Prisma ORM v2(およびそれ以降のバージョン)はイントロスペクション中にそれを認識しません。
回避策
データベース列にDEFAULT
制約を手動で追加する
以下のように列を変更してDEFAULT
制約を追加できます。
ALTER TABLE "Post"
ALTER COLUMN published SET DEFAULT false;
この調整後、データベースを再イントロスペクトすると、@default
属性がpublished
フィールドに追加されます。
model Post {
id String @id
published Boolean @default(false)
}
Prismaモデルに@default
属性を手動で追加する
Prismaモデルに@default
属性を追加できます。
model Post {
id String
published Boolean @default(false)
}
Prismaスキーマに@default
属性が設定されており、prisma generate
を実行すると、生成されたPrisma Clientコードは、ランタイム時に指定されたデフォルト値を生成します(Prisma 1サーバーがPrisma 1で行ったことと同様)。
生成されたCUIDがID値としてデータベースに反映されない
問題
Prisma 1は、@id
ディレクティブで注釈が付けられたID
フィールドにCUIDとしてID値を自動生成します。これらのCUIDはPrisma 1サーバーによってランタイム時に生成されます。この挙動がデータベース自体に反映されないため、Prisma ORM 2.x以降のイントロスペクションでは認識できません。
例
Prisma 1データモデル
type Post {
id: ID! @id
}
Prisma 1生成SQLマイグレーション
CREATE TABLE "Post" (
id VARCHAR(25) PRIMARY KEY NOT NULL
);
Prisma ORMバージョン2.x以降でのイントロスペクションの結果
model Post {
id String @id
}
データベースにCUIDの挙動を示すものがないため、Prisma ORMのイントロスペクションはそれを認識しません。
回避策
回避策として、Prismaモデルに@default(cuid())
属性を手動で追加できます。
model Post {
id String @id @default(cuid())
}
Prismaスキーマに@default
属性が設定されており、prisma generate
を実行すると、生成されたPrisma Clientコードは、ランタイム時に指定されたデフォルト値を生成します(Prisma 1サーバーがPrisma 1で行ったことと同様)。
イントロスペクションは属性を削除するため、各イントロスペクション後に属性を再追加する必要があることに注意してください(以前のバージョンのPrismaスキーマは上書きされます)!
@createdAt
がデータベースに反映されない
問題
Prisma 1は、@createdAt
ディレクティブで注釈が付けられたDateTime
フィールドの値を自動生成します。これらの値はPrisma 1サーバーによってランタイム時に生成されます。この挙動がデータベース自体に反映されないため、Prisma ORM 2.x以降のイントロスペクションでは認識できません。
例
Prisma 1データモデル
type Post {
id: ID! @id
createdAt: DateTime! @createdAt
}
Prisma 1生成SQLマイグレーション
CREATE TABLE "Post" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
"createdAt" TIMESTAMP NOT NULL
);
Prisma ORM 2.x以降のバージョンでのイントロスペクションの結果
model Post {
id String @id
createdAt DateTime
}
回避策
データベース列にDEFAULT CURRENT_TIMESTAMP
を手動で追加する
以下のように列を変更してDEFAULT
制約を追加できます。
ALTER TABLE "Post"
ALTER COLUMN "createdAt" SET DEFAULT CURRENT_TIMESTAMP;
この調整後、データベースを再イントロスペクトすると、@default
属性がcreatedAt
フィールドに追加されます。
model Post {
id String
createdAt DateTime @default(now())
}
Prismaモデルに@default(now())
属性を手動で追加する
回避策として、Prismaモデルに@default(now())
属性を手動で追加できます。
model Post {
id String @id
createdAt DateTime @default(now())
}
Prismaスキーマに@default
属性が設定されており、prisma generate
を実行すると、生成されたPrisma Clientコードは、ランタイム時に指定されたデフォルト値を生成します(Prisma 1サーバーがPrisma 1で行ったことと同様)。
イントロスペクションは属性を削除するため、各イントロスペクション後に属性を再追加する必要があることに注意してください(以前のバージョンのPrismaスキーマは上書きされます)!
@updatedAt
がデータベースに反映されない
問題
Prisma 1は、@updatedAt
ディレクティブで注釈が付けられたDateTime
フィールドの値を自動生成します。これらの値はPrisma 1サーバーによってランタイム時に生成されます。この挙動がデータベース自体に反映されないため、Prisma ORM 2.x以降のイントロスペクションでは認識できません。
例
Prisma 1データモデル
type Post {
id: ID! @id
updatedAt: DateTime! @updatedAt
}
Prisma 1生成SQLマイグレーション
CREATE TABLE "Post" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
updatedAt TIMESTAMP
);
Prisma ORM 2.x以降のバージョンでのイントロスペクションの結果
model Post {
id String @id
updatedAt DateTime
}
回避策
Prismaモデルに@updatedAt
属性を手動で追加する
回避策として、Prismaモデルに@updatedAt
属性を手動で追加できます。
model Post {
id String @id
updatedAt DateTime @updatedAt
}
Prismaスキーマに@updatedAt
属性が設定されており、prisma generate
を実行すると、既存のレコードが更新されたときに結果のPrisma Clientコードがこの列の値を自動的に生成します(Prisma 1サーバーがPrisma 1で行ったことと同様)。
イントロスペクションは属性を削除するため、各イントロスペクション後に属性を再追加する必要があることに注意してください(以前のバージョンのPrismaスキーマは上書きされます)!
インライン1対1リレーションが1対多として認識される(UNIQUE
制約の欠落)
問題
Prisma ORM v1.31で導入されたデータモデル v1.1では、1対1リレーションをインラインで宣言できます。その場合、リレーションはリレーションテーブルを介してではなく、関連する2つのテーブルのいずれかの単一の外部キーを介して維持されます。
このアプローチを使用すると、Prisma ORMは外部キー列にUNIQUE
制約を追加しません。これは、Prisma ORMバージョン2.x以降でのイントロスペクション後、この以前の1対1リレーションがPrismaスキーマに1対多リレーションとして追加されることを意味します。
例
Prisma ORMデータモデル v1.1(Prisma ORM v1.31から利用可能)
type User {
id: ID! @id
profile: Profile @relation(link: INLINE)
}
type Profile {
id: ID! @id
user: User
}
この場合、@relation
ディレクティブを省略しても同じ挙動になります。なぜなら、1対1リレーションではlink: INLINE
がデフォルトだからです。
Prisma 1生成SQLマイグレーション
CREATE TABLE "User" (
id VARCHAR(25) PRIMARY KEY NOT NULL
);
CREATE TABLE "Profile" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
"user" VARCHAR(25),
FOREIGN KEY ("user") REFERENCES "User"(id)
);
Prisma ORM 2.x以降のバージョンでのイントロスペクションの結果
model User {
id String @id
Profile Profile[]
}
model Profile {
id String @id
user String?
User User? @relation(fields: [user], references: [id])
}
user
列(このリレーションの外部キーを表す)にUNIQUE
制約が定義されていないため、Prisma ORMのイントロスペクションはリレーションを1対多として認識します。
回避策
外部キー列にUNIQUE
制約を手動で追加する
以下のように外部キー列を変更してUNIQUE
制約を追加できます。
ALTER TABLE "Profile"
ADD CONSTRAINT userId_unique UNIQUE ("user");
この調整後、データベースを再イントロスペクトすると、1対1リレーションが適切に認識されます。
model User {
id String @id
Profile Profile?
}
model Profile {
id String @id
user String? @unique
User User? @relation(fields: [user], references: [id])
}
すべての非インラインリレーションがm対nとして認識される
問題
Prisma 1はほとんどの場合、リレーションをリレーションテーブルとして表現します。
- Prisma 1のデータモデル v1.0におけるすべてのリレーションはリレーションテーブルとして表現されます。
- データモデル v1.1では、すべてのm対nリレーション、および
link: TABLE
として宣言された1対1および1対多リレーションはリレーションテーブルとして表現されます。
この表現のため、Prisma ORMバージョン2.x以降でのイントロスペクションでは、Prisma 1で1対1または1対多として宣言されたものであっても、これらのリレーションはすべてm対nリレーションとして認識されます。
例
Prisma 1データモデル
type User {
id: ID! @id
posts: [Post!]!
}
type Post {
id: ID! @id
author: User! @relation(link: TABLE)
}
Prisma 1生成SQLマイグレーション
CREATE TABLE "User" (
id VARCHAR(25) PRIMARY KEY NOT NULL
);
CREATE TABLE "Post" (
id VARCHAR(25) PRIMARY KEY NOT NULL
);
CREATE TABLE "_PostToUser" (
"A" VARCHAR(25) NOT NULL REFERENCES "Post"(id) ON DELETE CASCADE,
"B" VARCHAR(25) NOT NULL REFERENCES "User"(id) ON DELETE CASCADE
);
CREATE UNIQUE INDEX "_PostToUser_AB_unique" ON "_PostToUser"("A" text_ops,"B" text_ops);
CREATE INDEX "_PostToUser_B" ON "_PostToUser"("B" text_ops);
Prisma ORM 2.x以降のバージョンでのイントロスペクションの結果
model User {
id String @id
Post Post[] @relation(references: [id])
}
model Post {
id String @id
User User[] @relation(references: [id])
}
Prisma 1によって作成されたリレーションテーブルがPrisma ORMバージョン2.x以降のリレーションテーブルの規約と同じものを使用しているため、このリレーションは現在m対nリレーションとして認識されます。
回避策
回避策として、Prisma ORMの1対多リレーションと互換性のある構造にデータを移行できます。
Post
テーブルに新しい列authorId
を作成します。この列は、User
テーブルのid
フィールドを参照する外部キーである必要があります。ALTER TABLE "Post" ADD COLUMN "authorId" VARCHAR(25);
ALTER TABLE "Post"
ADD CONSTRAINT fk_author
FOREIGN KEY ("authorId")
REFERENCES "User"("id");_PostToUser
リレーションテーブルからすべての行を読み取り、各行に対してSQLクエリを記述します。- 列
A
の値を見て、対応するPost
レコードを見つけます。 - 列
B
の値をそのPost
レコードのauthorId
の値として挿入します。
UPDATE "Post" post
SET "authorId" = post_to_user."B"
FROM "_PostToUser" post_to_user
WHERE post_to_user."A" = post."id";- 列
_PostToUser
リレーションテーブルを削除します。DROP TABLE "_PostToUser";
その後、データベースをイントロスペクトすると、リレーションは1対多として認識されます。
model User {
id String @id
Post Post[]
}
model Post {
id String @id
User User @relation(fields: [authorId], references: [id])
authorId String
}
Json
型がデータベースでTEXT
として表現される
問題
Prisma 1はデータモデルでJson
データ型をサポートしています。しかし、基盤となるデータベースでは、Json
型のフィールドは実際には基盤となるデータベースのTEXT
データ型を使用してプレーンな文字列として格納されます。格納されたJSONデータの解析と検証はすべてPrisma 1サーバーによってランタイム時に行われます。
例
Prisma 1データモデル
type User {
id: ID! @id
jsonData: Json
}
Prisma 1生成SQLマイグレーション
CREATE TABLE "User" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
jsonData TEXT
);
Prisma ORM 2.x以降のバージョンでのイントロスペクションの結果
model User {
id String @id
jsonData String?
}
回避策
手動で列の型をJSON
に変更できます。
ALTER TABLE "User" ALTER COLUMN "jsonData" TYPE JSON USING "jsonData"::json;
この調整後、データベースを再イントロスペクトすると、フィールドはJson
として認識されるようになります。
model User {
id String @id
jsonData Json?
}
EnumがデータベースでTEXT
として表現される
問題
Prisma 1はデータモデルでenum
データ型をサポートしています。しかし、基盤となるデータベースでは、enum
として宣言された型は実際には基盤となるデータベースのTEXT
データ型を使用してプレーンな文字列として格納されます。格納されたenum
データの検証はすべてPrisma 1サーバーによってランタイム時に行われます。
例
Prisma 1データモデル
type User {
id: ID! @id
role: Role
}
enum Role {
ADMIN
CUSTOMER
}
Prisma 1生成SQLマイグレーション
CREATE TABLE "User" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
role TEXT
);
Prisma ORM 2.x以降のバージョンでのイントロスペクションの結果
model User {
id String @id
role String?
}
回避策
role
列を目的の値を持つenumに手動で変更できます。
- Prisma 1データモデルで定義した
enum
をミラーリングするenum
をデータベースに作成します。CREATE TYPE "Role" AS ENUM ('CUSTOMER', 'ADMIN');
- 型を
TEXT
から新しいenum
に変更します。ALTER TABLE "User" ALTER COLUMN "role" TYPE "Role"
USING "role"::text::"Role";
イントロスペクション後、型はenumとして適切に認識されるようになります。
model User {
id String @id
role Role?
}
enum Role {
ADMIN
CUSTOMER
}
CUIDの長さの不一致
問題
Prisma 1は、すべてのデータベースレコードのID値としてCUIDを使用します。基盤となるデータベースでは、これらのIDは最大25文字(VARCHAR(25)
として)の文字列として表現されます。しかし、Prisma ORM 2.x(またはそれ以降のバージョン)のスキーマで@default(cuid())
を使用してデフォルトのCUIDを設定する場合、生成されるID値が25文字の制限を超える可能性があります(最大長は30文字になる可能性があります)。したがって、Prisma ORM 2.x(またはそれ以降のバージョン)に対応するために、列の型をVARCHAR(30)
に調整する必要があります。
例
Prisma 1データモデル
type User {
id: ID! @id
}
Prisma 1生成SQLマイグレーション
CREATE TABLE "User" (
id VARCHAR(25) PRIMARY KEY NOT NULL
);
Prisma ORM 2.x以降のバージョンでのイントロスペクションの結果
model User {
id String @id
}
回避策
VARCHAR(25)
列をVARCHAR(30)
に手動で変更できます。
ALTER TABLE "User" ALTER COLUMN "id" SET DATA TYPE character varying(30);
注: Upgrade CLIでこの問題を修正しても、基盤となるデータベースの列タイプを変更した後も、生成されたSQLステートメントがUpgrade CLIに表示され続けます。これは現在のUpgrade CLIの制限です。
スカラーリスト(配列)が追加テーブルで維持される
問題
Prisma 1では、モデルでスカラー型のリストを定義できます。内部的には、これはリストの値を追跡する追加のテーブルで実装されています。
隠れたパフォーマンスコストを伴う追加テーブルのアプローチを排除するため、Prisma ORM 2.x以降のバージョンでは、使用するデータベースがネイティブにサポートしている場合にのみスカラーリストをサポートします。現在、PostgreSQLのみがスカラーリスト(配列)をネイティブにサポートしています。
したがって、PostgreSQLを使用している場合、Prisma ORM 2.x以降のバージョンでもスカラーリストを引き続き使用できますが、Prisma 1からの追加テーブルから実際のPostgreSQL配列にデータを転送するためにデータ移行を実行する必要があります。
例
Prisma 1データモデル
type User {
id: ID! @id
coinflips: [Boolean!]! @scalarList(strategy: RELATION)
}
Prisma 1生成SQLマイグレーション
CREATE TABLE "User" (
id VARCHAR(25) PRIMARY KEY NOT NULL
);
CREATE TABLE "User_coinflips" (
"nodeId" VARCHAR(25) REFERENCES "User"(id),
position INTEGER,
value BOOLEAN NOT NULL,
CONSTRAINT "User_coinflips_pkey" PRIMARY KEY ("nodeId", position)
);
CREATE UNIQUE INDEX "User_coinflips_pkey" ON "User_coinflips"("nodeId" text_ops,position int4_ops);
Prisma ORM 2のイントロスペクションの結果
model User {
id String @id
User_coinflips User_coinflips[]
}
model User_coinflips {
nodeId String
position Int
value Boolean
User User @relation(fields: [nodeId], references: [id])
@@id([nodeId, position])
}
これでPrisma Clientを生成でき、追加テーブルを介してスカラーリストのデータにアクセスできることに注意してください。PostgreSQLユーザーは、代わりにデータをネイティブのPostgreSQL配列に移行し、スカラーリスト用のより洗練されたPrisma Client APIの恩恵を受け続けることができます(詳細については以下のセクションを参照)。
Prisma Client API呼び出しの例を展開
coinflips
データにアクセスするには、常にクエリにinclude
する必要があります。
const user = await prisma.user.findUnique({
where: { id: 1 },
include: {
coinflips: {
orderBy: { position: 'asc' },
},
},
})
注: リストの順序を維持するには、
orderBy
が重要です。
これがクエリの結果です。
{
id: 1,
name: 'Alice',
coinflips: [
{ id: 1, position: 1000, value: false },
{ id: 2, position: 2000, value: true },
{ id: 3, position: 3000, value: false },
{ id: 4, position: 4000, value: true },
{ id: 5, position: 5000, value: true },
{ id: 6, position: 6000, value: false }
]
}
リストからブール値のみにアクセスするには、次のようにuser
のcoinflips
をmap
できます。
const currentCoinflips = user!.coinflips.map((cf) => cf.value)
注: 上記の感嘆符は、
user
値を強制アンラップしていることを意味します。これは、前のクエリから返されたuser
がnull
である可能性があるため必要です。
map
呼び出し後のcurrentCoinflips
の値は次のとおりです。
[false, true, false, true, true, false]
回避策
以下の回避策はPostgreSQLユーザーのみが利用可能です!
スカラーリスト(つまり、配列)がネイティブのPostgreSQL機能として利用可能であるため、Prismaスキーマでcoinflips: Boolean[]
と同じ表記法を引き続き使用できます。
ただし、そのためには、基盤となるデータ(User_coinflips
テーブルから)をPostgreSQL配列に手動で移行する必要があります。その方法は次のとおりです。
User
テーブルに新しいcoinflips
列を追加します。ALTER TABLE "User" ADD COLUMN coinflips BOOLEAN[];
"User_coinflips".value
から"User.coinflips"
にデータを移行します。UPDATE "User"
SET coinflips = t.flips
FROM (
SELECT "nodeId", array_agg(VALUE ORDER BY position) AS flips
FROM "User_coinflips"
GROUP BY "nodeId"
) t
where t."nodeId" = "User"."id";- クリーンアップのために、
User_coinflips
テーブルを削除できます。DROP TABLE "User_coinflips";
これでデータベースをイントロスペクトでき、新しいPrismaスキーマではcoinflips
フィールドが配列として表現されます。
model User {
id String @id
coinflips Boolean[]
}
Prisma Clientは以前と同様に引き続き使用できます。
const user = await prisma.user.findUnique({
where: { id: 1 },
})
API呼び出しの結果は次のとおりです。
{
id: 1,
name: 'Alice',
coinflips: [ false, true, false, true, true, false ]
}