SuperAPI AI 工具集

atlas-postgres

数据与分析

查看项目

更新于 11-04 16:18

技能介绍

用途

Atlas for PostgreSQL 技能用于补充基础的 Atlas 技能,专门说明在 PostgreSQL 上管理 schema 时的差异点:规则、边界情况和常见问题的答案。基础 atlas 技能负责工作流和命令,本技能负责 PostgreSQL 特有的部分。对 PostgreSQL 兼容引擎(如 CockroachDB、YugabyteDB、Aurora DSQL),行为存在差异,应参考各自的指南(https://atlasgo.io/databases)。

文件结构

本技能由 SKILL.md 和 references/ 下的七个参考文件组成,分别在 https://atlasgo.io/skills/atlas-postgres/references/<name> 提供:

  • references/dev-database.md:开发 URL 及其作用域、atlas tool docker、docker 块与基线、扩展、RDS、Cloud SQL、Supabase、Neon、Azure、连接 URL。
  • references/security.md:角色与用户、GRANT 与 REVOKE、ALTER DEFAULT PRIVILEGES、所有权、行级安全、托管服务商管理员角色。
  • references/objects.md:序列、serial 与 identity 列、枚举、域、列类型变更、函数、触发器、视图、分区、索引,以及 Atlas 不管理的对象。
  • references/hcl.md:用 HCL 编写 schema,包括 NOT NULL 默认值、列类型与 sql()、默认值、引用、键、索引、表设置、函数体、种子数据、输入变量。
  • references/migrations.md:锁与并发索引、PG* lint 发现、事务、连接池、锁安全的 NOT NULL、种子数据。
  • references/custom-rules.md:当没有分析器覆盖某检查时,用 HCL 规则语言编写自定义 lint 规则,包括谓词、运算符、各 PostgreSQL 对象暴露的属性及示例。
  • references/testing.md:测试每次变更,包括函数、触发器、视图、域、策略的 schema 测试,带种子行的迁移测试,行级安全测试,模板数据库,pgTAP。

前置要求

需要基础 atlas 技能,安装在本技能旁边(../atlas/SKILL.md)。若缺失,需下载 https://atlasgo.io/skills/atlas/SKILL.md 到 ../atlas/SKILL.md,并将其 Files 部分列出的每个参考文件下载到 ../atlas/references/<name>。

使用方式与规则要点

先运行 atlas whoami 检查登录状态。若未登录,需让用户运行 atlas login:未登录时 Atlas 会遗漏 PostgreSQL schema 的大部分内容,检查会静默跳过视图、函数、触发器、序列、扩展、分区和策略,且声明这些对象的期望状态会报错提示仅登录用户可用。无账号用户可通过 atlas login 开始免费试用。

URL 作用域需根据 schema 所含对象选择:schema 作用域(URL 带 search_path)管理单个 schema 并写不带限定的语句(users);database 作用域(无 search_path)覆盖所有 schema 并限定每条语句(public.users)。数据库级对象不属任何 schema:扩展、事件触发器、外部服务器,schema 作用域 URL 看不到它们且会静默略过,因此声明这些对象的 schema 必须使用 database 作用域。schema 级对象在两种作用域下都可用。角色和用户是集群级的,管理它们需要 database 作用域。

开发 URL 采用目标的作用域。开发数据库应运行目标的主版本和扩展:docker://postgres/<version>/dev。schema 使用但不管理的对象(如扩展、服务商角色、其它团队的 schema)应放在 docker 块基线中创建。切勿将开发指向真实环境的数据库。

期望状态中的 ALTER DEFAULT PRIVILEGES 不会出现在迁移中:Atlas 在开发数据库上运行它,并为其覆盖的每个对象规划一条 GRANT。需放在这些对象之前,且不带 FOR ROLE。管理角色需要 database 作用域和 mode { roles = true };Atlas 不应改动的角色标记 external = true,并在开发基线中创建授权所引用的外部角色。托管服务上应排除服务商的管理员角色。

在已有数据的表上并发构建和删除索引:使用 concurrent_index diff 策略,或以 -- atlas:txmode none 开头的手写文件。迁移文件中不要写 BEGIN 或 COMMIT,除非设置为 txmode none,否则 Atlas 会在事务中运行每个文件。添加 CHECK 约束和外键时用 NOT VALID,再在单独事务中验证(txmode none 文件或后续文件)。大表使用锁安全的 NOT NULL 策略。

迁移应通过直连应用,切勿经由事务模式连接池(如 Supabase 事务池 6543 端口、Neon 的 -pooler 端点、事务模式 PgBouncer),因为 Atlas 为运行持有的建议锁是会话级的,这些池会丢弃它。

部分变更需手工编辑生成的迁移:PostgreSQL 无法隐式完成的转换(如 text 到 integer 或 uuid)需要 USING 子句;有数据的列转为 serial 需要 setval,否则插入会因主键重复失败;serial 转 bigserial 需要 ALTER SEQUENCE ... AS bigint;新的枚举值放在一个文件中,其首次使用放在后续文件;删除或重排枚举值需手写迁移,其计划可能报告无变更。

每次变更完成前都应测试:运行 atlas schema validate,为新增或修改的函数、触发器、视图、域、检查或策略添加 test "schema" 用例,为移动或转换数据的迁移添加带种子行的 test "migrate" 用例,并用 atlas schema test 和 atlas migrate test 运行。

当内置分析器未覆盖某检查时,用 HCL 规则语言编写自定义 lint 规则;对用户声明的约定(如每张表开启行级安全、每个外键建索引)也同样处理。规则可检查 Atlas 检查的任何对象的任何属性,lint 会在每次变更时强制执行。

适用场景

适用于使用 Atlas 对 PostgreSQL 进行声明式或版本化 schema 管理的开发与运维工作,尤其是涉及视图、函数、触发器、扩展、分区、行级安全、角色授权、并发索引和大表迁移等需要特别处理细节的场景。

限制

本技能依赖基础 atlas 技能及 Atlas 登录状态;未登录时部分对象会被静默跳过,期望状态可能报错。PostgreSQL 兼容引擎的行为与本技能所述不同,需参考各自指南。迁移必须走直连而非事务模式连接池。部分变更(如枚举值删除、分区键变更)需手写迁移,Atlas 不会自动规划。所有者不属于期望状态。技能资料未提供收费、价格或平台支持范围等信息,相关内容暂未提供。