docs: explain deployment stages and separate comment sections [skip ci]
This commit is contained in:
@@ -1,5 +1,6 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Apply checked migrations atomically from the trusted deployment runner."""
|
||||
|
||||
# 部署 runner 入口:组合所有尚未执行的迁移及授权为单个外层事务,失败整体回滚。
|
||||
# db/*.sql 的校验和覆盖原始注释;历史文件不可仅为加注释而改写,中文对象说明见 docs/database-comments.sql。
|
||||
import argparse
|
||||
@@ -18,6 +19,9 @@ args = parser.parse_args()
|
||||
for value in (args.database, args.role):
|
||||
if not re.fullmatch(r"[a-z_][a-z0-9_]{0,62}", value):
|
||||
raise SystemExit("Invalid deployment database or role")
|
||||
|
||||
# 从本脚本位置定位 db/,避免调用目录影响迁移来源;文件名的排序也是版本执行顺序。
|
||||
# 编号命名需延续现有约定,运行脚本会真正访问数据库,不是生成预览文件。
|
||||
migrations = sorted((Path(__file__).resolve().parent.parent / "db").glob("[0-9]*.sql"))
|
||||
if not migrations:
|
||||
raise SystemExit("No migrations found")
|
||||
@@ -31,16 +35,22 @@ script = [
|
||||
"CREATE TABLE IF NOT EXISTS foundry_schema_migrations "
|
||||
"(name text PRIMARY KEY, checksum text NOT NULL, applied_at timestamptz NOT NULL DEFAULT now());",
|
||||
]
|
||||
|
||||
# 迁移清单记录文件名和原文摘要;tables 收集源码中显式 CREATE TABLE 的对象用于后续 DML 授权。
|
||||
# 这是按受信任 SQL 的既有写法提取,不是通用 SQL 解析器。
|
||||
tables = set()
|
||||
for index, path in enumerate(migrations):
|
||||
source = path.read_text()
|
||||
name = path.name
|
||||
if not re.fullmatch(r"[0-9]+-[a-z0-9-]+\.sql", name):
|
||||
raise SystemExit("Invalid migration name")
|
||||
|
||||
# 原文 SHA-256 与已执行记录逐字匹配,禁止同名历史迁移在部署后被静默修改。
|
||||
checksum = hashlib.sha256(source.encode()).hexdigest()
|
||||
tables.update(re.findall(r"CREATE TABLE ([a-z_]+)", source))
|
||||
|
||||
# The first deployed version predates migration tracking.
|
||||
# 第一批历史部署没有迁移账本:只有四张认证基线表都存在才认领首迁移,避免把部分初始化误判完整。
|
||||
if index == 0:
|
||||
script.extend([
|
||||
"SELECT bool_and(to_regclass('public.' || name) IS NOT NULL) AS baseline FROM "
|
||||
@@ -49,6 +59,8 @@ for index, path in enumerate(migrations):
|
||||
f"INSERT INTO foundry_schema_migrations(name,checksum) VALUES('{name}','{checksum}') ON CONFLICT DO NOTHING;",
|
||||
"\\endif",
|
||||
])
|
||||
|
||||
# psql 的 applied/valid 变量决定跳过或执行:同名已执行但摘要不同直接退出,不重放修改过的历史 SQL。
|
||||
script.extend([
|
||||
f"SELECT EXISTS(SELECT 1 FROM foundry_schema_migrations WHERE name='{name}') AS applied, "
|
||||
f"EXISTS(SELECT 1 FROM foundry_schema_migrations WHERE name='{name}' AND checksum='{checksum}') AS valid \\gset",
|
||||
@@ -60,15 +72,19 @@ for index, path in enumerate(migrations):
|
||||
"\\endif",
|
||||
"\\else",
|
||||
])
|
||||
|
||||
# 每份源文件显式 BEGIN/COMMIT;去除内层边界后放入外层统一事务,而非逐文件部分提交。
|
||||
source = source.strip()
|
||||
if not source.startswith("BEGIN;") or not source.endswith("COMMIT;"):
|
||||
raise SystemExit("Migration must have explicit transaction boundaries")
|
||||
|
||||
# 剥掉的是各文件最外层 BEGIN/COMMIT,正文保持不变;最终与账本登记和角色授权同一个事务提交。
|
||||
script.append(source[len("BEGIN;"):-len("COMMIT;")])
|
||||
script.extend([
|
||||
f"INSERT INTO foundry_schema_migrations(name,checksum) VALUES('{name}','{checksum}');",
|
||||
"\\endif",
|
||||
])
|
||||
|
||||
# 从受信任源码的 CREATE TABLE 清单补应用 DML 权限;identity 序列另授予使用/读取权限。
|
||||
for table in sorted(tables):
|
||||
script.append(f'GRANT SELECT,INSERT,UPDATE,DELETE ON TABLE "{table}" TO "{args.role}";')
|
||||
@@ -76,7 +92,10 @@ script.extend([
|
||||
f'GRANT USAGE,SELECT ON SEQUENCE link_clicks_id_seq TO "{args.role}";',
|
||||
"COMMIT;",
|
||||
])
|
||||
|
||||
# SQL 经标准输入交给容器内 psql,不把数据库密码或整段 SQL 拼成 shell 命令参数。
|
||||
# Docker 在服务器的 PostgreSQL 容器中运行 psql,POSTGRES_USER 由容器环境提供。
|
||||
# check=True 将非零退出码传播为部署失败;迁移脚本自身不会启动/切换 Core 容器。
|
||||
subprocess.run(
|
||||
["docker", "exec", "-i", args.container, "sh", "-c",
|
||||
'exec psql -X -U "${POSTGRES_USER:-postgres}" -d "$1" -v ON_ERROR_STOP=1', "sh", args.database],
|
||||
|
||||
Reference in New Issue
Block a user