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

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以降でのイントロスペクションの結果

schema.prisma
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フィールドに追加されます。

schema.prisma
model Post {
id String @id
published Boolean @default(false)
}

Prismaモデルに@default属性を手動で追加する

Prismaモデルに@default属性を追加できます。

schema.prisma
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以降でのイントロスペクションの結果

schema.prisma
model Post {
id String @id
}

データベースにCUIDの挙動を示すものがないため、Prisma ORMのイントロスペクションはそれを認識しません。

回避策

回避策として、Prismaモデルに@default(cuid())属性を手動で追加できます。

schema.prisma
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以降のバージョンでのイントロスペクションの結果

schema.prisma
model Post {
id String @id
createdAt DateTime
}

回避策

データベース列にDEFAULT CURRENT_TIMESTAMPを手動で追加する

以下のように列を変更してDEFAULT制約を追加できます。

ALTER TABLE "Post"
ALTER COLUMN "createdAt" SET DEFAULT CURRENT_TIMESTAMP;

この調整後、データベースを再イントロスペクトすると、@default属性がcreatedAtフィールドに追加されます。

schema.prisma
model Post {
id String
createdAt DateTime @default(now())
}

Prismaモデルに@default(now())属性を手動で追加する

回避策として、Prismaモデルに@default(now())属性を手動で追加できます。

schema.prisma
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以降のバージョンでのイントロスペクションの結果

schema.prisma
model Post {
id String @id
updatedAt DateTime
}

回避策

Prismaモデルに@updatedAt属性を手動で追加する

回避策として、Prismaモデルに@updatedAt属性を手動で追加できます。

schema.prisma
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以降のバージョンでのイントロスペクションの結果

schema.prisma
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リレーションが適切に認識されます。

schema.prisma
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以降のバージョンでのイントロスペクションの結果

schema.prisma
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対多リレーションと互換性のある構造にデータを移行できます。

  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");
  2. _PostToUserリレーションテーブルからすべての行を読み取り、各行に対してSQLクエリを記述します。
    1. Aの値を見て、対応するPostレコードを見つけます。
    2. Bの値をそのPostレコードのauthorIdの値として挿入します。
    UPDATE "Post" post
    SET "authorId" = post_to_user."B"
    FROM "_PostToUser" post_to_user
    WHERE post_to_user."A" = post."id";
  3. _PostToUserリレーションテーブルを削除します。
    DROP TABLE "_PostToUser";

その後、データベースをイントロスペクトすると、リレーションは1対多として認識されます。

schema.prisma
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以降のバージョンでのイントロスペクションの結果

schema.prisma
model User {
id String @id
jsonData String?
}

回避策

手動で列の型をJSONに変更できます。

ALTER TABLE "User" ALTER COLUMN "jsonData" TYPE JSON  USING "jsonData"::json;

この調整後、データベースを再イントロスペクトすると、フィールドはJsonとして認識されるようになります。

schema.prisma
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以降のバージョンでのイントロスペクションの結果

schema.prisma
model User {
id String @id
role String?
}

回避策

role列を目的の値を持つenumに手動で変更できます。

  1. Prisma 1データモデルで定義したenumをミラーリングするenumをデータベースに作成します。
    CREATE TYPE "Role" AS ENUM ('CUSTOMER', 'ADMIN');
  2. 型をTEXTから新しいenumに変更します。
    ALTER TABLE "User" ALTER COLUMN "role" TYPE "Role"
    USING "role"::text::"Role";

イントロスペクション後、型はenumとして適切に認識されるようになります。

schema.prisma
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以降のバージョンでのイントロスペクションの結果

schema.prisma
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のイントロスペクションの結果

schema.prisma
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 }
]
}

リストからブール値のみにアクセスするには、次のようにusercoinflipsmapできます。

const currentCoinflips = user!.coinflips.map((cf) => cf.value)

: 上記の感嘆符は、user値を強制アンラップしていることを意味します。これは、前のクエリから返されたusernullである可能性があるため必要です。

map呼び出し後のcurrentCoinflipsの値は次のとおりです。

[false, true, false, true, true, false]

回避策

以下の回避策はPostgreSQLユーザーのみが利用可能です!

スカラーリスト(つまり、配列)がネイティブのPostgreSQL機能として利用可能であるため、Prismaスキーマでcoinflips: Boolean[]と同じ表記法を引き続き使用できます。

ただし、そのためには、基盤となるデータ(User_coinflipsテーブルから)をPostgreSQL配列に手動で移行する必要があります。その方法は次のとおりです。

  1. Userテーブルに新しいcoinflips列を追加します。
    ALTER TABLE "User" ADD COLUMN coinflips BOOLEAN[];
  2. "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";
  3. クリーンアップのために、User_coinflipsテーブルを削除できます。
    DROP TABLE "User_coinflips";

これでデータベースをイントロスペクトでき、新しいPrismaスキーマではcoinflipsフィールドが配列として表現されます。

schema.prisma
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 ]
}
© . All rights reserved.