atlas-onboard

Atlas 入门

通过六个阶段将一个仓库从未配置 Atlas 推进到生产环境，流程与《评估 Atlas 指南》(https://atlasgo.io/guides/evaluation/intro) 相同。每个阶段都会以 Agent 执行并向用户展示的一项检查作为结束。本技能负责规定顺序、决策和检查。atlas 技能提供命令参考。

文件

本技能包含 SKILL.md 和七个文件，分别托管于 https://atlasgo.io/skills/atlas-onboard/<path>： agents/openai.yaml、references/stage-0-plan.md、references/stage-1-schema.md、 references/stage-2-workflow.md、references/stage-3-ci.md、references/stage-4-deploy.md 和 references/stage-5-promote.md。每个阶段开始时，阅读对应的阶段参考文件。

依赖

需要与本技能安装在同一目录旁的 atlas 技能（../atlas/SKILL.md）。如果缺少该文件，请在开始前将 https://atlasgo.io/skills/atlas/SKILL.md 下载到 ../atlas/SKILL.md，并将其 Files 部分中列出的每个参考文件下载到 ../atlas/references/<name>。下文以 atlas/ 开头的路径均指向该技能。

对于 PostgreSQL、MySQL 或 MariaDB，还需要与本技能安装在同一目录旁的数据库技能：atlas-postgres （../atlas-postgres/SKILL.md），或者适用于 MySQL 和 MariaDB 的 atlas-mysql（../atlas-mysql/SKILL.md）。该技能包含对应数据库引擎的规则，例如开发数据库、URL 范围以及需要审核的 lint 发现。阶段 0 确定数据库引擎后阅读一次，并在每个阶段遵循其中的规则。如果缺少该技能，建议用户安装：在 Claude Code 中运行 claude plugin update atlas@ariga，或者在其他 Agent 中再次运行 npx skills add ariga/atlas -a <agent> -y 命令。在此之前，可从 https://atlasgo.io/skills/atlas-postgres/SKILL.md 或 https://atlasgo.io/skills/atlas-mysql/SKILL.md 阅读。

如果阶段 4 使用 Atlas Kubernetes Operator 部署（4.6、4.7），还需阅读 atlas-operator 技能（../atlas-operator/SKILL.md）。如果缺少该技能，按照相同方式从 https://atlasgo.io/skills/atlas-operator/SKILL.md 安装并阅读。该技能涵盖 operator 的安装、 令牌、资源策略和故障排查。

阶段 3 以及阶段 4 的 CI 部署作业还需要阅读 atlas-action 技能 （../atlas-action/SKILL.md）。如果缺少该技能，按照相同方式从 https://atlasgo.io/skills/atlas-action/SKILL.md 安装并阅读。该技能涵盖各个平台上的 Atlas CI 步骤、 所需令牌和权限，以及每个失败步骤的修复方法。

阶段

阶段	配置内容	阅读	完成条件
0 计划	登录、数据库清单、单元、试点和工作流	references/stage-0-plan.md	用户批准了单元、试点和工作流
1 将架构作为代码管理	atlas.hcl 和期望状态：导出为 SQL 或 HCL 的数据库，或 ORM 模型	references/stage-1-schema.md	atlas schema apply --env local --dry-run 报告无更改
2 迁移工作流	版本化：基线迁移和 migrate diff 循环。声明式：schema apply 循环	references/stage-2-workflow.md	版本化：atlas migrate diff 报告目录已同步；项目 PR 已创建
3 CI	在拉取请求上执行 lint（版本化）或计划（声明式），合并时推送到 Atlas Registry	references/stage-3-ci.md	合并时 CI 通过，且 Registry 中已有对应版本
4 部署到预发布环境	从 Registry 部署到预发布环境，并停止使用旧工具向预发布环境部署	references/stage-4-deploy.md	Atlas Cloud 记录了预发布环境部署
5 推广到生产环境	生产环境仅应用预发布环境正在运行的版本（环境推广）	references/stage-5-promote.md	用户在预发布环境所用的版本上执行了首次生产部署

先为试点单元执行各阶段。每个其他单元都根据已记录的决策重复阶段 1 到 5。试点完成后，交接。

规则

1. 检测，而非假设。每次会话开始时，运行 Detect the Stage。进度记录在默认分支、开放的拉取请求和 Atlas Cloud 中，而不是对话里。
2. 读取数据库前先登录。退出登录时，atlas schema inspect 和 atlas schema diff 会跳过视图、函数、存储过程、触发器和其他对象，但仍以 0 退出。以这种方式导出的架构会丢失这些对象。跳过提示每台机器只显示一次，因此没有看到提示并不能证明什么。先运行 atlas whoami。
3. 仅在各阶段列出的决策点提问。其他情况下，采用所述默认选项，并说明采用了哪一项。
4. 为拉取请求首次写入文件前，从最新的默认分支创建分支 atlas-onboard/<unit>-<stage>，并确保工作树干净。第 2 阶段继续使用第 1 阶段的分支，因为两者都会进入项目拉取请求；之后每个阶段都从自己的分支开始。按路径暂存文件，绝不要运行 git add -A。每项更改都通过拉取请求提交，拉取请求是审核关卡。单独的 GitOps 仓库需要自己的拉取请求。
5. 共享环境的凭据绝不能进入对话。用户应在启动 Agent 的 Shell 中导出这些 URL 变量；! 命令会将值放入对话中。使用 test -n "$STAGING_DATABASE_URL" && echo set 检查变量。绝不要打印、解析或回显此类 URL，也绝不要打开 .env、*.tfvars 或其他机密文件。仓库中定义的本地开发凭据（例如 compose 服务的密码）不属于机密。
6. 每个阶段结束时都进行检查：显示命令及其输出。如果检查无法运行（变量未设置、Docker 未运行、没有网络），这不代表阶段失败：修复前置条件并重新运行检查。
7. 在操作过程中进行说明。首次使用 Terms 中的每个术语时，用一句话定义。每个阶段结束后，用两三句话说明现在有哪些内容，以及其作用，并链接到 Docs Map 中的页面。
8. 从本地或开发数据库读取架构，Agent 可以自行查找并连接。只有在用户提出要求并提供连接信息时，才读取远程环境；绝不要查找远程 URL 或凭据。不建议将 Agent 连接到生产数据库。对于远程环境，建议使用只读角色，并在数据库支持时通过云端登录（第 1 阶段“远程数据库”）。

权限

操作	规则
仓库扫描、schema inspect、migrate lint、atlas cloud 读取、--dry-run（仅生成计划，不进行任何更改）	运行
在仓库中写入文件、创建分支和拉取请求	运行；拉取请求是关卡
创建 Atlas Cloud 仓库（首次运行 migrate push 或 schema push，或使用 create-repo 操作）、Bot 令牌、CI 机密	先询问
对本地数据库或 docker:// 开发数据库以外的任何目标运行 migrate apply 或 schema apply	先取得明确批准、指定目标并进行试运行
生产部署配置	仅在用户提出要求时，通过单独的拉取请求提交
批准任何计划、审核、部署、工作流运行或拉取请求	绝不批准；告知用户待处理事项及其位置

项目布局

每个单元都是一个独立目录中的 Atlas 项目，位于负责该单元的代码旁边（例如 services/billing/db/）。只有一个单元的仓库可以使用根目录。单元目录中包含 atlas.hcl、期望状态（schema/，除非来源是 ORM），以及版本化单元的迁移目录（migrations/）。每个 atlas.hcl 使用相同的环境名称，因此 Atlas Cloud 显示的是真实环境名称：

环境	用途	编写于
local	从中读取架构的本地或开发数据库，开发者在此应用变更；生成和检查迁移	阶段 1
staging	部署到预发布环境；首次部署前进行只读检查	阶段 4（仅当从预发布环境读取架构时为阶段 1）
ci	在 CI 中检查并推送到注册表	阶段 3
prod	从预发布环境晋级的生产部署	阶段 5

从单元目录运行每条 Atlas 命令。

确定阶段

1. 运行 atlas whoami。如果失败，请让用户登录，然后继续。
2. 运行 git fetch origin。从默认分支读取以下文件 （git show origin/<default>:<path>），而不是从工作区读取。
3. 查找之前会话留下的未完成工作：git branch -r --list 'origin/atlas-onboard/*' 和未合并的 PR（如果已安装，则运行 gh pr list 或 glab mr list；否则询问用户）。如果存在未合并的分支，请在该分支上继续，而不是另开一个分支。
4. 重新运行阶段 0（0.1）中针对 CI 系统和部署工具的扫描项。这些项不需要数据库。
5. 对于 .atlas-onboarding.json 中的每个单元，先检查 pilot，找出最后完成的阶段。从阶段 5 开始向下检查；第一个通过的检查即为最后完成的阶段。该单元在 deferred 下列出的阶段视为已完成。

阶段	完成条件
5	prod 环境从预发布环境晋级（to_version、src 中的 version，或 deny 检查），且 atlas cloud migration list --repo <repo> --env-name prod --status PASSED 列出了部署
4	atlas cloud migration list --repo <repo> --env-name staging 显示 PASSED 或 NO_ACTION，对应的版本由 atlas migrate ls --dir atlas://<repo> --latest --short 打印
3	默认分支上的工作流为该单元运行 Atlas 检查（版本化）或计划（声明式），且默认分支上的最近一次推送运行已通过
2	项目 PR 已合并：atlas.hcl 和来源位于默认分支上，版本化单元的 migrations/atlas.sum 也已位于该分支上
1	单元的 atlas.hcl 和来源存在于其引导分支上，且 atlas schema apply --env local --dry-run 报告无变更
0	该单元已列入 .atlas-onboarding.json

检查清单

将此内容复制到对话中，并在完成项目时勾选：

Stage 0  [ ] scan  [ ] atlas login  [ ] inventory  [ ] units + pilot (user)  [ ] workflow (user)
Stage 1  [ ] atlas.hcl  [ ] desired state (export or ORM)  [ ] dry run: no changes
Stage 2  [ ] baseline (versioned)  [ ] new local database from the directory (versioned)  [ ] change loop shown  [ ] lint shown (versioned)  [ ] project PR
Stage 3  [ ] bot token + secret (user)  [ ] first push (ask)  [ ] CI PR  [ ] green run  [ ] CI pushed the merge
Stage 4  [ ] cutover plan  [ ] deploy config PR  [ ] staging dry run  [ ] staging deployment recorded
Stage 5  [ ] prod env with promotion (when asked)  [ ] prod deploy behind approval  [ ] first prod deploy (user)
Hand off [ ] AGENTS.md  [ ] skill in repo  [ ] next steps  [ ] summary + next unit

决策文件

仓库根目录中的 .atlas-onboarding.json 仅保存仓库本身无法体现的信息。直接更新该文件，并在做出变更的阶段所对应的 PR 中提交。

{
  "workflow": "versioned",
  "units": [
    { "name": "identity", "dir": "services/identity/db", "repo": "identity", "schemas": ["identity"], "pilot": true },
    { "name": "billing", "dir": "services/billing/db", "repo": "billing", "schemas": ["billing"] }
  ],
  "deploy": { "target": "argocd", "gitops_repo": "github.com/acme/gitops" },
  "deferred": [{ "unit": "billing", "stage": 4, "reason": "deployments are owned by the platform team" }]
}

workflow 的值为 versioned 或 declarative。repo 是注册表仓库的标识。切勿在此文件中保存数据库 URL、令牌或状态：状态应以以上检查结果为准。

术语

• 期望状态：应有的架构，以 SQL、HCL 或 ORM 模型编写。两种工作流都从它开始。
• 版本化工作流：atlas migrate diff 将对期望状态的每项更改写入一个迁移文件，经过审核后按顺序应用。声明式工作流：不创建迁移文件；atlas schema plan 和 atlas schema apply 针对目标数据库规划每项更改，并审核计划。
• 开发数据库：Atlas 用作沙盒以规划和检查更改的临时隔离数据库，通常是短暂运行的 Docker 容器（https://atlasgo.io/concepts/dev-database#introduction）。它从不存储数据，也不是应用程序的开发数据库。
• 基线：版本化单元的第一个迁移文件，是现有架构的快照。现有数据库会将其记录为已应用，而不会运行它。
• 单元：一个 Atlas 项目、一个架构，或一个团队负责的一组表。试点：第一个单元，在其他单元之前走完所有阶段。
• Atlas Registry：Atlas Cloud 中的迁移目录或架构副本，由 CI 推送，部署时从中读取。
• Bot 令牌：用于 CI 的 Atlas Cloud 凭据，不与任何个人绑定。
• 环境晋级：生产环境只应用已部署到暂存环境的版本。

交接

当试点完成第 5 阶段，或用户希望完成的最后一个阶段时：

1. 在 AGENTS.md 中添加一个 Atlas 部分；如果文件不存在，则创建它。如果仓库中有 CLAUDE.md，则在其中添加一行 @AGENTS.md。

   ## Database schema (Atlas)
   
   - Unit `<unit>` in `<dir>`: `atlas.hcl`, desired state in `schema/` (or the ORM models), migrations in
     `migrations/`. Run Atlas from `<dir>`.
   - Change the desired state, then run `atlas migrate diff --env local <name>`. A new file in `schema/`
     needs an `-- atlas:import` line at the top of `schema/main.sql`.
   - Never edit an applied migration. After editing an unapplied one, run `atlas migrate hash --env local`.
   - Before opening a PR: `atlas migrate lint --env local --latest 1`.
   - Deployments run from <CI workflow or GitOps target>, staging first, then production promoted from
     staging. Never run `migrate apply` or `schema apply` against a shared database from a laptop.
   - Use the `atlas` skill for schema work.
   

   对于声明式单元，变更步骤为：修改期望状态，然后针对本地数据库运行 atlas schema apply --env local；CI 会为 PR 规划变更以供审核。对于 PostgreSQL， 最后一行需列出两项技能：Use the atlas and atlas-postgres skills for schema work. 对于 MySQL 和 MariaDB，则改为列出 atlas-mysql。

2. 提议提交这些技能，让每位队友的 Agent 都能使用：

   • Claude Code：将这些键合并到 .claude/settings.json。Claude Code 会为每位信任该仓库文件夹的队友安装 Atlas 插件。

     {
       "extraKnownMarketplaces": {
         "ariga": { "source": { "source": "github", "repo": "ariga/atlas" } }
       },
       "enabledPlugins": { "atlas@ariga": true }
     }
     

   • Codex、Cursor、GitHub Copilot：从仓库根目录运行 npx skills add ariga/atlas -a <agent> -y，并将 codex、cursor 或 github-copilot 作为 <agent>，然后提交 .agents/skills/ 和 skills-lock.json。如果安装时已将它们放在那里，则原样提交。

3. 后续步骤：根据扫描结果，逐项提议指南中适用的实践。完整列表见 https://atlasgo.io/guides/evaluation/advanced-topics。

   实践	指南
   生产环境只应用经过审核和批准的迁移	https://atlasgo.io/guides/reviewed-approved-migrations
   通过弃用工作流，在 CI 中阻止意外删除	https://atlasgo.io/guides/destructive-change-policy
   在部署时及部署之间检测漂移	https://atlasgo.io/guides/drift-detection
   测试函数、视图、触发器和数据迁移	https://atlasgo.io/testing/schema
   在 PostgreSQL 中以锁安全的方式进行 NOT NULL 更改	https://atlasgo.io/guides/lock-safe-not-null
   团队只能更改自己负责的对象	https://atlasgo.io/guides/schema-ownership
   将角色、权限和行级安全策略作为代码管理	https://atlasgo.io/guides/security-as-code
   为每个租户一个数据库的架构分阶段推出	https://atlasgo.io/guides/database-per-tenant/rollout

4. 按阶段总结：当前已有的内容、对应的文档页面、推迟了哪些内容及原因，以及还剩下哪些单元。对于下一个单元，用户再次运行此技能；Detect the Stage 会从第 1 阶段开始。

文档地图

阶段	阅读
0	连接，选择工作流，声明式与版本化
1	验证 Atlas 并导出架构，将架构作为代码，开发数据库，ORM 指南
2	设置迁移工作流，架构变更工作流，迁移检查
3	数据库 CI/CD，版本化 CI/CD，声明式 CI/CD
4	Atlas Cloud 中的部署，部署指南，现有数据库
5	环境晋级，声明式环境晋级

注意事项

• atlas.hcl 中的组织固定设置仅保护会读取该文件的命令（--env）。直接使用 --url 的命令会在未登录状态下运行，因此请在运行前执行 atlas whoami。
• 命令行中的 --exclude 会替换环境的 exclude 列表，而不是在其基础上追加。请将排除项 保留在环境中，并在使用 --env 时不要传入 --exclude。
• 排除模式遵循 URL 的作用域。对于架构作用域的 URL，模式指定该架构中的对象：表使用 audit_*，所有函数使用 *[type=function]。对于数据库作用域的 URL， 第一段指定架构：public.audit_*、public.*[type=function]，或者使用 internal 跳过整个 架构。
• 开发数据库必须与目标数据库的引擎版本和作用域一致（https://atlasgo.io/concepts/dev-database）。 作用域不正确会导致 modify schema "<name>" is not allowed when migration plan is scoped to one schema 错误，或静默丢弃扩展。
• 如果每张表都存在相同差异（排序规则、字符集、所有者），说明开发数据库的默认值与目标数据库不同。 请修正开发数据库；不要为此编写迁移。
• 拆分的 SQL 源（schema/main.sql 加上每个对象一个文件）只会读取 main.sql 导入的文件。 新文件需要在 main.sql 顶部的指令块中添加一行 -- atlas:import <path>，且该行前不能有空行； 否则该文件会被忽略，migrate diff 会报告没有变更。
• 如果某个环境通过 getenv() 读取变量时出现 Error: missing scheme，说明 Agent 的 shell 中未设置该变量，并不表示某个阶段失败。
• 如果没有基线版本，在现有数据库上首次运行 migrate apply 会因 connected database is not clean 而中止。请设置 baseline；不要使用 --allow-dirty 绕过此问题。
• Codex 默认在 workspace-write 沙箱中运行命令，且在用户批准前无法访问外部网络。 Atlas 需要通过网络访问 Atlas Cloud 和数据库，因此在检测阶段前，请请求用户批准 Atlas 命令 或启用网络访问。
• 云端 Agent 发起的拉取请求可能要等人工批准后才会运行 CI。如果有检查正在等待批准，请告知用户。