Schema incompatibilities
Overview
本页面的每个章节都描述了从 Prisma 1 升级到 Prisma ORM 2.x 及更高版本时可能出现的问题,并解释了可用的解决方法。
Default values aren't represented in database
Problem
当在 Prisma 1 数据模型中添加 @default
指令时,此字段的默认值由 Prisma 1 服务器在运行时生成。数据库列中没有添加 DEFAULT
约束。由于此约束未反映在数据库本身中,因此 Prisma ORM 2.x 及更高版本的内省无法识别它。
Example
Prisma 1 datamodel
type Post {
id: ID! @id
published: Boolean @default(value: false)
}
Prisma 1 generated SQL migration
CREATE TABLE "Post" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
published BOOLEAN NOT NULL
);
Result of introspection in Prisma ORM versions 2.x and later
model Post {
id String @id
published Boolean
}
由于在使用 prisma deploy
将 Prisma 1 数据模型映射到数据库时,DEFAULT
约束未添加到数据库中,因此 Prisma ORM v2(及更高版本)在内省期间无法识别它。
Workarounds
Manually add a DEFAULT
constraint to the database column
您可以修改列以添加 DEFAULT
约束,如下所示
ALTER TABLE "Post"
ALTER COLUMN published SET DEFAULT false;
进行此调整后,您可以重新内省数据库,@default
属性将添加到 published
字段
model Post {
id String @id
published Boolean @default(false)
}
Manually add a @default
attribute to the Prisma model
您可以将 @default
属性添加到 Prisma 模型
model Post {
id String
published Boolean @default(false)
}
如果在 Prisma schema 中设置了 @default
属性,并且您运行 prisma generate
,则生成的 Prisma Client 代码将在运行时生成指定的默认值(类似于 Prisma 1 服务器在 Prisma 1 中所做的)。
Generated CUIDs as ID values aren't represented in database
Problem
当 ID
字段使用 @id
指令注释时,Prisma 1 会自动将 ID 值生成为 CUID。这些 CUID 由 Prisma 1 服务器在运行时生成。由于此行为未反映在数据库本身中,因此 Prisma ORM 2.x 及更高版本中的内省无法识别它。
Example
Prisma 1 datamodel
type Post {
id: ID! @id
}
Prisma 1 generated SQL migration
CREATE TABLE "Post" (
id VARCHAR(25) PRIMARY KEY NOT NULL
);
Result of introspection in Prisma ORM versions 2.x and later
model Post {
id String @id
}
由于数据库中没有 CUID 行为的指示,Prisma ORM 的内省无法识别它。
Workaround
作为一种解决方法,您可以手动将 @default(cuid())
属性添加到 Prisma 模型
model Post {
id String @id @default(cuid())
}
如果在 Prisma schema 中设置了 @default
属性,并且您运行 prisma generate
,则生成的 Prisma Client 代码将在运行时生成指定的默认值(类似于 Prisma 1 服务器在 Prisma 1 中所做的)。
请注意,您必须在每次内省后重新添加该属性,因为内省会将其删除(因为旧版本的 Prisma schema 会被覆盖)!
@createdAt
isn't represented in database
Problem
当 DateTime
字段使用 @createdAt
指令注释时,Prisma 1 会自动生成值。这些值由 Prisma 1 服务器在运行时生成。由于此行为未反映在数据库本身中,因此 Prisma ORM 2.x 及更高版本中的内省无法识别它。
Example
Prisma 1 datamodel
type Post {
id: ID! @id
createdAt: DateTime! @createdAt
}
Prisma 1 generated SQL migration
CREATE TABLE "Post" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
"createdAt" TIMESTAMP NOT NULL
);
Result of introspection in Prisma ORM 2.x and later versions
model Post {
id String @id
createdAt DateTime
}
Workarounds
Manually add DEFAULT CURRENT_TIMESTAMP
to the database column
您可以修改列以添加 DEFAULT
约束,如下所示
ALTER TABLE "Post"
ALTER COLUMN "createdAt" SET DEFAULT CURRENT_TIMESTAMP;
进行此调整后,您可以重新内省数据库,@default
属性将添加到 createdAt
字段
model Post {
id String
createdAt DateTime @default(now())
}
Manually add the @default(now())
attribute to the Prisma model
作为一种解决方法,您可以手动将 @default(now())
属性添加到 Prisma 模型
model Post {
id String @id
createdAt DateTime @default(now())
}
如果在 Prisma schema 中设置了 @default
属性,并且您运行 prisma generate
,则生成的 Prisma Client 代码将在运行时生成指定的默认值(类似于 Prisma 1 服务器在 Prisma 1 中所做的)。
请注意,您必须在每次内省后重新添加该属性,因为内省会将其删除(因为旧版本的 Prisma schema 会被覆盖)!
@updatedAt
isn't represented in database
Problem
当 DateTime
字段使用 @updatedAt
指令注释时,Prisma 1 会自动生成值。这些值由 Prisma 1 服务器在运行时生成。由于此行为未反映在数据库本身中,因此 Prisma ORM 2.x 及更高版本中的内省无法识别它。
Example
Prisma 1 datamodel
type Post {
id: ID! @id
updatedAt: DateTime! @updatedAt
}
Prisma 1 generated SQL migration
CREATE TABLE "Post" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
updatedAt TIMESTAMP
);
Result of introspection in Prisma ORM 2.x and later versions
model Post {
id String @id
updatedAt DateTime
}
Workarounds
Manually add the @updatedAt
attribute to the Prisma model
作为一种解决方法,您可以手动将 @updatedAt
属性添加到 Prisma 模型
model Post {
id String @id
updatedAt DateTime @updatedAt
}
如果在 Prisma schema 中设置了 @updatedAt
属性,并且您运行 prisma generate
,则生成的 Prisma Client 代码将在现有记录更新时自动为此列生成值(类似于 Prisma 1 服务器在 Prisma 1 中所做的)。
请注意,您必须在每次内省后重新添加该属性,因为内省会将其删除(因为旧版本的 Prisma schema 会被覆盖)!
Inline 1-1 relations are recognized as 1-n (missing UNIQUE
constraint)
Problem
在 Prisma ORM v1.31 中引入的 datamodel v1.1 中,1-1 关系可以声明为内联。在这种情况下,关系将不会通过关系表维护,而是通过其中一个涉及的表上的单个外键维护。
当使用这种方法时,Prisma ORM 不会向外键列添加 UNIQUE
约束,这意味着在 Prisma ORM 2.x 及更高版本中进行内省后,以前的 1-1 关系将作为 1-n 关系添加到 Prisma schema。
Example
Prisma ORM datamodel v1.1 (available from 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 generated SQL migration
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)
);
Result of introspection in Prisma ORM 2.x and later versions
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-n。
Workaround
Manually add UNIQUE
constraint to the foreign key column
您可以修改外键列以添加 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])
}
All non-inline relations are recognized as m-n
Problem
Prisma 1 大多数情况下将关系表示为关系表
- Prisma 1 datamodel v1.0 中的所有关系都表示为关系表
- 在 datamodel v1.1 中,所有 m-n 关系以及声明为
link: TABLE
的 1-1 和 1-n 关系都表示为关系表。
由于这种表示形式,Prisma ORM 2.x 及更高版本中的内省会将所有这些关系识别为 m-n 关系,即使它们在 Prisma 1 中可能被声明为 1-1 或 1-n。
Example
Prisma 1 datamodel
type User {
id: ID! @id
posts: [Post!]!
}
type Post {
id: ID! @id
author: User! @relation(link: TABLE)
}
Prisma 1 generated SQL migration
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);
Result of introspection in Prisma ORM 2.x and later versions
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 关系。
Workaround
作为一种解决方法,您可以将数据迁移到与 Prisma ORM 的 1-n 关系兼容的结构中
- 在
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"); - 编写一个 SQL 查询,该查询读取
_PostToUser
关系表中的所有行,并且对于每一行- 通过查找列
A
中的值来查找相应的Post
记录 - 将列
B
中的值作为authorId
的值插入到该Post
记录中
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-n
model User {
id String @id
Post Post[]
}
model Post {
id String @id
User User @relation(fields: [authorId], references: [id])
authorId String
}
Json
type is represented as TEXT
in database
Problem
Prisma 1 在其数据模型中支持 Json
数据类型。但是,在底层数据库中,Json
类型的字段实际上是使用底层数据库的 TEXT
数据类型以纯字符串形式存储的。存储的 JSON 数据的任何解析和验证都由 Prisma 1 服务器在运行时完成。
Example
Prisma 1 datamodel
type User {
id: ID! @id
jsonData: Json
}
Prisma 1 generated SQL migration
CREATE TABLE "User" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
jsonData TEXT
);
Result of introspection in Prisma ORM 2.x and later versions
model User {
id String @id
jsonData String?
}
Workaround
您可以手动将列的类型更改为 JSON
ALTER TABLE "User" ALTER COLUMN "jsonData" TYPE JSON USING "jsonData"::json;
进行此调整后,您可以重新内省数据库,该字段现在将被识别为 Json
model User {
id String @id
jsonData Json?
}
Enums are represented as TEXT
in database
Problem
Prisma 1 在其数据模型中支持 enum
数据类型。但是,在底层数据库中,声明为 enum
的类型实际上是使用底层数据库的 TEXT
数据类型以纯字符串形式存储的。存储的 enum
数据的任何验证都由 Prisma 1 服务器在运行时完成。
Example
Prisma 1 datamodel
type User {
id: ID! @id
role: Role
}
enum Role {
ADMIN
CUSTOMER
}
Prisma 1 generated SQL migration
CREATE TABLE "User" (
id VARCHAR(25) PRIMARY KEY NOT NULL,
role TEXT
);
Result of introspection in Prisma ORM 2.x and later versions
model User {
id String @id
role String?
}
Workaround
您可以手动将 role
列转换为具有所需值的枚举
- 在数据库中创建一个
enum
,该enum
镜像您在 Prisma 1 数据模型中定义的enum
CREATE TYPE "Role" AS ENUM ('CUSTOMER', 'ADMIN');
- 将类型从
TEXT
更改为新的enum
ALTER TABLE "User" ALTER COLUMN "role" TYPE "Role"
USING "role"::text::"Role";
内省后,该类型现在被正确识别为枚举
model User {
id String @id
role Role?
}
enum Role {
ADMIN
CUSTOMER
}
Mismatching CUID length
Problem
Prisma 1 对所有数据库记录使用 CUID 作为 ID 值。在底层数据库中,这些 ID 表示为最大大小为 25 个字符的字符串(如 VARCHAR(25)
)。但是,当在 Prisma ORM 2.x(或更高版本)schema 中使用 @default(cuid())
配置默认 CUID 时,生成的 ID 值可能会超过 25 个字符的限制(最大长度可能为 30 个字符)。为了使您的 ID 能够用于 Prisma ORM 2.x(或更高版本),您因此需要将列类型调整为 VARCHAR(30)
。
Example
Prisma 1 datamodel
type User {
id: ID! @id
}
Prisma 1 generated SQL migration
CREATE TABLE "User" (
id VARCHAR(25) PRIMARY KEY NOT NULL
);
Result of introspection in Prisma ORM 2.x and later versions
model User {
id String @id
}
Workaround
您可以手动将 VARCHAR(25)
列转换为 VARCHAR(30)
ALTER TABLE "User" ALTER COLUMN "id" SET DATA TYPE character varying(30);
注意:当使用 Upgrade CLI 修复此问题时,即使您已更改底层数据库中的列类型,生成的 SQL 语句仍将继续显示在 Upgrade CLI 中。这目前是 Upgrade CLI 中的一个限制。
Scalar lists (arrays) are maintained with extra table
Problem
在 Prisma 1 中,您可以在模型上定义标量类型的列表。在底层,这是通过一个额外的表来实现的,该表跟踪列表中的值。
为了消除额外表的方法(这会产生隐藏的性能成本),Prisma ORM 2.x 及更高版本仅在您使用的数据库本身原生支持标量列表时才支持标量列表。目前,只有 PostgreSQL 原生支持标量列表(数组)。
因此,对于 PostgreSQL,您可以在 Prisma ORM 2.x 及更高版本中继续使用标量列表,但是您需要执行数据迁移,以将数据从 Prisma 1 的额外表传输到实际的 PostgreSQL 数组中。
Example
Prisma 1 datamodel
type User {
id: ID! @id
coinflips: [Boolean!]! @scalarList(strategy: RELATION)
}
Prisma 1 generated SQL migration
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);
Result of Prisma ORM 2 introspection
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 中受益,以用于标量列表(阅读以下部分以获取更多信息)。
Expand for sample Prisma Client API calls
要访问 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
上 map
coinflips
const currentCoinflips = user!.coinflips.map((cf) => cf.value)
注意:上面的感叹号表示您正在强制解包
user
值。这是必要的,因为从先前的查询返回的user
可能是null
。
这是调用 map
后 currentCoinflips
的值
[false, true, false, true, true, false]
Workaround
以下解决方法仅适用于 PostgreSQL 用户!
由于标量列表(即 数组)是 PostgreSQL 的原生功能,因此您可以在 Prisma schema 中继续使用相同的 coinflips: Boolean[]
表示法。
但是,为了这样做,您需要手动将底层数据从 User_coinflips
表迁移到 PostgreSQL 数组中。以下是如何执行此操作
- 将新的
coinflips
列添加到User
表中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";
您现在可以内省数据库,并且 coinflips
字段将在新的 Prisma schema 中表示为数组
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 ]
}