关于影子数据库
影子数据库是第二个prisma migrate dev
时都会**自动创建和删除**,主要用于**检测问题**,例如模式漂移或生成的迁移可能导致的数据丢失。
migrate diff
命令在与本地migrations
目录进行--from-migrations
或--to-migrations
比较时,也需要影子数据库。
- 如果您的数据库不允许创建和删除数据库(例如在云托管环境中),您需要手动创建和配置影子数据库。
影子数据库在生产环境中**不是**必需的,并且不用于生产重点命令,例如prisma migrate resolve
和prisma migrate deploy
。
影子数据库从不用于 MongoDB,因为migrate dev
在那里不使用。
影子数据库的工作原理
当您运行prisma migrate dev
创建新迁移时,Prisma Migrate 会使用影子数据库来
🎨 展开以漫画形式查看影子数据库的解释。
检测模式漂移
为了检测开发中的漂移,Prisma Migrate
- 创建影子数据库的全新副本(如果影子数据库通过
shadowDatabaseUrl
配置,则执行软重置) - 在影子数据库中重新运行**当前**的现有迁移历史记录。
- **内省**影子数据库以生成 Prisma 模式的“当前状态”。
- 将当前迁移历史记录的结束状态与开发数据库进行比较。
- 如果当前迁移历史记录的结束状态(通过影子数据库)与开发数据库不匹配(例如,由于手动更改),则报告**模式漂移**
如果 Prisma Migrate 没有检测到模式漂移,它将继续生成新迁移。
**注意**:影子数据库不负责检查迁移文件是否被**编辑或删除**。这是通过
_prisma_migrations
表中的checksum
字段完成的。
如果 Prisma Migrate 检测到模式漂移,它会输出有关数据库哪些部分已漂移的详细信息。以下示例输出可能会在开发数据库被手动修改时显示:Color
枚举缺少预期的变体RED
,并包含意外的变体TRANSPARENT
[*] Changed the `Color` enum
[+] Added variant `TRANSPARENT`
[-] Removed variant `RED`
生成新迁移
假设 Prisma Migrate 没有检测到模式漂移,它会继续根据 Prisma 模式更改生成新迁移。为了生成新迁移,Prisma Migrate
- 根据当前 Prisma 模式计算目标数据库模式。
- 比较现有迁移历史记录的结束状态和目标模式,并生成从一个到另一个的步骤。
- 将这些步骤渲染为 SQL 字符串并将其保存在新的迁移文件中。
- 评估由 SQL 引起的数据丢失并发出警告。
- 将生成的迁移应用于开发数据库(假设您没有指定
--create-only
标志) - 删除影子数据库(通过
shadowDatabaseUrl
配置的影子数据库不会被删除,但在migrate dev
命令开始时会被重置)
手动配置影子数据库
在某些情况下(例如,当云托管数据库不允许创建和删除数据库时),手动定义应作为migrate dev
的影子数据库的连接字符串和数据库名称可能是有意义的。在这种情况下,您可以
- 创建一个专用的数据库作为影子数据库
- 将该数据库的连接字符串添加到您的环境变量
SHADOW_DATABASE_URL
(或.env
文件) - 添加读取此环境变量的
shadowDatabaseUrl
字段
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
shadowDatabaseUrl = env("SHADOW_DATABASE_URL")
}
**重要提示**:不要为
url
和shadowDatabaseUrl
使用完全相同的值,否则可能会删除数据库中的所有数据。
云托管的影子数据库必须手动创建
一些云提供商不允许您使用 SQL 删除和创建数据库。有些要求通过在线界面创建或删除数据库,有些则真的只限制您一个数据库。如果您在这样的云托管环境中**开发**,您必须
- 创建一个专用的云托管影子数据库
- 将 URL 添加到您的环境变量
SHADOW_DATABASE_URL
- 添加读取此环境变量的
shadowDatabaseUrl
字段
datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
shadowDatabaseUrl = env("SHADOW_DATABASE_URL")
}
**重要提示**:不要为
url
和shadowDatabaseUrl
使用相同的值。
影子数据库用户权限
为了在使用migrate dev
时创建和删除影子数据库,Prisma Migrate 目前要求您的datasource
中定义的数据库用户拥有**创建数据库**的权限。
数据库 | 数据库用户要求 |
---|---|
SQLite | 无特殊要求。 |
MySQL/MariaDB | 数据库用户必须拥有CREATE, ALTER, DROP, REFERENCES ON *.* 权限 |
PostgreSQL | 用户必须是超级用户或拥有CREATEDB 权限。参见CREATE ROLE (PostgreSQL 官方文档) |
Microsoft SQL Server | 用户必须是站点管理员或拥有SERVER 安全对象。参见官方文档。 |
如果您使用云托管数据库进行开发且无法使用这些权限,请参见:云托管影子数据库
注意:例如,Azure SQL 禁用了影子数据库的自动创建。
如果 Prisma Migrate 无法使用您提供的连接 URL 凭据创建影子数据库,它会抛出以下错误
Error: A migration failed when applied to the shadow database
Database error: Error querying the database: db error: ERROR: permission denied to create database
要解决此错误
- 如果您在本地工作,我们建议您更新数据库用户的权限。
- 如果您正在针对不允许创建和删除数据库的数据库(出于任何原因)进行开发,请参见手动配置影子数据库
- 如果您正在针对云数据库(例如,在 Heroku、Digital Ocean 或 Vercel Postgres 上)进行开发,请参见:云托管影子数据库。
- 如果您正在针对云数据库(例如,在 Heroku、Digital Ocean 或 Vercel Postgres 上)进行开发,并且目前正在**原型设计**,因此您不关心生成的迁移文件,而只需要将 Prisma 模式应用于数据库模式,则可以运行
prisma db push
而不是prisma migrate dev
命令。
**重要提示**:影子数据库**仅**在开发环境中需要(特别是对于
prisma migrate dev
命令)- 您**无需**对生产环境进行任何更改。