[ { "id": "01", "title": "准备 PostgreSQL 与 psql 练习环境", "group": "连接与数据模型", "summary": "为 notes-service 建立独立练习库，区分数据库进程、数据库、角色与客户端。", "objectives": [ "启动 PostgreSQL 16 并创建非超级用户", "用 psql 明确连接地址、端口、角色和数据库", "区分连接失败、认证失败和 SQL 错误" ], "concepts": [ { "title": "服务端与客户端", "body": "PostgreSQL 进程负责保存数据和执行 SQL；psql 是向它发送命令的终端工具。关闭 psql 不会停止数据库。一个 PostgreSQL 实例可以包含多个数据库，连接时必须确定要进入哪个库。" }, { "title": "角色与数据库分别创建", "body": "角色表示谁在连接，数据库表示在哪里读写。练习的 app_user 是 notes_lab 所有者，但不是超级用户。第 11 课再拆分迁移角色与运行时角色，避免 API 进程拥有修改表结构的权限。" }, { "title": "实验边界", "body": "本模块所有命令都是学员在独立 notes_lab 中执行的练习，不是让你操作线上数据库。需要 Python 3.11+ 和已安装、启动的 Docker。此处只用容器获得一致的 PostgreSQL 16 环境；镜像、卷与容器网络在 Docker 模块系统学习。" } ], "steps": [ { "title": "建立项目与本机密码文件", "body": "以下为 Linux / macOS Bash 命令；Windows 可在 WSL 中执行。本节使用 127.0.0.1:5433，容器内部仍是 5432。密码只用于本机练习，不要提交到 Git。终端在 notes-service 中执行。", "code": "mkdir -p notes-service\ncd notes-service\numask 077\nprintf 'POSTGRES_PASSWORD=%s\\n' \"$(python3 -c 'import secrets; print(secrets.token_urlsafe(24))')\" > .postgres.env\nprintf '.postgres.env\\n.env\\nbackups/\\n.venv/\\n' >> .gitignore\ndocker run --name notes-postgres --env-file .postgres.env \\\n -p 127.0.0.1:5433:5432 \\\n -v notes_pgdata:/var/lib/postgresql/data -d postgres:16\ndocker exec notes-postgres pg_isready -U postgres", "lang": "bash" }, { "title": "创建练习角色和数据库", "body": "等待 pg_isready 显示 accepting connections。先执行 docker exec -it notes-postgres psql -U postgres -d postgres，然后在该 psql 中执行下列命令。\\password 会交互要求输入两遍 app_user 密码，不在 SQL 历史中直接写出密码。下面建库命令只执行一次。", "code": "CREATE ROLE app_user LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE;\n\\password app_user\nCREATE DATABASE notes_lab OWNER app_user;\n\\q", "lang": "sql" }, { "title": "用业务身份重新连接", "body": "执行 docker exec -it notes-postgres psql -h 127.0.0.1 -U app_user -d notes_lab -W，输入刚设置的密码。该命令在容器内访问容器的 5432。若本机已安装 psql，则使用 psql -h 127.0.0.1 -p 5433 -U app_user -d notes_lab -W。后续未特别标明的 SQL 都在此连接运行。", "code": "\\conninfo\nSELECT current_database(), current_user, version();\nSHOW server_encoding;\nSHOW TimeZone;\n\\set VERBOSITY verbose\n\\timing on", "lang": "sql" }, { "title": "验证持久化与 SQL 命令边界", "body": "运行两条 SELECT，观察分号用于结束 SQL，反斜杠命令由 psql 处理。退出客户端后重新连接，数据库仍存在。数据库卷保留了实例数据；不要为了重新做某节练习删除整个卷。", "code": "SELECT 6 * 7 AS answer;\n-- answer = 42\nSELECT current_database() = 'notes_lab' AS in_lab;\n-- in_lab = t\n\\q", "lang": "sql" } ], "checks": [ "current_database() 为 notes_lab，current_user 为 app_user。", "version() 显示 PostgreSQL 16，server_encoding 为 UTF8。", "退出并重新连接后 SELECT 6 * 7 仍能执行；数据库进程没有因客户端退出而停止。" ], "pitfalls": [ { "symptom": "connection refused", "cause": "容器未启动、端口尚未就绪或混用了宿主机与容器端口。", "fix": "用 docker ps 与 pg_isready 检查状态；本机使用 5433，docker exec 内部使用 5432。" }, { "symptom": "role app_user does not exist 或 password authentication failed", "cause": "创建角色步骤未执行，或输入的是 postgres 密码。", "fix": "使用管理连接检查 \\du；通过 \\password app_user 重设本机练习密码，再用业务身份重连。" } ], "exercise": { "task": "分别在一个正确连接和一个故意写错数据库名的连接中观察结果，记录错误发生在哪一层。", "hint": "将 notes_lab 暂时写成 notes_missing；不要真的创建这个库。", "answer": "正确连接能执行 SELECT；错误库名在连接阶段返回 database does not exist，SQL 尚未执行。连接地址错通常是网络层失败，密码错是认证失败，SELECT 1/0 则是连接成功后的 SQL 执行错误。" }, "refs": [ { "label": "PostgreSQL 16：psql", "url": "https://www.postgresql.org/docs/16/app-psql.html" }, { "label": "PostgreSQL 16：创建数据库", "url": "https://www.postgresql.org/docs/16/sql-createdatabase.html" }, { "label": "Docker：PostgreSQL 官方镜像", "url": "https://hub.docker.com/_/postgres" } ], "production": { "scenario": "新服务需要一个可重复创建、不会误连线上实例的开发数据库。", "decisions": [ "连接串明确包含数据库名与端口。", "先用非超级用户练习，环境文件加入忽略规则。", "生产环境选择受维护的 16.x 补丁版并锁定镜像摘要；postgres:16 是本课程环境入口。" ], "failureDrill": "在独立练习环境中用错误端口尝试连接，依据 pg_isready 与实际端口定位原因。", "acceptance": [ "能从连接信息确认当前实例和身份。", "数据库卷与容器用途可区分。", "仓库没有密码文件。" ] } }, { "id": "02", "title": "定义笔记表、数据类型与约束", "group": "连接与数据模型", "summary": "把 Python 对象转成有明确边界的数据表，让非法数据在数据库入口被拒绝。", "objectives": [ "建立 notes 表并理解主键", "选择 text、boolean 和 timestamptz", "通过 NOT NULL、CHECK 与默认值维护数据规则" ], "concepts": [ { "title": "列类型约束存储形式", "body": "bigint 存储整数编号，varchar(120) 限制标题字符数，text 存储正文。boolean 使用 true / false，不能用随意约定的字符串。时间使用 timestamptz 表示一个时间点，显示格式受会话时区影响。" }, { "title": "默认值与非空是两条规则", "body": "DEFAULT 只在插入时省略列或使用 DEFAULT 时生效；显式传 NULL 仍然是 NULL。NOT NULL 才拒绝空值，CHECK 再约束有效内容。应用校验改善错误提示，数据库约束保护所有写入入口。" }, { "title": "主键和生成编号", "body": "identity 自动提供编号，PRIMARY KEY 保证编号唯一且非空。编号用于定位，不保证连续，也不代表严格的业务提交顺序。updated_at 的默认值只在插入时生效，更新时需要显式修改或使用统一触发器。" } ], "steps": [ { "title": "确认连接后创建表", "body": "在第 01 课的 app_user / notes_lab 连接中执行。保存为 sql/001_notes.sql，首次运行一次；后续变更使用单独迁移文件，不要反复删表重建。", "code": "CREATE TABLE notes (\n id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,\n title varchar(120) NOT NULL CHECK (char_length(btrim(title)) > 0),\n content text NOT NULL DEFAULT '',\n pinned boolean NOT NULL DEFAULT false,\n created_at timestamptz NOT NULL DEFAULT now(),\n updated_at timestamptz NOT NULL DEFAULT now()\n);\n\\d notes", "lang": "sql", "filename": "sql/001_notes.sql" }, { "title": "插入合法数据并看默认值", "body": "本节写入的标题用 db02- 前缀，避免与后续实验混淆。RETURNING 在同一次写入中返回实际保存的行。记录生成的编号，但后续练习不依赖它必须从 1 开始。", "code": "INSERT INTO notes (title) VALUES ('db02-first')\nRETURNING id, title, content, pinned, created_at, updated_at;\n-- content 为空串，pinned 为 f，两列时间均非空\nSELECT count(*) FROM notes WHERE title = 'db02-first';", "lang": "sql" }, { "title": "让数据库拒绝非法数据", "body": "以下两条语句在 psql 默认自动提交状态逐条执行；预期分别失败，不要包进同一个 BEGIN 后继续运行。随后 count(*) 仍为 1。", "code": "INSERT INTO notes (title) VALUES (NULL);\n-- SQLSTATE 23502: not_null_violation\nINSERT INTO notes (title) VALUES (' ');\n-- SQLSTATE 23514: check_violation\nSELECT count(*) FROM notes WHERE title = 'db02-first';", "lang": "sql" }, { "title": "观察同一时间点的时区显示", "body": "这里改的是当前会话显示方式。UTC 与上海时间显示相差 8 小时，epoch 秒数相同。业务对外使用带时区 ISO 8601，不能在 Python 中去掉 tzinfo 后再猜测时区。", "code": "SET TIME ZONE 'UTC';\nSELECT created_at, extract(epoch FROM created_at) FROM notes WHERE title='db02-first';\nSET TIME ZONE 'Asia/Shanghai';\nSELECT created_at, extract(epoch FROM created_at) FROM notes WHERE title='db02-first';\nSET TIME ZONE 'UTC';", "lang": "sql" } ], "checks": [ "\\d notes 显示主键、identity、非空与标题 CHECK。", "省略 content 和 pinned 时得到默认值；显式 NULL 标题被拒绝。", "切换时区后显示不同，epoch 值保持一致。" ], "pitfalls": [ { "symptom": "UPDATE 后 updated_at 没变化", "cause": "DEFAULT now() 只参与插入。", "fix": "后续每次更新同时设置 updated_at=now()；多人维护时把规则收敛到统一写入层或触发器。" }, { "symptom": "空标题进入数据库", "cause": "只使用了 NOT NULL，空串不是 NULL。", "fix": "加入 btrim 与长度 CHECK，并在应用侧做一致校验；已有不合格数据需先清理。" } ], "exercise": { "task": "验证 121 个字符的标题被拒绝，再插入带单引号的合法标题。", "hint": "SQL 字面量中的单引号用两个单引号表示；Python 动态值在下一课使用参数化。", "answer": "INSERT INTO notes(title) VALUES(repeat('a',121)); 会触发长度错误。INSERT INTO notes(title) VALUES('db02-O''Reilly') RETURNING title; 返回 db02-O'Reilly。SQL 中的引号转义不替代 Python 驱动的参数化接口。" }, "refs": [ { "label": "PostgreSQL 16：约束", "url": "https://www.postgresql.org/docs/16/ddl-constraints.html" }, { "label": "PostgreSQL 16：日期时间类型", "url": "https://www.postgresql.org/docs/16/datatype-datetime.html" }, { "label": "PostgreSQL 16：生成列编号", "url": "https://www.postgresql.org/docs/16/sql-createtable.html" } ], "production": { "scenario": "同一张表将被 API、导入脚本和后台任务共同写入。", "decisions": [ "关键合法性规则落到数据库。", "编号只当标识符，不用于推算数据量。", "统一存时间点、在展示层选择时区。" ], "failureDrill": "向 notes_lab 提交空标题、NULL 和超长标题，逐条记录 SQLSTATE。", "acceptance": [ "非法行没有落库。", "合法写入能返回真实生成值。", "能说明 updated_at 的维护位置。" ] } }, { "id": "03", "title": "用参数化 SQL 完成增删改查", "group": "SQL 与关系建模", "summary": "从 Python 读写笔记，处理不存在的数据，并验证用户输入不会变成 SQL。", "objectives": [ "使用 psycopg 3 传递参数", "通过 RETURNING 判断实际写入结果", "用明确列名、过滤与排序控制查询" ], "concepts": [ { "title": "SQL 结构与参数分开传递", "body": "execute 的 SQL 字符串描述操作结构，第二个参数提供数据。值占位符统一写 %s，不自行加引号，也不用 f-string 拼接输入。表名、列名不能作为普通值参数传入，动态排序应使用固定白名单。" }, { "title": "写入结果要检查", "body": "UPDATE 或 DELETE 匹配不到数据通常不是 SQL 错误。RETURNING 返回零行能表示资源不存在；不要在未检查结果时声称修改成功。" }, { "title": "读取结果必须有边界", "body": "查询显式列名能稳定输出结构。列表查询需要 LIMIT 和确定排序，否则数据库不承诺返回顺序。id DESC 可作为当前课程按编号倒序的简单规则。" } ], "steps": [ { "title": "安装驱动与设置连接", "body": "在 notes-service 创建并激活 Python 3.11+ 虚拟环境，执行 python -m pip install \"psycopg[binary]>=3.2,<4\"。把实际解析版本写入 requirements-lock.txt。Linux 使用下面的 PG 环境变量，PGPASSWORD 在当前 shell 中交互输入，不写进脚本。正式环境使用密钥注入并避免输出连接串。", "code": "export PGHOST=127.0.0.1 PGPORT=5433 PGDATABASE=notes_lab PGUSER=app_user\nread -rsp 'Database password: ' PGPASSWORD\nprintf '\\n'\nexport PGPASSWORD\npython -m pip freeze > requirements-lock.txt", "lang": "bash" }, { "title": "保存并运行完整 CRUD 脚本", "body": "保存为 db_crud.py，再执行 python db_crud.py。connect(\"\") 读取 PG 环境变量；上下文正常退出提交，异常退出回滚。单元素参数必须带逗号。此脚本先创建自己的数据，最后删除同一行，可以重复执行。", "code": "import psycopg\nfrom psycopg.rows import dict_row\n\nwith psycopg.connect(\"\", row_factory=dict_row) as conn:\n created = conn.execute(\n \"INSERT INTO notes(title, content) VALUES (%s, %s) RETURNING id, title\",\n (\"db03-O'Reilly\", \"parameterized insert\"),\n ).fetchone()\n note_id = created[\"id\"]\n print(\"created\", created)\n print(\"read\", conn.execute(\n \"SELECT id, title, pinned FROM notes WHERE id = %s\", (note_id,)\n ).fetchone())\n print(\"updated\", conn.execute(\n \"UPDATE notes SET pinned = %s, updated_at = now() WHERE id = %s RETURNING id, pinned\",\n (True, note_id),\n ).fetchone())\n print(\"deleted\", conn.execute(\n \"DELETE FROM notes WHERE id = %s RETURNING id\", (note_id,)\n ).fetchone())\n print(\"missing\", conn.execute(\n \"SELECT id FROM notes WHERE id = %s\", (note_id,)\n ).fetchone())", "lang": "python", "filename": "db_crud.py" }, { "title": "提交一段看起来像 SQL 的标题", "body": "单独保存为 db_input.py 并运行。预期只插入一条普通笔记，输入里的 DROP TABLE 不会执行。finally 外层连接上下文会正常提交这个插入和删除的组合；最后 notes 表仍能查询。", "code": "import psycopg\n\npayload = \"db03-x'); DROP TABLE notes; --\"\nwith psycopg.connect(\"\") as conn:\n row = conn.execute(\n \"INSERT INTO notes(title) VALUES (%s) RETURNING id, title\", (payload,)\n ).fetchone()\n assert row[1] == payload\n print(row)\n conn.execute(\"DELETE FROM notes WHERE id = %s\", (row[0],))\n print(\"table exists\", conn.execute(\"SELECT count(*) FROM notes\").fetchone())", "lang": "python", "filename": "db_input.py" }, { "title": "练习有边界的列表查询", "body": "回到 psql 执行，记录结果列与顺序。修改 LIMIT 观察数量变化。对照 Python 中的写法：LIMIT 也可用 %s 传值，但应用应限制 1 到 100，不能让客户端请求任意数量。", "code": "SELECT id, title, pinned\nFROM notes\nWHERE pinned = false\nORDER BY id DESC\nLIMIT 10;\nUPDATE notes SET pinned = true WHERE id = -1 RETURNING id;\n-- 0 rows / UPDATE 0，不是 SQL 异常", "lang": "sql" } ], "checks": [ "CRUD 输出依次出现同一编号，最后 missing 为 None。", "含单引号和 SQL 片段的标题保持原样，notes 表仍存在。", "不存在编号的 UPDATE 返回零行；列表最多 10 行且编号递减。" ], "pitfalls": [ { "symptom": "syntax error 或用户输入改变了 SQL 含义", "cause": "把输入放进 f-string 或字符串拼接。", "fix": "恢复固定 SQL 和独立参数元组；不要手写通用转义函数。" }, { "symptom": "脚本输出成功但另一个连接查不到新增行", "cause": "事务尚未提交，或者最后主动删除了练习行。", "fix": "确认连接上下文已经退出；若只验证插入，暂时移除删除步骤后在独立连接核查。" } ], "exercise": { "task": "写一个只更新标题的函数，返回更新后的 id/title；不存在时返回 None。", "hint": "WHERE id = %s，并在同一 UPDATE 中 RETURNING id, title。", "answer": "def rename_note(conn, note_id, title):\n return conn.execute(\"UPDATE notes SET title=%s, updated_at=now() WHERE id=%s RETURNING id,title\", (title,note_id)).fetchone()\n调用方决定事务提交边界；函数不私自创建连接或提交。" }, "refs": [ { "label": "Psycopg 3：参数传递", "url": "https://www.psycopg.org/psycopg3/docs/basic/params.html" }, { "label": "Psycopg 3：基本使用", "url": "https://www.psycopg.org/psycopg3/docs/basic/usage.html" }, { "label": "PostgreSQL 16：RETURNING", "url": "https://www.postgresql.org/docs/16/dml-returning.html" } ], "production": { "scenario": "笔记标题来自浏览器，数据库不能把任何一段用户输入当成可执行语法。", "decisions": [ "参数化所有动态值。", "列表显式限制数量和排序。", "以 RETURNING 判断变更结果。" ], "failureDrill": "在 notes_lab 用包含单引号与 SQL 片段的标题创建笔记，核验原值与表完整性。", "acceptance": [ "没有 SQL 字符串插值。", "空结果有明确处理。", "连接与事务在脚本结束后释放。" ] } }, { "id": "04", "title": "用关联表、JOIN 与聚合表达关系", "group": "SQL 与关系建模", "summary": "为笔记添加标签，使用外键保证关联有效，再统计每条笔记的标签数量。", "objectives": [ "建立多对多关系和联合主键", "区别 INNER JOIN 与 LEFT JOIN", "避免 JOIN 重复行导致聚合错误" ], "concepts": [ { "title": "多对多关系单独建表", "body": "一条笔记可有多个标签，一个标签可属于多条笔记。note_tags 的每一行代表一组关联，联合主键阻止重复关联。将标签塞进逗号字符串会让检索、唯一性与改名都变得困难。" }, { "title": "外键检查关联完整性", "body": "note_id 必须对应真实笔记，tag_id 必须对应真实标签。此例删除笔记时级联清理关联行，删除仍被使用的标签则拒绝；删除策略来自业务，而不是所有外键统一加 CASCADE。" }, { "title": "聚合前先辨认行数", "body": "LEFT JOIN 会保留没有标签的笔记，并补一个右侧为空的连接结果。COUNT(*) 会把这一行算进去，COUNT(nt.tag_id) 只统计非空标签。聚合查询返回的是分组后的结果。" } ], "steps": [ { "title": "建立标签和关联表", "body": "在 notes_lab 首次执行一次；保存为 sql/002_tags.sql。引用 notes 主键，不复制标题。外键列并不会自动获得适合所有反向查询的索引，后续根据查询创建。", "code": "CREATE TABLE tags (\n id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,\n name varchar(40) NOT NULL UNIQUE CHECK (char_length(btrim(name)) > 0)\n);\nCREATE TABLE note_tags (\n note_id bigint NOT NULL REFERENCES notes(id) ON DELETE CASCADE,\n tag_id bigint NOT NULL REFERENCES tags(id) ON DELETE RESTRICT,\n PRIMARY KEY (note_id, tag_id)\n);", "lang": "sql", "filename": "sql/002_tags.sql" }, { "title": "准备两条笔记和两个标签", "body": "以下是 psql 脚本；\\gset 将 RETURNING 值写进本会话变量。创建笔记返回语句末尾不加分号，由 \\gset 执行。标签可以重复准备，笔记每次执行都会产生两条独立样本。", "code": "INSERT INTO notes(title) VALUES ('db04-with-tags') RETURNING id AS tagged_id \\gset\nINSERT INTO notes(title) VALUES ('db04-no-tags') RETURNING id AS empty_id \\gset\nINSERT INTO tags(name) VALUES ('db04-python'), ('db04-api') ON CONFLICT (name) DO NOTHING;\nINSERT INTO note_tags(note_id,tag_id)\nSELECT :tagged_id, id FROM tags WHERE name IN ('db04-python','db04-api');", "lang": "sql" }, { "title": "分别查看关联明细和数量", "body": "第一条查询得到 2 行标签明细。第二条查询保留无标签笔记，数量分别为 2 与 0。注意按 id 筛选的是上一步新建的两行，不受此前重复运行影响。", "code": "SELECT n.id,n.title,t.name\nFROM notes n JOIN note_tags nt ON nt.note_id=n.id\nJOIN tags t ON t.id=nt.tag_id\nWHERE n.id=:tagged_id ORDER BY t.name;\n\nSELECT n.id,n.title,count(nt.tag_id) AS tag_count\nFROM notes n LEFT JOIN note_tags nt ON nt.note_id=n.id\nWHERE n.id IN (:tagged_id,:empty_id)\nGROUP BY n.id,n.title ORDER BY n.id;", "lang": "sql" }, { "title": "验证重复关联和删除策略", "body": "先单独执行重复 INSERT，预期 23505 唯一性错误；再单独执行 DELETE tags，预期 23503 外键错误。最后删除本课带标签笔记，对应关联行自动清理。只删除本会话创建的样本。", "code": "INSERT INTO note_tags(note_id,tag_id)\nSELECT :tagged_id,id FROM tags WHERE name='db04-python';\n-- 23505：重复关联\nDELETE FROM tags WHERE name='db04-python';\n-- 23503：仍被笔记引用\nDELETE FROM notes WHERE id=:tagged_id;\nSELECT count(*) FROM note_tags WHERE note_id=:tagged_id;\n-- 0", "lang": "sql" } ], "checks": [ "关联明细返回两个标签，聚合结果分别为 2 与 0。", "重复添加同一关联失败，不存在编号的外键写入也会失败。", "删除练习笔记后仅其关联行消失，标签本身仍存在。" ], "pitfalls": [ { "symptom": "没有标签的笔记消失了", "cause": "使用 INNER JOIN，或在 WHERE 中过滤右表导致 LEFT JOIN 效果被破坏。", "fix": "需要保留左表时使用 LEFT JOIN；右表匹配条件按语义放到 ON，并检查空值结果。" }, { "symptom": "无标签笔记显示数量 1", "cause": "COUNT(*) 统计了 LEFT JOIN 生成的空关联行。", "fix": "改用 COUNT(nt.tag_id)，并检查连接多个一对多表时是否又放大行数。" } ], "exercise": { "task": "查询拥有 db04-python 标签的笔记，要求每条笔记最多出现一次。", "hint": "可使用 EXISTS 子查询表达是否存在，不需要把标签列放进输出。", "answer": "SELECT n.id,n.title FROM notes n WHERE EXISTS (SELECT 1 FROM note_tags nt JOIN tags t ON t.id=nt.tag_id WHERE nt.note_id=n.id AND t.name='db04-python') ORDER BY n.id; 第 04 步已删除本课关联时结果为空；重新执行第 02 步后应出现新笔记。" }, "refs": [ { "label": "PostgreSQL 16：表表达式与 JOIN", "url": "https://www.postgresql.org/docs/16/queries-table-expressions.html" }, { "label": "PostgreSQL 16：聚合函数", "url": "https://www.postgresql.org/docs/16/functions-aggregate.html" }, { "label": "PostgreSQL 16：外键", "url": "https://www.postgresql.org/docs/16/ddl-constraints.html" } ], "production": { "scenario": "生产列表页需要展示标签数，同时允许笔记暂时没有标签。", "decisions": [ "通过关联表表达多对多。", "用唯一约束阻止重复关系。", "明确父记录删除行为并验证空关系。" ], "failureDrill": "在 notes_lab 重复插入关联、删除被引用标签，记录数据库拒绝原因。", "acceptance": [ "零标签结果正确。", "重复关系无法落库。", "统计没有因连接放大而重复计算。" ] } }, { "id": "05", "title": "把多次写入放进同一个事务", "group": "事务与并发", "summary": "一次保存笔记并关联标签，主动制造第二步失败，确认第一步也回滚。", "objectives": [ "划定需要同时成功的写入边界", "识别失败事务状态并执行回滚", "使用保存点隔离可选步骤" ], "concepts": [ { "title": "事务覆盖一个业务动作", "body": "创建笔记和保存必需标签属于同一次提交。只有两步都成功才向调用者返回成功。数据库事务不能自动回滚已经发送的邮件或外部 HTTP 请求，跨系统一致性在 API + 数据库和异步任务模块继续处理。" }, { "title": "错误后的事务需要结束", "body": "BEGIN 后发生约束错误，事务进入失败状态。继续 SELECT 通常得到 25P02；应 ROLLBACK 整个事务，或者在预先建立的 SAVEPOINT 上回滚到保存点。" }, { "title": "事务越短越容易控制", "body": "事务持有连接与可能的锁。不要在 BEGIN 与 COMMIT 之间等用户输入、调用模型或上传文件。identity 消耗的编号即使回滚也可能不复用，所以不能用编号是否连续判断事务正确性。" } ], "steps": [ { "title": "用成功路径保存笔记和标签", "body": "先完成第 04 课表结构。此脚本在 psql 中执行；标签使用已有 db04-api，若无该标签先执行 INSERT INTO tags(name) VALUES ('db04-api') ON CONFLICT DO NOTHING。事务末尾应 COMMIT。", "code": "BEGIN;\nINSERT INTO notes(title) VALUES ('db05-atomic-ok') RETURNING id AS ok_id \\gset\nINSERT INTO note_tags(note_id,tag_id)\nSELECT :ok_id,id FROM tags WHERE name='db04-api';\nCOMMIT;\nSELECT n.id,n.title,t.name FROM notes n\nJOIN note_tags nt ON nt.note_id=n.id JOIN tags t ON t.id=nt.tag_id\nWHERE n.id=:ok_id;", "lang": "sql" }, { "title": "制造第二步失败", "body": "本例用不存在的负标签编号触发外键错误。逐条执行，观察提示符从 notes_lab=* 改为失败事务状态。不要把预期错误脚本用 ON_ERROR_STOP 直接执行后遗漏回滚。", "code": "BEGIN;\nINSERT INTO notes(title) VALUES ('db05-must-rollback') RETURNING id AS failed_id \\gset\nINSERT INTO note_tags(note_id,tag_id) VALUES (:failed_id,-999);\n-- 23503：外键错误\nSELECT 1;\n-- 25P02：当前事务已失败\nROLLBACK;\nSELECT count(*) FROM notes WHERE id=:failed_id;\n-- 0", "lang": "sql" }, { "title": "用保存点处理可选标签", "body": "只有当业务允许“笔记成功、可选标签失败”时才采用本例。保存点前的笔记保留，保存点之后失败的关联被回滚。若标签是业务必填，则应沿用上一步整笔回滚。", "code": "BEGIN;\nINSERT INTO notes(title) VALUES ('db05-optional-tag') RETURNING id AS optional_id \\gset\nSAVEPOINT optional_tag;\nINSERT INTO note_tags(note_id,tag_id) VALUES (:optional_id,-999);\nROLLBACK TO SAVEPOINT optional_tag;\nCOMMIT;\nSELECT id,title FROM notes WHERE id=:optional_id;\n-- 1 row", "lang": "sql" }, { "title": "在独立会话核对提交边界", "body": "打开第二个 psql，执行相同 SELECT。成功笔记和可选标签笔记可见，must-rollback 不可见。再在会话 A BEGIN 后插入一条新笔记，暂不提交；会话 B 查询该标题为零行，A COMMIT 后 B 再查才能看到。最后结束两个会话中所有未结束事务。", "code": "SELECT title,count(*) FROM notes\nWHERE title LIKE 'db05-%' GROUP BY title ORDER BY title;\n-- 包含 db05-atomic-ok、db05-optional-tag\n-- 不包含 db05-must-rollback", "lang": "sql" } ], "checks": [ "第二步外键失败后，回滚事务中的笔记不存在。", "失败状态执行 SELECT 返回 25P02，ROLLBACK 后恢复。", "另一会话只能读取已提交数据；保存点例子符合明确的可选业务规则。" ], "pitfalls": [ { "symptom": "笔记创建了但标签没保存", "cause": "每条 SQL 独立提交，缺少完整事务边界。", "fix": "将必需写入放入同一事务，仅在成功提交后返回业务成功。" }, { "symptom": "重试 SQL 一直提示 current transaction is aborted", "cause": "在失败事务中继续执行，没有先回滚。", "fix": "退出事务上下文或显式 ROLLBACK，再决定是否重试整个业务动作。" } ], "exercise": { "task": "把可选标签例子改成标签必填，说明应该删除哪些语句。", "hint": "必填意味着不能在失败后只回滚局部。", "answer": "移除 SAVEPOINT 和 ROLLBACK TO SAVEPOINT。标签插入异常时执行整个事务 ROLLBACK，笔记和关联都不保留；应用把错误转成合适的响应，而不是返回创建成功。" }, "refs": [ { "label": "PostgreSQL 16：事务入门", "url": "https://www.postgresql.org/docs/16/tutorial-transactions.html" }, { "label": "PostgreSQL 16：SAVEPOINT", "url": "https://www.postgresql.org/docs/16/sql-savepoint.html" }, { "label": "Psycopg 3：事务管理", "url": "https://www.psycopg.org/psycopg3/docs/basic/transactions.html" } ], "production": { "scenario": "保存按钮触发多张表写入，任何必需步骤失败都不能产生半成品记录。", "decisions": [ "事务以业务动作划分。", "可选步骤才允许保存点局部恢复。", "外部调用在数据库事务之外安排。" ], "failureDrill": "在 notes_lab 用无效外键中断保存，重新连接检查是否留下半条业务记录。", "acceptance": [ "必需写入要么全有要么全无。", "失败后连接能够继续服务。", "日志能定位原始约束错误而不是只有后续 25P02。" ] } }, { "id": "06", "title": "用两个会话观察隔离级别与 MVCC", "group": "事务与并发", "summary": "按固定顺序执行读写，比较 Read Committed 和 Repeatable Read 的可见结果。", "objectives": [ "用两个 psql 会话复现读取差异", "解释语句快照与事务快照", "识别需要重试的序列化失败" ], "concepts": [ { "title": "快照决定读者能看见什么", "body": "Read Committed 下，每条查询读取该语句开始时已经提交的数据。Repeatable Read 通常固定在事务第一条实际查询建立的快照。下面的实验用同一行、同一个读取动作对照，避免只背隔离级别名字。" }, { "title": "普通读与写锁不是同一机制", "body": "MVCC 使普通 SELECT 可以读取已提交版本，不必因为另一会话正在更新同一行而等待其提交。SELECT FOR UPDATE 是带锁读取，行为不同。长事务会保留旧快照，增加旧版本清理压力。" }, { "title": "更强隔离伴随重试责任", "body": "Repeatable Read 或 Serializable 在并发冲突下可能返回 SQLSTATE 40001。重试应从事务开始重新读取和计算，设置次数上限与退避；不能在已经失败的事务里重发最后一条 SQL。" } ], "steps": [ { "title": "准备专用行并打开会话 A 与 B", "body": "在任意会话执行一次第一组语句，记录返回的编号。A、B 均使用 app_user / notes_lab。每个会话执行 \\set iso_id 实际编号，示例中的 123 必须替换。每轮实验开始前确保双方已 COMMIT 或 ROLLBACK。", "code": "INSERT INTO notes(title,content) VALUES ('db06-isolation','v1') RETURNING id;\n-- 假设返回 123，在 A 和 B 各自设置：\n\\set iso_id 123\nSHOW default_transaction_isolation;\n-- read committed", "lang": "sql" }, { "title": "执行 Read Committed 时序", "body": "按注释切换窗口，不要一次性粘贴到同一会话。A 第一次读 v1；B 更新但未提交时 A 仍读 v1；B 提交后 A 再读变为 v2。A 的事务没有重开，但下一条查询已经取得新快照。", "code": "-- A：先执行\nBEGIN ISOLATION LEVEL READ COMMITTED;\nSELECT content FROM notes WHERE id=:iso_id;\n-- B：执行，先不提交\nBEGIN;\nUPDATE notes SET content='v2',updated_at=now() WHERE id=:iso_id;\n-- A：此时仍为 v1\nSELECT content FROM notes WHERE id=:iso_id;\n-- B：现在提交\nCOMMIT;\n-- A：现在为 v2，然后结束\nSELECT content FROM notes WHERE id=:iso_id;\nCOMMIT;", "lang": "sql" }, { "title": "执行 Repeatable Read 时序", "body": "延续上一步的 v2。A 建立快照后，B 写入 v3 并提交；A 在原事务内仍读 v2。A 提交并开始新查询后读到 v3。记录四次读取结果与相应窗口。", "code": "-- A\nBEGIN ISOLATION LEVEL REPEATABLE READ;\nSELECT content FROM notes WHERE id=:iso_id;\n-- B：自动提交状态\nUPDATE notes SET content='v3',updated_at=now() WHERE id=:iso_id;\n-- A：原快照仍为 v2\nSELECT content FROM notes WHERE id=:iso_id;\nCOMMIT;\nSELECT content FROM notes WHERE id=:iso_id;\n-- v3", "lang": "sql" }, { "title": "复现并发更新失败并恢复", "body": "A 用 Repeatable Read 读取 v3，B 改成 v4 并提交，A 再更新同一行会遇到 40001。最后 A ROLLBACK 并重新读取，确认新事务看到 v4。这里只演示失败机制，不对包含外部副作用的动作进行盲目重试。", "code": "-- A\nBEGIN ISOLATION LEVEL REPEATABLE READ;\nSELECT content FROM notes WHERE id=:iso_id;\n-- B\nUPDATE notes SET content='v4',updated_at=now() WHERE id=:iso_id;\n-- A\nUPDATE notes SET content='v5' WHERE id=:iso_id;\n-- ERROR: could not serialize access due to concurrent update\nROLLBACK;\nSELECT content FROM notes WHERE id=:iso_id;\n-- v4", "lang": "sql" } ], "checks": [ "Read Committed 在 B 提交前后读到 v1、v2。", "Repeatable Read 在事务中保持 v2，事务结束后读到 v3。", "并发更新实验出现 40001，ROLLBACK 后读取恢复。" ], "pitfalls": [ { "symptom": "两种隔离级别看起来没有区别", "cause": "A 没有显式 BEGIN，或者 B 在 A 建立快照之前已提交。", "fix": "严格按窗口与注释顺序执行，记录每次 BEGIN、SELECT 和 COMMIT 的时点。" }, { "symptom": "实验结束后连接一直 idle in transaction", "cause": "只观察结果没有结束事务。", "fix": "两个窗口都执行 ROLLBACK；生产应用用上下文管理事务并限制事务内工作量。" } ], "exercise": { "task": "说明报表需要同一时点多次读取，而普通单条查询通常不用提高到 Repeatable Read 的原因。", "hint": "先确定需要保证的是一条 SQL，还是多条 SQL 共享快照。", "answer": "单条 SELECT 本身在一个语句快照内执行。需要多条 SELECT 共享一致快照时，可选择短的只读 Repeatable Read 事务；若能用一条 SQL 表达汇总，通常可减少事务持续时间。提高隔离级别不能代替业务约束与正确的重试实现。" }, "refs": [ { "label": "PostgreSQL 16：事务隔离", "url": "https://www.postgresql.org/docs/16/transaction-iso.html" }, { "label": "PostgreSQL 16：MVCC 简介", "url": "https://www.postgresql.org/docs/16/mvcc-intro.html" }, { "label": "PostgreSQL 16：序列化失败处理", "url": "https://www.postgresql.org/docs/16/mvcc-serialization-failure-handling.html" } ], "production": { "scenario": "后台导出需要一致读取，编辑接口同时持续更新笔记。", "decisions": [ "根据读取范围选择隔离级别。", "限制长事务，避免把导出网络传输放在读事务内。", "40001 重试覆盖完整事务。" ], "failureDrill": "在 notes_lab 双会话执行快照与并发更新实验，保留实际输出顺序。", "acceptance": [ "每个结果可对应到一次提交。", "实验后无遗留事务。", "能区分数据可见性与行锁等待。" ] } }, { "id": "07", "title": "定位锁等待、复现死锁并加入版本检查", "group": "事务与并发", "summary": "观察同一行写入的等待关系，再分别用固定加锁顺序和乐观锁解决不同冲突。", "objectives": [ "用 pg_blocking_pids 找到锁等待源头", "复现并处理死锁回滚", "用 version 条件阻止覆盖其他人的编辑" ], "concepts": [ { "title": "行锁持续到事务结束", "body": "UPDATE 和 SELECT FOR UPDATE 可阻止另一个事务更新同一行。等待不一定是坏事，但必须有时限与可观测性；持锁时调用外部服务会让数据库承担外部延迟。" }, { "title": "死锁来自循环等待", "body": "A 持有行一等待行二，B 持有行二等待行一，形成闭环。数据库会中止其中一个事务，不能预言一定中止谁。固定顺序获取多行锁可减少死锁，应用仍需识别 40P01 并有限重试整个事务。" }, { "title": "版本检查表达编辑冲突", "body": "客户端读取 version=1，更新时要求 WHERE version=1 并同时 version=version+1。若别人已提交，更新返回零行，调用者应重新读取并解决冲突。版本检查防止旧内容覆盖新内容，不用于替代所有数据库锁。" } ], "steps": [ { "title": "建立两个实验行并添加版本列", "body": "完成前面表结构后执行一次 ADD COLUMN；若已存在 version 则只运行后两条。把返回编号记为 first_id 和 second_id，在 A、B 两个窗口各设置相同变量。", "code": "ALTER TABLE notes ADD COLUMN version integer NOT NULL DEFAULT 1 CHECK (version > 0);\nINSERT INTO notes(title) VALUES ('db07-first') RETURNING id;\nINSERT INTO notes(title) VALUES ('db07-second') RETURNING id;\n-- 在两个窗口替换为实际返回值\n\\set first_id 124\n\\set second_id 125", "lang": "sql" }, { "title": "观察一个有上限的锁等待", "body": "先 A 加锁，再 B 执行 UPDATE。B 等待期间切回 A 查询阻塞信息；如果 5 秒不够观察，可重做一次。B 约 5 秒后收到 lock timeout，之后必须 ROLLBACK；A 也 ROLLBACK 释放锁。", "code": "-- A\nBEGIN;\nSELECT id FROM notes WHERE id=:first_id FOR UPDATE;\n-- B\nBEGIN;\nSET LOCAL lock_timeout='5s';\nUPDATE notes SET content='waiting' WHERE id=:first_id;\n-- A：在 B 等待期间执行\nSELECT pid,wait_event_type,wait_event,pg_blocking_pids(pid) AS blockers\nFROM pg_stat_activity WHERE datname='notes_lab';\n-- B 超时后，以及 A 观察完后，各自执行\nROLLBACK;", "lang": "sql" }, { "title": "按顺序制造死锁", "body": "先确认双方没有遗留事务。先 A 锁第一行，再 B 锁第二行，然后 A 请求第二行进入等待，最后 B 请求第一行。一个窗口返回 deadlock detected，另一个窗口可继续获得锁。无论哪个失败，两个窗口最后都执行 ROLLBACK。", "code": "-- A\nBEGIN;\nSELECT id FROM notes WHERE id=:first_id FOR UPDATE;\n-- B\nBEGIN;\nSELECT id FROM notes WHERE id=:second_id FOR UPDATE;\n-- A：此处会等待\nSELECT id FROM notes WHERE id=:second_id FOR UPDATE;\n-- B：触发循环等待\nSELECT id FROM notes WHERE id=:first_id FOR UPDATE;\n-- SQLSTATE 40P01 出现在其中一个会话\n-- A 和 B 各执行 ROLLBACK;", "lang": "sql" }, { "title": "改为相同顺序锁定多行", "body": "在 A 执行下面代码并保持事务，B 执行同样代码会等待 A。A COMMIT 后 B 能继续，然后 B COMMIT。双方都按 id 升序取得目标锁，避免本例的相反顺序。", "code": "BEGIN;\nSELECT id FROM notes WHERE id IN (:first_id,:second_id) ORDER BY id FOR UPDATE;\n-- A 先 COMMIT，B 等待结束后再 COMMIT\nCOMMIT;", "lang": "sql" }, { "title": "用旧版本号重放编辑", "body": "在同一个窗口按顺序执行即可模拟两个客户端都读到版本 1。先把专用行重置到 version=1；第一次更新得到 2，第二次带旧版本条件返回 0 行。只有实际更新成功才向客户端返回成功。", "code": "UPDATE notes SET version=1,content='base' WHERE id=:first_id;\nUPDATE notes SET content='editor A',version=version+1,updated_at=now()\nWHERE id=:first_id AND version=1 RETURNING id,content,version;\n-- version=2\nUPDATE notes SET content='editor B',version=version+1,updated_at=now()\nWHERE id=:first_id AND version=1 RETURNING id,content,version;\n-- 0 rows\nSELECT content,version FROM notes WHERE id=:first_id;\n-- editor A, 2", "lang": "sql" } ], "checks": [ "锁等待能查到非空 blockers，超时后事务可回滚。", "死锁仅保证一个参与事务被中止，两个窗口最后均无活动事务。", "旧版本更新返回零行，editor A 的内容没有被覆盖。" ], "pitfalls": [ { "symptom": "设置 statement_timeout 后还是不清楚在等什么", "cause": "语句超时能中断执行，但没有分析锁等待来源。", "fix": "在等待期间查看 wait_event 与 pg_blocking_pids，结合持锁会话事务时长定位。" }, { "symptom": "版本检查存在但更新仍覆盖内容", "cause": "SELECT 后在 Python 检查版本，UPDATE 没带 version 条件。", "fix": "把版本比较和递增放在同一条 UPDATE 中，依据 RETURNING 判定成功。" } ], "exercise": { "task": "将批量修改改为按 id 升序锁定，并说明收到 40P01 后重试范围。", "hint": "不要只重试死锁报错的最后一条 SELECT。", "answer": "先确定全部目标编号，在同一事务按升序 SELECT ... FOR UPDATE，再执行修改。收到 40P01 后回滚并重新读取整个业务动作的输入，有限退避重试；涉及外部副作用时先使用幂等机制。" }, "refs": [ { "label": "PostgreSQL 16：显式锁与死锁", "url": "https://www.postgresql.org/docs/16/explicit-locking.html" }, { "label": "PostgreSQL 16：统计活动", "url": "https://www.postgresql.org/docs/16/monitoring-stats.html" }, { "label": "PostgreSQL 16：错误码", "url": "https://www.postgresql.org/docs/16/errcodes-appendix.html" } ], "production": { "scenario": "两名用户同时编辑笔记，后台任务又可能批量修改相同记录。", "decisions": [ "短事务与锁超时控制等待。", "多行写入约定一致的锁顺序。", "普通编辑用版本检查向用户呈现冲突。" ], "failureDrill": "仅在 notes_lab 双会话制造行锁与死锁，记录等待链、SQLSTATE 和回滚结果。", "acceptance": [ "没有无限等待。", "所有写入入口维护 version。", "冲突时保留已提交内容并报告更新失败。" ] } }, { "id": "08", "title": "围绕查询设计单列、组合与部分索引", "group": "查询性能", "summary": "准备足够的数据，对照查询条件与排序建立索引，再核算索引带来的写入成本。", "objectives": [ "从 WHERE 与 ORDER BY 推导组合索引", "用部分索引服务低占比条件", "知道主键、唯一约束与外键索引的区别" ], "concepts": [ { "title": "索引缩小查找范围", "body": "B-tree 索引按键组织数据，使等值、范围与有序读取可以少访问一些数据页。索引占用磁盘，写入和更新时也要维护。是否使用索引由优化器估计成本决定，小表顺序扫描常常更合适。" }, { "title": "组合键的顺序来自查询", "body": "WHERE pinned=true ORDER BY created_at DESC,id DESC LIMIT 20 可用 pinned、created_at、id 的组合索引。前面的等值条件固定范围，后面提供稳定排序。只对 pinned 这个低基数字段建索引不一定有收益。" }, { "title": "部分索引只保存需要的行", "body": "如果置顶笔记仅占少数，可只索引 WHERE pinned=true 的记录。查询条件需能匹配该谓词；不要假设参数化的任意布尔条件总能使用该索引。主键和唯一约束会创建索引，外键引用列不自动创建索引。" } ], "steps": [ { "title": "在独立练习库生成性能样本", "body": "仅 notes_lab 执行，写入 50,000 条带 db08-bench- 前缀的笔记。此脚本只运行一次，重复执行会额外产生同量数据。固定时间与稀疏 pinned 分布便于对照，但不能代表真实业务分布。", "code": "INSERT INTO notes(title,content,pinned,created_at,updated_at)\nSELECT 'db08-bench-' || g, repeat('x',200), g % 100 = 0,\n timestamptz '2026-01-01 00:00:00+00' + g * interval '1 second',\n timestamptz '2026-01-01 00:00:00+00' + g * interval '1 second'\nFROM generate_series(1,50000) AS g;\nANALYZE notes;\nSELECT count(*),count(*) FILTER(WHERE pinned) FROM notes;", "lang": "sql" }, { "title": "保存无专用索引时的计划", "body": "先只用 EXPLAIN 观察估计计划，下一课运行带 ANALYZE 的实际计划。记录扫描方式、Sort 是否存在及估计行数，不把某个固定 cost 数值作为正确答案。", "code": "EXPLAIN\nSELECT id,title,created_at FROM notes\nWHERE pinned=true ORDER BY created_at DESC,id DESC LIMIT 20;\nSELECT indexname,indexdef FROM pg_indexes WHERE tablename='notes';", "lang": "sql" }, { "title": "建立组合索引并对比", "body": "建索引后重新执行相同 EXPLAIN。数据量足够时通常能减少扫描和排序工作，但输出由版本、统计和数据决定。索引包含 id 用于同一时间点下稳定排序。", "code": "CREATE INDEX notes_pinned_created_id_idx ON notes(pinned,created_at DESC,id DESC);\nANALYZE notes;\nEXPLAIN\nSELECT id,title,created_at FROM notes\nWHERE pinned=true ORDER BY created_at DESC,id DESC LIMIT 20;\nSELECT pg_size_pretty(pg_relation_size('notes_pinned_created_id_idx')) AS index_size;", "lang": "sql" }, { "title": "将置顶查询改为部分索引实验", "body": "为能明确对照，只在 notes_lab 删除刚创建的实验索引，改建部分索引，再执行同样查询。生产建索引可评估 CREATE INDEX CONCURRENTLY 以减少阻塞，但它不能放在事务块中，失败后还需检查无效索引。", "code": "DROP INDEX notes_pinned_created_id_idx;\nCREATE INDEX notes_pinned_recent_idx ON notes(created_at DESC,id DESC) WHERE pinned=true;\nEXPLAIN\nSELECT id,title,created_at FROM notes\nWHERE pinned=true ORDER BY created_at DESC,id DESC LIMIT 20;\nSELECT pg_size_pretty(pg_relation_size('notes_pinned_recent_idx')) AS index_size;\nCREATE INDEX note_tags_tag_id_idx ON note_tags(tag_id);", "lang": "sql" } ], "checks": [ "记录至少两个版本计划和各自索引大小。", "能说明 pinned=true 查询与部分索引谓词的关系。", "note_tags 的联合主键覆盖 note_id 开头查找，反向 tag_id 查询有单独索引。" ], "pitfalls": [ { "symptom": "建了索引仍然 Seq Scan", "cause": "表很小、命中行过多、统计过旧或查询不匹配索引。", "fix": "先 ANALYZE 并检查实际 SQL、类型与选择率；不要通过关闭顺序扫描作为生产修复。" }, { "symptom": "索引越加越多，写入越来越慢", "cause": "每个索引都增加存储与维护，部分索引可能重复覆盖同一查询。", "fix": "保留使用证据与目标查询，对重复索引评估后再清理，结合写入延迟一起验收。" } ], "exercise": { "task": "为 WHERE tag_id=? 查询关联的 note_id 设计索引，并判断现有主键是否足够。", "hint": "联合主键是 (note_id,tag_id)，注意最左列。", "answer": "现有主键擅长 note_id 或 note_id+tag_id 条件，不应默认满足按 tag_id 反查的性能需求。可使用 CREATE INDEX ON note_tags(tag_id,note_id)，并在实际数据上对比；若采用此组合索引，应评估是否还需要单列 tag_id 索引。" }, "refs": [ { "label": "PostgreSQL 16：多列索引", "url": "https://www.postgresql.org/docs/16/indexes-multicolumn.html" }, { "label": "PostgreSQL 16：部分索引", "url": "https://www.postgresql.org/docs/16/indexes-partial.html" }, { "label": "PostgreSQL 16：CREATE INDEX", "url": "https://www.postgresql.org/docs/16/sql-createindex.html" } ], "production": { "scenario": "首页需要快速显示置顶笔记，写入仍持续发生。", "decisions": [ "索引对应一条明确查询。", "用接近真实分布的数据评估读写成本。", "生产在线建索引单独规划事务与失败恢复。" ], "failureDrill": "在 notes_lab 比较无索引、组合索引与部分索引的计划与大小。", "acceptance": [ "查询顺序确定。", "有性能证据支持索引选择。", "没有把练习库 DROP INDEX 直接当成生产变更方案。" ] } }, { "id": "09", "title": "读取 EXPLAIN ANALYZE 并改造深分页", "group": "查询性能", "summary": "用执行计划验证实际工作量，再把大 OFFSET 改成稳定的游标条件。", "objectives": [ "读懂实际行数、loops 与 buffers", "比较浅分页和深分页的扫描量", "使用 created_at 与 id 实现键集分页" ], "concepts": [ { "title": "ANALYZE 会真的执行 SQL", "body": "EXPLAIN 只生成计划，EXPLAIN ANALYZE 会执行语句并收集结果。此课仅分析 SELECT；不要直接拿它分析线上 DELETE 或 UPDATE。实际耗时受缓存与负载影响，需要同时看扫描量和缓冲访问。" }, { "title": "深 OFFSET 仍需跳过前面的记录", "body": "LIMIT 20 OFFSET 40000 返回 20 行，但执行器通常仍需走过被跳过的记录。键集分页使用上一页最后一行的排序键，直接定位下一段范围。" }, { "title": "游标必须与排序完全一致", "body": "按 created_at DESC,id DESC 排序，就用 (created_at,id)<(游标时间,游标编号)。id 处理相同时间的并列。游标不是快照；并发删除、排序字段修改仍可能影响跨页视图，导出要另行定义一致性。" } ], "steps": [ { "title": "创建列表索引并收集实际计划", "body": "继续使用第 08 课的 50,000 条样本。首次建索引一次，运行 ANALYZE。记录节点名称、actual rows、loops、Buffers 和 Execution Time。不要要求每台机器出现完全相同的执行时间。", "code": "CREATE INDEX notes_created_id_idx ON notes(created_at DESC,id DESC);\nANALYZE notes;\nEXPLAIN (ANALYZE,BUFFERS)\nSELECT id,title,created_at FROM notes ORDER BY created_at DESC,id DESC LIMIT 20;", "lang": "sql" }, { "title": "比较深分页的额外工作", "body": "运行相同排序的深 OFFSET。即使最后只返回 20 行，下层扫描节点通常处理约 40,020 行。若计划不同，按真实节点追踪返回与丢弃的行，不强行匹配示例计划。", "code": "EXPLAIN (ANALYZE,BUFFERS)\nSELECT id,title,created_at FROM notes\nORDER BY created_at DESC,id DESC LIMIT 20 OFFSET 40000;", "lang": "sql" }, { "title": "从第一页取得下一页游标", "body": "以下 psql 查询取第一页最后一行的时间和编号，\\gset 保存为 cursor_created、cursor_id。实际 API 应从已返回的第 20 行取值，不再单独 OFFSET 查询。使用 :'cursor_created' 让 psql 正确引用时间文本。", "code": "SELECT created_at AS cursor_created,id AS cursor_id\nFROM notes ORDER BY created_at DESC,id DESC LIMIT 1 OFFSET 19 \\gset\nSELECT id,title,created_at FROM notes\nWHERE (created_at,id) < (:'cursor_created'::timestamptz,:cursor_id)\nORDER BY created_at DESC,id DESC LIMIT 20;\nEXPLAIN (ANALYZE,BUFFERS)\nSELECT id,title,created_at FROM notes\nWHERE (created_at,id) < (:'cursor_created'::timestamptz,:cursor_id)\nORDER BY created_at DESC,id DESC LIMIT 20;", "lang": "sql" }, { "title": "在相近深度公平对照", "body": "为了教学比较，先花一次 OFFSET 成本拿到深处游标，再测游标查询本身。实际连续翻页只传前页游标。连续运行两次，说明缓存预热影响，不用单次毫秒值证明普遍结论。", "code": "SELECT created_at AS deep_created,id AS deep_id\nFROM notes ORDER BY created_at DESC,id DESC LIMIT 1 OFFSET 39999 \\gset\nEXPLAIN (ANALYZE,BUFFERS)\nSELECT id,title,created_at FROM notes\nWHERE (created_at,id) < (:'deep_created'::timestamptz,:deep_id)\nORDER BY created_at DESC,id DESC LIMIT 20;", "lang": "sql" } ], "checks": [ "记录浅 OFFSET、深 OFFSET 与深游标的实际扫描量。", "下一页与前页没有重复编号，排序键与过滤条件完全一致。", "能区分计划估计值与实际执行值，不把 cost 当成毫秒。" ], "pitfalls": [ { "symptom": "分页重复或漏掉相同时间的记录", "cause": "只把 created_at 放进排序或游标，缺少唯一的并列键。", "fix": "排序和比较同时包含 id，并让排序方向与比较符号一致。" }, { "symptom": "游标查询变慢且出现 Sort", "cause": "缺少匹配排序的索引，或添加了新筛选条件改变访问方式。", "fix": "对实际查询重新 EXPLAIN ANALYZE，检查复合索引与筛选顺序，而不是只调 LIMIT。" } ], "exercise": { "task": "给置顶列表加入键集分页，并说明使用哪个已有索引。", "hint": "保留 pinned=true，同时添加二元组范围条件。", "answer": "SELECT id,title,created_at FROM notes WHERE pinned=true AND (created_at,id)<($1,$2) ORDER BY created_at DESC,id DESC LIMIT 20; 这是数据库参数形式示意，psycopg 中使用 %s。第 08 课的 notes_pinned_recent_idx 对该固定谓词和排序有用，仍需实际执行计划验证。" }, "refs": [ { "label": "PostgreSQL 16：EXPLAIN", "url": "https://www.postgresql.org/docs/16/using-explain.html" }, { "label": "PostgreSQL 16：LIMIT 与 OFFSET", "url": "https://www.postgresql.org/docs/16/queries-limit.html" }, { "label": "PostgreSQL 16：行比较", "url": "https://www.postgresql.org/docs/16/functions-comparisons.html" } ], "production": { "scenario": "笔记数量增长后，第几百页响应变慢，而第一页正常。", "decisions": [ "以实际扫描量解释深分页成本。", "连续滚动用键集分页，任意跳页另做产品和性能取舍。", "游标字段选择稳定值，分页不默认承诺全程快照。" ], "failureDrill": "在 notes_lab 对比相同深度的 OFFSET 与游标查询，记录执行计划。", "acceptance": [ "深页工作量明显下降或有证据解释未下降原因。", "同时间记录不重复。", "测试记录注明样本规模与缓存状态。" ] } }, { "id": "10", "title": "用 psycopg 连接池管理连接与事务", "group": "Python 与运行保障", "summary": "让并发代码借用有限连接，复现池耗尽，确保异常后连接能够归还。", "objectives": [ "建立一个可显式开启和关闭的连接池", "把事务包含在借还连接的作用域内", "通过超时和统计观察池拥塞" ], "concepts": [ { "title": "连接池是有限资源预算", "body": "每个连接对应数据库后端资源。池在 min_size 与 max_size 范围复用连接，借不到时等待而非无限新建。进程数乘每进程最大池容量，再加任务、运维与其他服务连接，必须落在数据库预算内。" }, { "title": "连接不等于业务并发数", "body": "多个请求可以排队等待少量连接。持有连接的时间越长，可服务吞吐越低。一个连接上的查询串行执行；不同线程不要把同一连接当作各自独立事务。同步 psycopg 应运行在同步代码或受控线程中。" }, { "title": "借还边界包含提交与回滚", "body": "pool.connection() 的上下文负责正常结束时提交、异常退出时回滚并归还连接。应用启动创建池、退出关闭池；业务函数借用连接，不在每次调用时重新创建整个池。异步 API 对应 AsyncConnectionPool，在 API + 数据库模块接入。" } ], "steps": [ { "title": "安装池依赖", "body": "沿用第 03 课 PG 环境变量。在虚拟环境运行 python -m pip install \"psycopg[binary,pool]>=3.2,<4\"，然后更新 requirements-lock.txt。psycopg_pool 是单独分发的依赖，安装 psycopg 本体不代表已安装连接池。", "code": "python -m pip install \"psycopg[binary,pool]>=3.2,<4\"\npython -m pip freeze > requirements-lock.txt", "lang": "bash" }, { "title": "运行并发读的完整示例", "body": "保存为 db_pool.py 并运行。4 个工作线程共用最大 2 条连接；每次函数调用独立借还。open=False 加 open(wait=True) 让启动阶段就确认连接可用，退出通过 finally 关闭。应用不应把密码或整条连接信息打印到日志。", "code": "from concurrent.futures import ThreadPoolExecutor\nfrom psycopg_pool import ConnectionPool\n\npool = ConnectionPool(\"\", min_size=1, max_size=2, timeout=2, open=False,\n kwargs={\"application_name\": \"notes-service-db-lab\"})\n\ndef count_notes(_):\n with pool.connection() as conn:\n with conn.cursor() as cur:\n cur.execute(\"SET LOCAL statement_timeout='2s'\")\n cur.execute(\"SELECT count(*) FROM notes\")\n return cur.fetchone()[0]\n\ntry:\n pool.open(wait=True, timeout=10)\n with ThreadPoolExecutor(max_workers=4) as workers:\n print(list(workers.map(count_notes, range(8))))\n print(pool.get_stats())\nfinally:\n pool.close()", "lang": "python", "filename": "db_pool.py" }, { "title": "验证异常后事务回滚", "body": "保存为 db_pool_rollback.py。故意抛出 Python 异常，异常必须离开 connection 上下文后再捕获，否则上下文可能把事务当作正常结束而提交。第二次借用连接后查询结果应为 0。", "code": "from psycopg_pool import ConnectionPool\n\nwith ConnectionPool(\"\", min_size=1, max_size=1) as pool:\n pool.wait(timeout=10)\n note_id = None\n try:\n with pool.connection() as conn:\n note_id = conn.execute(\n \"INSERT INTO notes(title) VALUES (%s) RETURNING id\",\n (\"db10-rollback\",),\n ).fetchone()[0]\n raise RuntimeError(\"simulated failure after insert\")\n except RuntimeError:\n pass\n with pool.connection() as conn:\n count = conn.execute(\"SELECT count(*) FROM notes WHERE id=%s\", (note_id,)).fetchone()[0]\n assert count == 0\n print(\"rolled back\", count)", "lang": "python", "filename": "db_pool_rollback.py" }, { "title": "可控复现池耗尽", "body": "保存为 db_pool_timeout.py，只在本机练习运行。max_size=1 时外层已经占用唯一连接，内层借用 0.2 秒后超时；捕获异常后退出外层归还连接，再借用应成功。生产代码应消除嵌套借还并缩短持有时间，不能只扩大池。", "code": "from psycopg_pool import ConnectionPool, PoolTimeout\n\nwith ConnectionPool(\"\", min_size=1, max_size=1) as pool:\n pool.wait(timeout=10)\n with pool.connection():\n try:\n with pool.connection(timeout=0.2):\n pass\n except PoolTimeout:\n print(\"expected pool timeout\")\n with pool.connection() as conn:\n print(\"recovered\", conn.execute(\"SELECT 1\").fetchone()[0])\n print(pool.get_stats())", "lang": "python", "filename": "db_pool_timeout.py" } ], "checks": [ "并发读取成功，连接数量受 max_size=2 限制。", "异常插入的笔记在下一次借用中查不到。", "池耗尽产生 PoolTimeout，归还后 SELECT 1 恢复。" ], "pitfalls": [ { "symptom": "高并发时不断出现 PoolTimeout", "cause": "连接持有时间过长、嵌套借用或总并发超过容量。", "fix": "检查等待数和事务时长，先缩短查询与持有范围，再按数据库预算调整池。" }, { "symptom": "async 路由中数据库调用阻塞其他请求", "cause": "在事件循环中直接执行同步 psycopg 查询。", "fix": "用 AsyncConnectionPool 与 await，或在受控线程执行同步代码；不要只把函数名改成 async。" } ], "exercise": { "task": "4 个 API 进程各 max_size=8，两个任务进程各 max_size=5，预留运维 10 条连接，至少需要规划多少连接？", "hint": "进程之间不共享一个 Python 连接池。", "answer": "仅这些进程峰值预算是 4×8+2×5+10=52 条，还应核查迁移、监控、其他服务和数据库保留连接。52 是这组假设下的预算，不是直接把 max_connections 设为 52 的建议。" }, "refs": [ { "label": "Psycopg 3：连接池", "url": "https://www.psycopg.org/psycopg3/docs/advanced/pool.html" }, { "label": "Psycopg 3：池 API", "url": "https://www.psycopg.org/psycopg3/docs/api/pool.html" }, { "label": "Psycopg 3：并发与异步", "url": "https://www.psycopg.org/psycopg3/docs/advanced/async.html" } ], "production": { "scenario": "API 与任务进程同时访问 PostgreSQL，突发请求不应耗尽全部数据库连接。", "decisions": [ "按进程数计算总连接预算。", "连接等待和 SQL 执行分别设时限。", "业务异常离开事务边界后再转为响应。" ], "failureDrill": "在 notes_lab 用单连接池制造超时和事务异常，再确认连接能归还复用。", "acceptance": [ "没有连接泄漏。", "等待有时限与可记录指标。", "连接池在应用生命周期内创建和关闭。" ] } }, { "id": "11", "title": "拆分数据库权限并管理连接配置", "group": "Python 与运行保障", "summary": "让运行时账号只做业务读写，限制危险语句，并检查日志和连接配置中的敏感信息。", "objectives": [ "区分迁移账号与 API 运行账号", "配置现有对象和未来对象的授权", "验证最小权限以及超时配置" ], "concepts": [ { "title": "权限应按工作职责分配", "body": "app_user 保留为练习的对象所有者和迁移身份；新增 notes_runtime 供 API 运行。运行时需要 SELECT、INSERT、UPDATE、DELETE，不需要 CREATE ROLE、DROP TABLE 或 ALTER TABLE。数据库 CONNECT、schema USAGE、表权限是不同层。" }, { "title": "未来对象不会自动继承手工授权", "body": "GRANT ON ALL TABLES 只覆盖当时存在的表。ALTER DEFAULT PRIVILEGES 针对特定创建者未来创建的对象生效，必须由正确身份设置。生产服务若只需要部分表，应显式授权，不能照搬练习的全部业务表授权。" }, { "title": "连接加密与秘密存储", "body": "生产连接优先使用 TLS 且校验证书和主机名，例如 sslmode=verify-full 配合可信根证书。本机官方镜像没有自动配置可校验 TLS，不应伪称本课容器已提供 TLS。密码通过环境或秘密文件注入，SQL 参数和业务正文也可能包含敏感数据。" } ], "steps": [ { "title": "管理身份创建运行角色", "body": "使用第 01 课 docker exec -it notes-postgres psql -U postgres -d notes_lab 进入管理连接。密码通过 \\password 交互设置。PUBLIC 是所有角色的隐式集合，撤销公开连接只限此独立练习库，不在共享线上库直接执行。", "code": "CREATE ROLE notes_runtime LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE;\n\\password notes_runtime\nREVOKE CONNECT ON DATABASE notes_lab FROM PUBLIC;\nGRANT CONNECT ON DATABASE notes_lab TO app_user,notes_runtime;\nALTER ROLE notes_runtime IN DATABASE notes_lab SET statement_timeout='3s';\nALTER ROLE notes_runtime IN DATABASE notes_lab SET lock_timeout='1s';\nALTER ROLE notes_runtime IN DATABASE notes_lab SET idle_in_transaction_session_timeout='30s';", "lang": "sql" }, { "title": "所有者身份授权现有与未来对象", "body": "重新用 app_user 连接 notes_lab 执行。当前课程所有业务表都位于 public，生产可改成独立 schema 并按表授权。identity 之外若使用显式序列默认值，需要相应 sequence 权限；本例将业务序列使用权限一并授予。", "code": "REVOKE CREATE ON SCHEMA public FROM PUBLIC;\nGRANT USAGE ON SCHEMA public TO notes_runtime;\nGRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO notes_runtime;\nGRANT USAGE,SELECT ON ALL SEQUENCES IN SCHEMA public TO notes_runtime;\nALTER DEFAULT PRIVILEGES FOR ROLE app_user IN SCHEMA public\nGRANT SELECT,INSERT,UPDATE,DELETE ON TABLES TO notes_runtime;\nALTER DEFAULT PRIVILEGES FOR ROLE app_user IN SCHEMA public\nGRANT USAGE,SELECT ON SEQUENCES TO notes_runtime;", "lang": "sql" }, { "title": "运行身份验证允许与拒绝操作", "body": "通过 docker exec -it notes-postgres psql -h 127.0.0.1 -U notes_runtime -d notes_lab -W 连接。插入成功后删除本次编号；尝试 ALTER TABLE 会因不是所有者失败，不应产生新列。", "code": "SELECT current_user;\nINSERT INTO notes(title) VALUES ('db11-runtime') RETURNING id AS runtime_id \\gset\nDELETE FROM notes WHERE id=:runtime_id;\nALTER TABLE notes ADD COLUMN should_not_exist text;\n-- ERROR: must be owner of table notes\nSHOW statement_timeout;\nSHOW lock_timeout;\nSELECT pg_sleep(4);\n-- 约 3 秒取消，SQLSTATE 57014", "lang": "sql" }, { "title": "验证未来表权限并调整应用配置", "body": "以 app_user 创建临时验收表，再以 notes_runtime SELECT 应成功。验收后 app_user 删除该专用表。把应用 PGUSER 改为 notes_runtime 并注入对应密码，迁移工具继续单独使用 app_user。检查日志只记录操作名、耗时和 SQLSTATE，不打印密码或完整正文。", "code": "-- app_user\nCREATE TABLE permission_probe(id integer PRIMARY KEY);\nINSERT INTO permission_probe VALUES (1);\n-- notes_runtime：应该读到 1\nSELECT id FROM permission_probe;\n-- app_user：验收结束清理本课专用表\nDROP TABLE permission_probe;", "lang": "sql" } ], "checks": [ "notes_runtime 可以执行业务 CRUD，不能修改表结构。", "新连接显示 3 秒语句超时和 1 秒锁超时。", "app_user 创建的未来表遵循默认权限，密码没有写进仓库和示例日志。" ], "pitfalls": [ { "symptom": "现有表能访问，新迁移建的表报 permission denied", "cause": "只给现有表 GRANT，或默认权限针对了错误创建角色。", "fix": "检查实际迁移角色，给该角色设置 ALTER DEFAULT PRIVILEGES，并补授权已经创建的对象。" }, { "symptom": "sslmode=require 就被当成完成服务器身份校验", "cause": "只要求加密不等于完整证书与主机名校验。", "fix": "生产按基础设施证书配置 verify-full 与根证书；本机未配 TLS 的容器使用明确的开发配置。" } ], "exercise": { "task": "给只读报表账号设计最小权限，说明为什么不应复用 app_user。", "hint": "需要 CONNECT、schema USAGE 和必要表的 SELECT；不授予写入或对象所有权。", "answer": "创建独立 LOGIN 角色，授予 notes_lab 的 CONNECT、public 的 USAGE、指定业务表的 SELECT。为其设置合适超时与只读事务默认值作为附加限制；最终权限仍由 GRANT 决定。app_user 是对象所有者，权限范围远超报表需求。" }, "refs": [ { "label": "PostgreSQL 16：权限", "url": "https://www.postgresql.org/docs/16/ddl-priv.html" }, { "label": "PostgreSQL 16：默认权限", "url": "https://www.postgresql.org/docs/16/sql-alterdefaultprivileges.html" }, { "label": "PostgreSQL 16：SSL 客户端验证", "url": "https://www.postgresql.org/docs/16/libpq-ssl.html" }, { "label": "PostgreSQL 16：客户端默认设置", "url": "https://www.postgresql.org/docs/16/runtime-config-client.html" } ], "production": { "scenario": "API 连接配置泄漏或代码出现错误时，需要限制其能影响的数据库对象。", "decisions": [ "运行角色与迁移角色使用不同秘密。", "超时配置需重连生效并实测。", "审计日志避免包含原始敏感正文。" ], "failureDrill": "在 notes_lab 用运行角色尝试 ALTER TABLE 并执行超时查询，验证拒绝和恢复。", "acceptance": [ "运行角色不是所有者或超级用户。", "权限随未来迁移保持可用。", "生产 TLS、凭据注入和轮换方式有明确配置责任。" ] } }, { "id": "12", "title": "备份恢复与可回退的结构变更", "group": "Python 与运行保障", "summary": "导出练习库并恢复到另一个数据库，通过数据核对和迁移演练完成生产验收。", "objectives": [ "用 pg_dump 创建逻辑备份并校验文件", "在独立恢复库验证结构、数据和序列", "使用扩展、回填、验证的步骤变更表结构" ], "concepts": [ { "title": "备份文件可生成不代表能恢复", "body": "逻辑备份包含数据库对象与数据，恢复需要兼容的工具、角色与目标环境。单库 pg_dump 不包含整个实例的角色定义，也不能独自提供任意时间点恢复；严格 RPO 需要基础备份与 WAL 归档等方案。" }, { "title": "RPO 和 RTO 是验收条件", "body": "RPO 是可接受的数据丢失时间范围，RTO 是恢复服务需要的时间上限。备份频率、保留、异地副本与恢复速度必须与业务目标一致。本课实际测量恢复步骤，而不把本机几秒恢复推断为线上保证。" }, { "title": "结构变更考虑新旧代码并存", "body": "增加可空列通常比直接删除或改名更容易兼容。先加字段，再部署兼容代码，分批回填并验证，最后收紧约束。回滚代码不意味着可以随意 DROP 已有用户数据的新列，破坏性变更需要单独恢复设计。" } ], "steps": [ { "title": "生成备份与源库验收数据", "body": "以下 Linux Bash 在 notes-service 执行，需要 PostgreSQL 16 客户端 pg_dump、psql、pg_restore；沿用 PGHOST/PGPORT/PGDATABASE，PGUSER 使用 app_user 且注入其密码。备份目录限制权限。命令失败必须停止，不继续上传空文件。", "code": "set -e\nmkdir -p backups\nchmod 700 backups\npg_dump --version\npg_dump -Fc --no-owner --no-acl -f backups/notes_lab.dump\nsha256sum backups/notes_lab.dump > backups/notes_lab.dump.sha256\npg_restore --list backups/notes_lab.dump > backups/notes_lab.contents.txt\npsql -At -v ON_ERROR_STOP=1 -c \"SELECT count(*),min(id),max(id),count(*) FILTER(WHERE pinned) FROM notes\" > backups/source-notes.txt\nsha256sum -c backups/notes_lab.dump.sha256", "lang": "bash" }, { "title": "创建隔离恢复目标并恢复", "body": "管理连接执行 CREATE DATABASE notes_restore OWNER app_user;，只在本机首次创建该专用恢复库。不要向原 notes_lab 恢复。下面 --no-owner --no-acl 使本课恢复对象由 app_user 持有，权限在恢复后按第 11 课脚本重建；这不是自动恢复所有生产角色。", "code": "# Linux Bash，PGUSER=app_user，使用相应密码\npg_restore --exit-on-error --single-transaction --no-owner --no-acl \\\n -h 127.0.0.1 -p 5433 -U app_user -d notes_restore backups/notes_lab.dump\npsql -d notes_restore -At -v ON_ERROR_STOP=1 \\\n -c \"SELECT count(*),min(id),max(id),count(*) FILTER(WHERE pinned) FROM notes\" > backups/restored-notes.txt\ndiff backups/source-notes.txt backups/restored-notes.txt", "lang": "bash" }, { "title": "核查恢复后的关系与新写入", "body": "使用 app_user 连 notes_restore 执行。反关联查询均应为 0。插入能生成合法新编号，ROLLBACK 避免保留验收笔记；序列可能前进一位，这是正常行为。若源库备份期间持续写入，外部另查的 count 不一定对应 pg_dump 快照；本课在停止练习写入后对照。", "code": "SELECT count(*) FROM note_tags nt LEFT JOIN notes n ON n.id=nt.note_id WHERE n.id IS NULL;\nSELECT count(*) FROM note_tags nt LEFT JOIN tags t ON t.id=nt.tag_id WHERE t.id IS NULL;\nBEGIN;\nINSERT INTO notes(title) VALUES ('db12-restore-probe') RETURNING id,title;\nROLLBACK;\n\\d notes\n\\d note_tags", "lang": "sql" }, { "title": "在练习源库做一次兼容扩展迁移", "body": "重新连接 notes_lab / app_user。创建 archived_at 可空列表示未归档；保存为 sql/003_archived.sql，使用 psql -v ON_ERROR_STOP=1 -f sql/003_archived.sql 执行一次。短 lock_timeout 保证拿不到结构锁时尽快失败，再由人检查阻塞后择机重试。它不能保证 DDL 永远无阻塞。", "code": "BEGIN;\nSET LOCAL lock_timeout='1s';\nSET LOCAL statement_timeout='5s';\nALTER TABLE notes ADD COLUMN archived_at timestamptz;\nCOMMIT;", "lang": "sql", "filename": "sql/003_archived.sql" }, { "title": "验证新旧访问兼容并记录恢复方案", "body": "旧查询只选择明确列名，不受新列影响。新查询把 archived_at IS NULL 当作活动笔记。故障演练是在恢复库模拟错误更新再从备份另建恢复目标，不覆盖源库。本课不实际给出删除全表语句；验收恢复耗时、权限重建与业务请求都必须列入恢复记录。", "code": "SELECT id,title,pinned FROM notes ORDER BY id DESC LIMIT 3;\nSELECT id,title FROM notes WHERE archived_at IS NULL ORDER BY id DESC LIMIT 3;\nSELECT column_name,is_nullable,data_type\nFROM information_schema.columns\nWHERE table_name='notes' AND column_name='archived_at';\n-- is_nullable=YES，data_type=timestamp with time zone", "lang": "sql" } ], "checks": [ "备份校验和正确，pg_restore 清单包含业务表、约束和数据。", "独立恢复库行数与静止源库一致，外键无孤儿，新插入成功。", "新增字段后旧查询与新查询都可运行，迁移失败有停止和重试策略。" ], "pitfalls": [ { "symptom": "备份命令成功，但恢复时缺角色或权限", "cause": "把单库逻辑备份当成完整实例备份，未规划角色与授权。", "fix": "在恢复流程中显式重建角色和授权，或由受控配置管理维护；本课使用 no-owner/no-acl 后重新授权。" }, { "symptom": "上线加字段一直等待，API 也开始变慢", "cause": "DDL 正在等待强锁，可能与长事务形成阻塞队列。", "fix": "用短 lock_timeout 退出，查等待链并缩短长事务；在明确窗口重试，不无限等锁。" }, { "symptom": "恢复行数不等于备份后源库行数", "cause": "源库继续写入，两个统计不属于同一快照。", "fix": "练习对比时暂停写入；生产验收使用与备份快照一致的方法或业务不变量，不把后续变化误判为备份损坏。" } ], "exercise": { "task": "为“每日备份、允许最多丢失 15 分钟数据”的需求判断现有方案是否合格，并写出补充项。", "hint": "先将备份间隔与 RPO 对照，再考虑恢复演练。", "answer": "单独每日 pg_dump 无法满足 15 分钟 RPO。需要能够持续归档的 WAL 与基础备份或受管数据库时间点恢复，并验证归档延迟、保留期、异地副本、恢复步骤和监控；按目标时间点实际演练并测量 RTO。" }, "refs": [ { "label": "PostgreSQL 16：pg_dump", "url": "https://www.postgresql.org/docs/16/app-pgdump.html" }, { "label": "PostgreSQL 16：pg_restore", "url": "https://www.postgresql.org/docs/16/app-pgrestore.html" }, { "label": "PostgreSQL 16：持续归档与时间点恢复", "url": "https://www.postgresql.org/docs/16/continuous-archiving.html" }, { "label": "PostgreSQL 16：ALTER TABLE", "url": "https://www.postgresql.org/docs/16/sql-altertable.html" } ], "production": { "scenario": "发布结构变更之前，需要证明数据库可恢复，旧版本服务仍能短暂并存。", "decisions": [ "恢复目标与源库严格分开。", "备份验收覆盖数据、约束、权限与新写入。", "新增字段先兼容，再部署和回填；迁移文件纳入版本管理。" ], "failureDrill": "在独立 notes_restore 检查备份恢复，然后在 notes_lab 用短锁超时演练新增可空字段；所有操作保持目标库可辨认。", "acceptance": [ "记录实际恢复耗时与备份时间。", "恢复库能完成业务 CRUD。", "迁移前后访问兼容，生产 RPO/RTO 不由本机测试推定。" ] } } ]