Atlas 是一个基于 Atlas CLI 的数据库架构管理技能,其内容包括 SKILL.md 以及 references/ 下的九个参考文件:schema-sources.md、versioned.md、declarative.md、cicd.md、lint.md、testing.md、drift.md、cloud.md 和 scripts.md。这些文件按任务需要按需读取,各参考文件可从 https://atlasgo.io/skills/atlas/references/<name> 获取。
用途 Atlas 用于数据库架构管理、迁移、数据脚本和 Atlas Cloud 相关操作。主要场景包括:生成或应用迁移、比较架构差异、校验架构定义、执行 lint 与测试、检测数据库漂移、运行数据迁移脚本,以及查询 Atlas Cloud 中的部署和数据库状态。
安全与配置 资料强调不要硬编码凭据,应在 atlas.hcl 中使用环境变量,例如:
env "prod" { url = getenv("DATABASE_URL") }
所有命令都应带上 --env <name> 参数,使数据库 URL 保留在 atlas.hcl 中,不进入对话。使用前应先阅读项目中的 atlas.hcl,了解环境名称。
主要能力与常用命令 安装与登录:atlas version 查看版本,atlas whoami 查看登录状态和组织,atlas login 用于 lint、test、drift、plan、scripts、schema lint 及 cloud 等需要登录的命令。
架构操作:atlas schema inspect 检查当前架构,atlas schema validate 校验语法与语义,atlas schema diff 比较在线数据库与目标架构,atlas schema lint 与 atlas schema test 用于策略检查和逻辑测试。
声明式工作流:atlas schema plan 预生成变更计划供审阅,atlas schema apply --dry-run 预览变更,atlas schema apply 应用变更。声明式方式不生成迁移文件,适合开发阶段的快速迭代。
版本化工作流:atlas migrate diff 生成迁移,atlas migrate lint 检查最新迁移,atlas migrate test 测试迁移,atlas migrate apply 预览或应用迁移,atlas migrate status 查看数据库与迁移目录的差异,atlas migrate down 预览回滚,atlas migrate hash 在手动编辑后重算 atlas.sum,atlas migrate new 创建空迁移文件,atlas migrate checkpoint 压缩历史,atlas migrate rebase 重定基迁移,atlas migrate push 推送到 Atlas Registry。
Lint 与测试:迁移 lint 可发现破坏性变更(DS*)、依赖数据的变更(MF*)、向后不兼容变更(BC*)、表锁与重写(MY*、PG*)、命名与归属策略以及自定义 HCL 规则。策略配置位于 atlas.hcl 的 lint 块。未应用的迁移可直接修改文件后运行 atlas migrate hash;已应用的迁移应创建修正迁移,不直接编辑。
漂移检测:atlas migrate drift 检查数据库与迁移历史是否一致,漂移时退出码为 1,适合定时任务;atlas schema diff 可比较任意两个状态;atlas.hcl 中可通过 check "migrate_apply" { drift { on_error = FAIL } } 在部署前阻止漂移目标;Atlas Cloud 提供基于代理的持续监控与告警。
Atlas Cloud:atlas cloud repo list 查看注册表仓库及同步状态计数,atlas cloud database list --env-name 查看受跟踪数据库及状态,atlas cloud migration list --status FAILED 查看失败部署,atlas schema plan list --pending 查看待审批计划。
数据脚本:atlas script exec 执行事务性变更,atlas script query 执行读取或报告,atlas script loop 执行批量回填或清理,atlas script test 在开发数据库上测试脚本。
使用方式与工作流选择 如果请求是架构变更,项目已有 migrations/ 目录或 atlas.hcl 中有 migration 块,则采用版本化工作流:migrate diff → lint → test → apply;否则采用声明式工作流:schema apply --dry-run → apply。若变更需要审阅批准后再执行,可使用 schema plan(声明式)或带 migrate lint 的 PR(版本化)。本地数据库快速迭代可使用 schema apply --auto-approve。
标准流程为:atlas schema inspect 了解当前状态;编辑架构文件;atlas schema validate 检查语法;atlas migrate diff 生成迁移;atlas migrate lint --latest 1 校验;atlas migrate test 测试;如有问题修改迁移后运行 atlas migrate hash;最后 atlas migrate apply --dry-run 预览再应用。
开发数据库 Atlas 使用临时开发数据库处理与校验架构。开发数据库 URL 的作用域应与目标匹配:管理单个架构时使用 schema 作用域,例如 docker://postgres/17/dev?search_path=public;管理多个架构、扩展或事件触发器时使用 database 作用域。作用域错误可能导致 "modify schema "public" is not allowed when migration plan is scoped to one schema" 等错误,或静默丢弃数据库级对象。PostGIS 或 pgvector 架构应使用对应镜像,如 docker://postgis/latest/dev 或 docker://pgvector/pg17/dev。若架构依赖扩展,可通过 docker 块配置 baseline。
限制与注意事项 资料说明,atlas schema inspect 和 atlas schema diff 在未登录时会跳过视图、函数、存储过程、触发器、序列、扩展等对象,但仍以 0 退出,输出看似完整却并不完整,因此执行这些操作前应运行 atlas whoami,必要时提示用户登录。需要登录的命令会以 "command requires 'atlas login'" 或仅限 Atlas Pro 用户的提示失败,此时应告知用户该步骤被跳过及原因,并继续其余步骤。资料未提供定价、价格、平台支持范围或独立图形界面的详细信息。