Wasp 数据库迁移全流程解析:从 schema.prisma 定义实体到 `wasp db migrate-dev` 与 TACTE 自动化执行 📅 发布时间:2026/9/14 2:01:48 👁 浏览次数: Wasp 数据库迁移全流程解析从 schema.prisma 定义实体到wasp db migrate-dev与 TACTE 自动化执行【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp导读本文以 Wasp 仓库中机器可执行教程的第三步03-migrate.md为骨架完整讲解 Wasp 应用数据库迁移的标准工作流先在schema.prisma中声明 Prisma 数据模型实体再通过wasp db migrate-dev命令生成并应用数据库迁移。同时深入剖析 Tutorial Actions ExecutorTACTE如何将文档中的TutorialAction actionMIGRATE_DB注解自动翻译为真实的 CLI 调用并用 E2E 快照测试验证整条执行链路的正确性。读完本文你将掌握 Wasp 实体定义语法、数据库迁移命令的完整参数语义以及 Wasp 文档教程如何做到文字可读、动作可执行。一、这份文档是什么机器可执行教程的迁移步骤在 Wasp 仓库的web/tutorial-actions-executor/目录下存放着一套名为TACTETutorial Actions Executor的 CLI 工具。它的职责是从 Wasp 官方教程的 MDX 文件中提取TutorialAction组件解析出一个个机器可执行的动作如初始化应用打补丁迁移数据库然后按顺序执行最终生成一个完整可运行的 Wasp 应用。web/tutorial-actions-executor/e2e-tests/fixtures/tutorial/03-migrate.md正是这套工具用于 E2E 测试的最小化教程 fixture——它模拟了真实教程中添加实体 → 迁移数据库这一步。文档主体只有两个动作--- title: 3. Migrate DB --- import { TutorialAction } from ./TutorialAction; ## Migrate DB TutorialAction idadd-model actionAPPLY_PATCH Add a model to schema.prisma: prisma model Post { id Int id default(autoincrement()) title String content String? createdAt DateTime default(now()) }Now, migrate the database withwasp db migrate-dev.虽然篇幅简短但它完整承载了两个核心知识点实体Entity定义与数据库迁移Migration这正是 Wasp 数据模型体系的基础环节。真实教程中对应的完整版可见 web/docs/tutorial/04-entities.md其中使用同样的模式定义了Task实体并执行wasp db migrate-dev。二、第一步在 schema.prisma 中声明实体Wasp 使用 Prisma 作为 ORM数据模型统一写在项目根目录的schema.prisma文件中。minimal起步模板自带的初始文件见 waspc/data/Cli/starters/minimal/schema.prisma只有 datasource 与 generator 两段datasource db { provider sqlite // Wasp requires that the url is set to the DATABASE_URL environment variable. url env(DATABASE_URL) } // Wasp requires the prisma-client-js generator to be present. generator client { provider prisma-client-js }教程动作add-model类型APPLY_PATCH所做的工作就是以 Git patch 的形式向这个文件追加一个Post模型。对应的补丁文件位于 web/tutorial-actions-executor/e2e-tests/fixtures/tutorial/patches/03-migrate__add-model.patch -8,3 8,10 datasource db { generator client { provider prisma-client-js } model Post { id Int id default(autoincrement()) title String content String? createdAt DateTime default(now()) }2.1 Post 模型字段逐行解读id Int id default(autoincrement())主键字段类型为Int由数据库自增生成。这是 Wasp/Prisma 中最常见的主键写法title String必填字符串字段。注意没有?后缀表示该列在数据库中为 NOT NULLcontent String?可空字符串字段。?表示该列允许为 NULL适合正文可选的场景createdAt DateTime default(now())创建时间戳。default(now())让数据库在插入行时自动写入当前时间应用代码无需手动赋值。字段名采用camelCase是 Prisma 的推荐风格Prisma 会自动将其转换为数据库列名如createdAt→created_at并在生成的 Prisma Client 中暴露为驼峰属性。2.2 实体与数据库后端的关系datasource中的provider决定了迁移生成的目标方言。Wasp 默认使用 SQLite仅限开发环境生产环境则需切换到 PostgreSQL。关于两种后端的切换细节可参考 web/docs/data-model/databases.md切换到 PostgreSQL 只需把provider改为postgresql并保证开发期间有一个可用的数据库实例。无论哪种后端wasp db migrate-dev都是将 schema 变更落到数据库的标准入口。三、第二步用wasp db migrate-dev迁移数据库在真实使用中编辑完schema.prisma后开发者需要手动执行wasp db migrate-dev该命令的行为在 web/docs/general/cli.md 中有明确说明wasp db migrate-dev使开发数据库与当前 schema实体状态保持同步。如果 schema 有任何变更它会生成一个新的迁移migration并将所有待应用的迁移应用到数据库。其关键语义可拆解为三点对比将当前schema.prisma与数据库实际结构对比找出差异生成若存在差异自动生成一个包含CREATE TABLE/ALTER TABLE等语句的迁移目录形如migrations/时间戳_名称/migration.sql应用执行所有尚未应用的迁移使数据库结构达到与 schema 一致的状态。此外--name 名称选项可以显式指定迁移名称默认会基于动作/内容自动生成--create-only选项则只生成迁移文件而不立即应用便于人工审查 SQL。需要注意不要绕过 Wasp 直接使用prisma命令操作数据库一切数据库变更都应通过wasp db系列命令完成参见 web/docs/general/cli.md 中的 caution 提示。迁移成功后可配合wasp db studio打开数据库 GUI直观查看新实体的表结构wasp start则会基于最新 schema 重新生成 Prisma Client使查询/操作代码获得对新实体的类型支持。四、机器可执行TACTE 如何将 MIGRATE_DB 动作变成真实命令在 TACTE 的体系里迁移数据库并不是让读者手动敲命令而是由工具自动执行。理解这一点需要沿着解析与执行两条链路走一遍源码。4.1 动作类型系统动作的类型定义在 web/tutorial-actions-executor/src/actions/actions.tsexport type Action InitAppAction | ApplyPatchAction | MigrateDbAction; export interface MigrateDbAction extends BaseAction { kind: MIGRATE_DB; } export interface BaseAction { id: ActionId; sourceTutorialFilePath: MdxFilePath; }可以看到MIGRATE_DB动作无需额外属性只需要id即文档中的migrate-db和来源文件路径。代码注释还特别提醒新增动作类型时必须同步更新 web/docs/tutorial/TutorialAction.tsx 中的ActionProps联合类型保证文档组件与执行器两侧类型一致。4.2 从 MDX 文本到 AST 再到动作对象解析链路分三层MDX 解析web/tutorial-actions-executor/src/extract-actions/mdxParsing.ts用micromark-extension-mdx-jsx与mdast-util-mdx-jsx把 MDX 文本解析为 mdast AST节点提取web/tutorial-actions-executor/src/extract-actions/astTraversal.ts通过unist-util-visit遍历 AST凡是名为TutorialAction的mdxJsxFlowElement节点就读取其id、action、starterTemplateName三个属性id与action缺失时直接抛错保证文档质量动作映射web/tutorial-actions-executor/src/extract-actions/nodeMapping.ts按action属性分发到createInitAppAction/createApplyPatchAction/createMigrateDbAction其中INIT_APP强制要求starterTemplateName属性而MIGRATE_DB则零参数构造。4.3 执行阶段MIGRATE_DB 到底跑了什么动作的顺序执行逻辑在 web/tutorial-actions-executor/src/commands/generate-app/execute-actions.ts 中MIGRATE_DB分支如下case MIGRATE_DB: await waspDbMigrate({ waspCliCommand, appDir: tutorialApp.appDirPath, migrationName: action.id, }); break;这里有一个非常优雅的设计迁移名称直接复用动作的id。由于 fixture 中动作 id 是migrate-db最终生成的迁移目录就是migrations/时间戳_migrate_db/。真正发出 CLI 调用的封装在 web/tutorial-actions-executor/src/waspCli.tsawait $({ // We ignore stdin to avoid hangs in non-interactive environments e.g. e2e tests stdio: [ignore, pipe, pipe], cwd: appDir, })${waspCliCommand} db migrate-dev --name ${migrationName};值得注意的实现细节执行时显式将stdin 置为 ignore。因为wasp db migrate-dev在交互式终端中会等待用户输入如确认迁移名称而 TACTE 在 CI / E2E 场景下是非交互的若不忽略 stdin 命令会永久挂起。由于迁移名称已通过--name显式传入忽略 stdin 是安全且必要的。每个动作执行完毕后commitActionChanges还会以动作 id 作为 commit message 提交一次 Git 提交从而保证每个教程步骤 一次可追溯的提交。五、验证E2E 快照测试如何确认迁移真的发生了TACTE 对这套流程的正确性保障来自 Vitest 快照测试 web/tutorial-actions-executor/e2e-tests/generate-app.test.ts。它用三个 fixture 文件01-init.md、02-patch.md、03-migrate.md依次执行INIT_APP、APPLY_PATCH、MIGRATE_DB然后对生成的应用做四项断言。存储在 web/tutorial-actions-executor/e2e-tests/snapshots/generate-app.test.ts.snap 中的快照可以直观看到迁移动作的产物file-structure 快照生成的项目中出现了migrations/时间戳_migrate_db/migration.sql与migrations/migration_lock.toml证明MIGRATE_DB动作确实创建了迁移目录prisma-schema 快照schema.prisma在初始 datasource/generator 之后追加了完整的Post模型与补丁内容逐字一致git-commits 快照Git 历史依次为create-test-app→add-test-file→add-model→migrate-db且migrate-db提交只包含migrations/...、package-lock.json两类文件——说明迁移动作没有夹带无关改动测试还通过normalizeTimestamps将迁移目录中的 14 位时间戳替换为占位符避免每次运行因时间变化产生假性差异。六、在真实项目中复现这套工作流如果你想在自己的 Wasp 项目中手动体验而非通过 TACTE 自动化完整步骤为# 1. 基于 minimal 模板创建新应用 wasp new MyApp -t minimal # 2. 在 schema.prisma 的 generator client 之后追加实体定义 # 即本文第二部分给出的 Post 模型 # 3. 生成并应用数据库迁移 wasp db migrate-dev # 可选显式命名迁移 wasp db migrate-dev --name add_post # 4. 启动开发环境基于最新 schema 生成 Prisma Client wasp start # 5. 如需查看数据库表结构与数据 wasp db studio而若要使用 TACTE 自动化复现可直接运行其generate-app命令详见 web/tutorial-actions-executor/README.mdnpm run generate-app -- --app-name MyApp --output-dir ./.result --tutorial-dir ./my-tutorial当某个APPLY_PATCH补丁因冲突无法应用时generate-app会暂停并引导你手动修改.result/MyApp中的代码确认后由工具自动生成新的补丁文件并继续执行后续动作包括MIGRATE_DB。若希望借助 LLM 完成人工介入环节README 也给出了保持generate-app运行、按提示让 LLM 编辑生成目录、人工确认后继续的 human-in-the-loop 流程。七、小结一条从文档到数据库的自动化链路回顾03-migrate.md及其背后的实现可以看到 Wasp 把数据库迁移这一常规操作同时做到了两件事对开发者友好wasp db migrate-dev一条命令完成对比 schema → 生成迁移 → 应用迁移实体定义只需在schema.prisma中声明 Prisma 模型即可对自动化友好通过TutorialAction id... actionMIGRATE_DB /这样的声明式注解教程步骤可以被 TACTE 解析成结构化动作映射为wasp db migrate-dev --name id的真实调用并以一步一提交的方式沉淀为可验证的 Git 历史最终由 E2E 快照测试兜底。这套声明式文档 自动化执行 快照验证的模式正是 Wasp 保证官方教程永远可复现、可测试、可交付的技术底座。参考路径速查教程 fixture 本体web/tutorial-actions-executor/e2e-tests/fixtures/tutorial/03-migrate.mdadd-model 动作的补丁web/tutorial-actions-executor/e2e-tests/fixtures/tutorial/patches/03-migrate__add-model.patch动作类型定义web/tutorial-actions-executor/src/actions/actions.ts数据库迁移命令封装web/tutorial-actions-executor/src/waspCli.ts动作执行主循环web/tutorial-actions-executor/src/commands/generate-app/execute-actions.tsE2E 测试与快照web/tutorial-actions-executor/e2e-tests/generate-app.test.ts、web/tutorial-actions-executor/e2e-tests/snapshots/generate-app.test.ts.snapwasp db命令官方说明web/docs/general/cli.md实体与数据库文档web/docs/tutorial/04-entities.md、web/docs/data-model/databases.md起步模板 schemawaspc/data/Cli/starters/minimal/schema.prisma【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考