prisma文档摘要

商曦

2023-12-01

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添加到现有项目中

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

自省检测更新本地的prisma schema

prisma db pull

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

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

可能的修改sql文件
应用初始迁移

npx prisma migrate dev

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

审查数据库 schema，以确保迁移能达到预期的最终状态（例如，通过与生产数据库 schema 进行比较）。
提交整个迁移历史文件和schema.prisma文件
其他开发者需要重置开发数据库

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 模式。

步骤：

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

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

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

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

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

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

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

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

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

修复：

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

npx prisma migrate reset
npx prisma migrate dev

保留数据库数据

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

6. 迁移失败

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

prisma migrate reset

prisma文档摘要