docs: explain deployment stages and separate comment sections [skip ci]

This commit is contained in:
2026-11-17 00:01:26 +08:00
parent 00fd89af1a
commit 53bc8d73eb
7 changed files with 123 additions and 0 deletions
+19
View File
@@ -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],