管理核心数据库迁移

EmDash 核心迁移更新 EmDash 自身的表以及内容表上的标准列。它们不会创建、删除或重命名您的集合和字段；有关内容模型更改，请参阅 演进已部署的站点。

运行时迁移模式默认为 auto，因此现有部署会在启动时继续应用待处理的核心迁移。部署管理的迁移允许构建在新应用程序代码接收流量之前迁移其数据库，然后让运行时验证或信任该部署步骤。

构建、迁移、部署、检查

Astro 构建或同步会写入 .emdash/migrations.json。此无密钥清单记录了该构建使用的确切 EmDash 版本、有序迁移集、区域设置配置和适配器迁移执行器。

从生成清单的依赖项所在的项目运行这些命令。首先构建并检查目标。

pnpm build
pnpm emdash migrate --status

确认报告的目标是预期的数据库后，启动交互式迁移。在确认前再次在提示中审查目标。然后部署相同的构建并检查已部署的架构。

pnpm emdash migrate
pnpm wrangler deploy
pnpm emdash migrate --check

emdash migrate --status 报告已应用、待处理和未知的迁移，而不更改数据库。简单的 emdash migrate 命令显示目标，并在应用待处理迁移之前请求确认。

--check 从不应用迁移，当已知迁移待处理或数据库包含构建未知的迁移记录时以非零退出。当您想在不使用 check 的”需要工作”非零退出状态的情况下检查相同的迁移集时，请使用 --status。CLI 参考 区分待处理、未知、确认、中断和操作退出码。

非交互式应用和每个 --json 应用都需要 --expected-target-fingerprint；如果解析的目标不匹配，命令将失败。在自动化部署作业中使用这些选项，而不是上述交互式工作流。

使用 --manifest path/to/migrations.json 指定存储在其他位置的清单。对于本地调查，--from-config [--config astro.config.mjs] 在不运行 Astro 钩子或启动服务器的情况下明确评估受信任的项目配置。部署管道应使用构建清单。

显式选择数据库

配置的适配器向清单提供无密钥的目标信息。凭据保留在环境变量中，仅由迁移命令读取。

相对 SQLite 路径从项目根目录解析，而不是从已安装的 EmDash 包或 shell 的当前子目录解析。PostgreSQL、libSQL 和 Hyperdrive 目标标签省略凭据和 URL 参数。

迁移前预配 D1

创建 D1 数据库和迁移其架构是分开的操作。emdash migrate 从不创建缺失的数据库。

您也可以提供 --account-id 与 --d1 <数据库UUID或名称>。名称查找必须恰好解析为一个数据库。预览 ID、占位符 ID、冲突的账户和模糊的绑定会以封闭方式失败。

在 CI 中配置 D1 迁移

D1 不提供 PostgreSQL 使用的咨询迁移锁。每个账户和数据库 UUID 最多运行一个迁移作业。

在 CI 环境中设置以下密钥和变量：

• 密钥 CLOUDFLARE_API_TOKEN：具有 D1 编辑权限的范围令牌。
• 变量 CLOUDFLARE_ACCOUNT_ID：拥有数据库的 Cloudflare 账户 ID。
• 变量 D1_DATABASE_ID：生产 D1 数据库 UUID。
• 变量 EMDASH_TARGET_FINGERPRINT：在本地审查账户和数据库后 emdash migrate --status 打印的指纹。

以下 GitHub Actions 工作流使用这些值，并将并发组键限定为两个不可变的 D1 标识符。其应用步骤是非交互式的，因此明确提供已审查的目标指纹。

name: Deploy

on:
  workflow_dispatch:

concurrency:
  group: emdash-migrations-${{ vars.CLOUDFLARE_ACCOUNT_ID }}-${{ vars.D1_DATABASE_ID }}
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - name: Inspect EmDash migration target
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          pnpm emdash migrate --status --json \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}"
      - name: Apply EmDash migrations
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          EMDASH_TARGET_FINGERPRINT: ${{ vars.EMDASH_TARGET_FINGERPRINT }}
        run: |
          pnpm emdash migrate \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}" \
            --expected-target-fingerprint "$EMDASH_TARGET_FINGERPRINT"
      - run: pnpm wrangler deploy
      - name: Check EmDash migrations
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          pnpm emdash migrate --check \
            --account-id "${{ vars.CLOUDFLARE_ACCOUNT_ID }}" \
            --d1 "${{ vars.D1_DATABASE_ID }}"

仅在本地审查更改的目标后才更新 EMDASH_TARGET_FINGERPRINT。指纹不包含凭据，但在未检查账户和数据库的情况下更改它会移除防止迁移错误数据库的保护。

Hyperdrive 连接到源

Hyperdrive 的迁移执行器打开到源的直接 PostgreSQL 连接。它不通过 Hyperdrive 发送迁移流量，不使用可选的缓存绑定，也不继承 Worker 的私有网络可达性。

部署运行器必须能够到达源。当默认的绑定特定变量不合适时，在 hyperdrive() 上设置 migrationConnectionStringEnv，并仅向迁移作业提供该变量。保持运行时 Hyperdrive 凭据和直接源部署凭据分开。

逐步采用运行时强制

以下 EmDash 集成配置在保留开发中自动迁移的同时启用运行时强制。

emdash({
	database,
	migrations: {
		runtime: "check",
		dev: "auto",
	},
});

• auto 是向后兼容的默认值。运行时启动时检查并应用待处理的迁移。
• check 执行定向状态查询，当已知迁移待处理时在服务请求之前返回 503。在滚动部署期间容忍来自较新兼容构建的记录。
• manual 不执行运行时迁移或状态查询。仅在部署管道可靠地应用和检查每个构建后使用。

当同一构件通过多个环境提升时，EMDASH_MIGRATIONS_MODE 可以覆盖运行时模式。设置和开发旁路路由遵循有效模式；它们不能在 check 或 manual 后面静默迁移。

保守的推出方式是：引入部署作业时使用 auto，作业可靠后使用 check，当每次部署都强制执行外部检查时使用 manual。

滚动部署期间的兼容性

核心迁移遵循扩展/部署/收缩排序。部署可能会暂时针对扩展的数据库运行旧的和新的应用程序隔离，并且回填可能仍在进行中。在每个已部署版本停止使用架构之前，不要收缩架构。

未知的已应用迁移记录仅在此滚动部署方向上被运行时 check 容忍。CLI 的精确检查会报告它们，apply 拒绝变更，因为数据库可能更新或具有不同的迁移历史。

故障排除

• 未找到迁移清单。 首先构建或同步项目。对于非标准构件位置使用 --manifest，或明确选择 --from-config 进行本地调查。
• 构件与项目的 EmDash 不匹配。 重新构建并一起部署应用程序和清单。运行项目的 CLI 而不是全局安装。
• 目标缺失或模糊。 首先预配它，然后提供明确的数据库路径、连接变量名、D1 选择器或选定的 Wrangler 配置和环境。EmDash 不会从不相关的环境变量或绑定中猜测。
• 目标指纹已更改。 停下来审查显示的账户、环境、数据库名称、UUID 或路径。仅在确认预期目标后更新期望的指纹。
• 存在未知的迁移记录。 不要删除记录或重新运行 apply。确认应用程序构件是预期版本，并调查是否有更新或不同的构建迁移了数据库。
• D1 写入结果不明确。 不要重播迁移命令。对相同的账户和数据库 UUID 运行 emdash migrate --status，检查结果，如果迁移中途停止则升级处理。
• Hyperdrive 无法连接。 测试从部署运行器到 PostgreSQL 源的可达性，并验证直接源变量。Worker 到 Hyperdrive 的连接性不能证明运行器可以到达源。