权限迁移报错主因是脚本逻辑、上下文或环境问题，而非sql语法错误；需用migration script法将权限作为可版本化、可回滚、可验证的代码管理，严格规范命名（时间戳+语义+up/down成对）、自包含内容（显式schema、角色存在性判断、变量占位）、执行前语法校验，并避免重复执行与活跃会话冲突。
权限迁移报错，多数不是SQL语法错，而是脚本执行逻辑、上下文缺失或环境不匹配导致的。用 Migration Script 脚本法，核心是把权限当作“可版本化、可回滚、可验证”的代码来管理，而不是零散命令。
脚本命名与结构必须严格规范
每个权限变更必须成对存在：.up.sql（创建/授权）和 .down.sql（撤销/清理）。文件名带时间戳+语义，例如：
- 1692405672_create_api_reader_role.up.sql —— 创建角色并授予 SELECT 权限
- 1692405672_create_api_reader_role.down.sql —— DROP ROLE（不是 REVOKE，避免残留）
不规范命名（如 test_perm.sql 或 1.sql）会导致迁移工具无法排序、跳过或重复执行，是报错高频原因。
脚本内容要自包含，不依赖外部状态
常见错误：脚本里直接写 GRANT SELECT ON users TO api_reader;，但没检查 api_reader 是否已存在，也没处理 schema 名称。正确写法需前置判断或兜底：
- 显式指定 schema：用
GRANT SELECT ON TABLE public.users TO api_reader;，避免 search_path 不一致导致对象找不到 - 角色创建不依赖 CREATE USER 自动触发：先
DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = 'api_reader') THEN CREATE ROLE api_reader; END IF; END $$; - 避免硬编码密码或 host：用变量占位（如
{APP_ENV}），通过工具注入，而非写死在 SQL 中
执行前必须校验脚本合法性
Migration 工具（如 golang-migrate、Laravel Migrator、Flyway）不会解析 SQL 语义，只按顺序执行。所以脚本本身要能独立通过语法检查：
- 用
psql -v ON_ERROR_STOP=1 -f script.up.sql手动预跑，看是否报错（如对象不存在、权限不足） - 检查是否有跨库引用（如
GRANT ... ON database_x.table_y）—— PostgreSQL 不支持跨库授权，会静默失败 - MySQL 用户注意：
SHOW GRANTS FOR 'u'@'h'输出中含USAGE或已删库的权限项，导入前应grep -v "USAGE\|ON.*nonexistent_db"过滤
失败后别重试，先查迁移状态与锁
报错后直接 rerun 脚本极易引发冲突。应优先确认：
- 迁移表（如
schema_migrations或migrate_version）是否已记录该版本？避免重复执行 - 目标库是否存在长事务或锁表操作？用
SELECT * FROM pg_stat_activity WHERE state = 'active';查阻塞源 - 权限类脚本常因角色正在被会话使用而失败（PostgreSQL 报 ERROR: role "xxx" is being used by active session），需先
pg_terminate_backend(pid)
