prisma文档摘要

prisma文档摘要

概念

方便下面文档描述理解上不清楚的时候，来这里查看相关概念。

• 迁移：记录需要操作的sql，以及将sql连接到数据库执行。
  主要有两个步骤：
  1. 在本地生成对数据库表和结构等的修改的记录文件（一般在prisma/migrations/timestramp_action/migration.sql）。
  2. 在数据库执行sql文件
• 预迁移：使用--create-only参数，只会生成文件，不会立即执行sql语句，方便修改sql，一般用于自定义迁移。
• 应用：迁移的第二步，连接数据库后，执行本地生成的sql，将迁移应用到数据库。
• 影子数据库：
  用于开发时使用，其实就是本地数据库。
• seed：seed文件，用于生成数据库的基本数据（比如用于测试）
• 基线版本：作用是保持原有数据库的结构和数据。主要方法是：初始化sql迁移记录，或者标记已经执行过的sql为已应用状态，目的是避免重复执行sql语句从而改变了数据库（比如清空数据等影响）
• 反省：从线上数据库同步结构到本地schema.prisma

1、prisma开发流程简录：

1. 创建和应用迁移

npx prisma migrate dev

该操作会创建prisma/migrations/timeStamp_action/migration.sql

2. 影子数据库

概述：主要是本地开发时当作数据库。

Prisma Migrate在运行以开发为中心的命令时会使用第二个临时数据库，例如:

  prisma migrate dev
  prisma migrate reset

影子数据库会在每次运行开发命令时自动创建和删除，主要用于检测问题，如架构漂移。

影子数据库在生产中是不需要的，并且不会被prisma migrate resolve和prisma migrate deploy等以生产为中心的命令使用。

原理

运行prisma migrate dev创建新迁移时，Prisma Migrate 会使用影子数据库:

• 检测架构漂移，这意味着检查开发数据库没有手动更改。
  为了检测开发中的漂移，Prisma Migrate:
  • 创建影子数据库的最新副本 (如果影子数据库是云托管的，则执行软重置)。
  • 在影子数据库中重放当前迁移历史记录。
  • 检查影子数据库，以生成 Prisma 架构的’当前状态’。
  • 将当前迁移历史的最终状态与开发数据库进行比较。
  • 如果当前迁移历史的结束状态与开发数据库不匹配 (例如，由于手动更改)，则报告架构漂移。
  • 如果 Prisma Migrate 没有检测到架构漂移，它将继续生成新的迁移。
• 生成新迁移
  • 根据当前 Prisma 架构计算目标数据库架构。
  • 比较现有迁移历史记录和目标架构的结束状态，并生成从一个迁移到另一个迁移的步骤。
  • 将这些步骤呈现为 SQL 字符串，并将其保存在新的迁移文件中。
  • 将生成的迁移应用到开发数据库 (假设您没有指定 --create-only 标志)
  • 删除影子数据库(云托管数据库不能删除，但会在 migrate dev 命令开始时重置)

• 如果您使用云托管数据库进行开发，则需要手动创建影子数据库。

手动添加影子数据库

添加字段shadowDatabaseUrl

.env新增SHADOW_DATABASE_URL，字段同DATABASE_URL，内容为本地数据库。

datasource db {
  provider          = "postgresql"
  url               = env("DATABASE_URL")
  shadowDatabaseUrl = env("SHADOW_DATABASE_URL")
}

3. 编写种子脚本

seed.js

npx prisma db seed

开发环境中经常需要重置数据库 - 例如，切换具有不同迁移历史的代码分支之后, 当运行prisma migrate dev时，会提示migrate reset。种子脚本可以帮你在重置数据库后填充初始数据。

• 一种是prisma db seed手动调用，
• 另一种prisma migrate dev 或者 prisma migrate reset会自动调用

以下情况 Prisma Migrate 会触发 seeding:

• 手动执行 prisma migrate reset 命令
• 使用prisma migrate dev重置数据库 - 例如，迁移历史发生冲突导致的或者数据库 schema 偏移(drift)导致的
• 传入 --skip-seed 标志可以跳过prisma migrate dev和prisma migrate reset的 seeding

4. 将Prisma Migrate添加到现有项目中

结果：重置数据库，开发数据库的数据丢失

1. 自省检测更新本地的prisma schema

prisma db pull

2. 初始化但不执行sql，方便修改

prisma migrate dev --name initial-migration --create-only

3. 可能的修改sql文件

4. 应用初始迁移

npx prisma migrate dev

Prisma Migrate 检测到数据库与迁移历史不同步，将提示你重置。确认重置（仅在开发环境中！）。

5. 审查数据库 schema，以确保迁移能达到预期的最终状态（例如，通过与生产数据库 schema 进行比较）。

6. 提交整个迁移历史文件和schema.prisma文件

7. 其他开发者需要重置开发数据库

npx prisma migrate dev

5. 生成生产环境数据库的基线版本

生成基线版本操作为包含数据且不能被重置的数据库（如生产数据库）初始化迁移历史

结果：不会影响线上数据

生成基线版本 步骤:

• 切换到一个可以访问你想要的 baseline 数据库的环境。
• 确保你有一个新迁移目录的工作副本。
• 运行下面命令来 baseline 迁移 - 本例将初始化迁移历史步骤所产生的迁移标记为已经应用：
• prisma migrate resolve --applied 20210426141759_initial-migration 如果你需要 baseline 多个迁移（例如，从开发环境转移后产生了更多的迁移），请为每个迁移分别运行prisma migrate resolve命令。

定制迁移流程

目的：在应用迁移之前对其进行编辑，即修改sql语句

要在应用迁移之前编辑该文件:

• 做一个需要自定义 SQL 的 schema 改变（例如，保留现有数据）。
• 创建一个预迁移：

  npx prisma migrate dev --create-only

• 修改生成的 SQL 文件。
• 执行修改后的 SQL：

  npx prisma migrate dev

重命名字段

默认情况下，schema 重命名schema中的一个字段会导致:

• CREATE 一新的列 (例如, fullname)
• DROP 现有列 (for example, name) 和该列中的数据

通过修改生成的 SQL 文件来避免这种上面的情况：

生成的文件：

ALTER TABLE "Profile" DROP COLUMN "biograpy",
ADD COLUMN  "biography" TEXT NOT NULL;

修改后的文件：

ALTER TABLE "Profile"
RENAME COLUMN "biograpy" TO "biography"

最后应用迁移

应用 expand 和 contract 模式，在不停机的情况下改进 schema

情况：修改字段，

可能的结果：停机

概念：可以将修改字段分解为一系列不连续的步骤，从而避免停机。 这种模式叫作 expand 和 contract 模式。

步骤：

1. 增加新的字段并创建迁移
2. 更新代码并同时写入旧的字段 和 新的字段, 但保持读取旧的字段, 然后部署代码
3. 创建一个空的迁移，将旧的字段中的现有数据拷贝到新的字段

update table set 新的字段=旧的字段

4. 验证数据库中的薪字段的完整性
5. 更新代码，读新字段
6. 更新代码，停止写入旧的字段
7. 删除旧的字段，创建迁移移除旧的字段

5. 开发环境中的迁移故障排除

开发环境中迁移历史冲突的原因

• 已经应用的迁移，之后被修改了
• 文件系统中缺少已应用的迁移

如果 Prisma Migrate 在运行prisma migrate dev时检测到迁移历史冲突, CLI 会提示要求重置数据库并重新应用迁移历史。

这时候会把线上的数据库的表删除重建，然后再执行seed.js去填充测试数据。

开发环境中产生 Schema 偏移(drift)的原因
Schema 偏移(drift) 产生原因:
在没有使用迁移的情况下改变了数据库 schema - 例如, 通过使用prisma db push或者手动改了 schema.

修复：

1. 数据库的数据不需要保留，则直接重置

npx prisma migrate reset
npx prisma migrate dev

2. 保留数据库数据

npx prisma db pull
npx prisma migrate dev --name introspected_change

6. 迁移失败

在开发环境中，修复迁移失败的最简单方法是解决根本原因并重置数据库
如果迁移过程因某些原因被打断了，请重置数据库：

prisma migrate reset