数据库 · XB 现场笔记

Postgres 的 jsonb 专为查询而生

Sat, 04 Dec 2027 00:00:00 +0000

PostgreSQL 提供两种 JSON 存储类型，它们承担的表示成本不同。json 验证并保留输入文本，jsonb 把文本转换成拆解后的二进制值。两者都能提取字段和路径。选择类型时，需要回答的是是否必须保留文本形态、是否反复处理文档，以及真实查询需要哪些算子，而不是简单判断能不能读取内部字段。

图中的 json 文本仅为显示而换行，对象布局为示意。数组保留顺序及重复元素；原始请求字节应另行保存。

保留文本还是保留结构值

json 会保留无意义空白、对象键的顺序和重复对象键。处理函数仍需要解析这些文本，遇到重复键时，以最后一个值作为有效值。因此，存储保留了重复项，并不代表每个消费方都会得出同样解释。不要把重复键当成应用契约中有意义的数据结构，否则跨语言解析时很容易产生分歧。

jsonb 去掉无意义空白和对象键顺序，同一个对象键只保留最后一次出现的值。这里说的是对象：数组仍然保留元素顺序和重复元素。数组的包含判断有自己的匹配规则，不能因为包含查询把两个数组视为匹配，就反推存储时发生了排序或去重。表示、相等比较和包含关系是三个需要分别理解的问题。

这种二进制格式属于 PostgreSQL，并不是 BSON，也不是可跨系统使用的签名格式。jsonb 输出的文本没有承诺遵循某个外部 JSON 规范化算法。如果签名覆盖原始请求字节，应另外保留这些字节，例如使用 bytea，并针对该表示验证签名。json 保留的是接收后的 JSON 文本；客户端编码转换和协议处理可能已改变网络上的原始字节，因此不能把它当成任意请求的逐字节归档。

两种类型都支持路径提取

两者都支持用 -> 提取 JSON 值，用 ->> 提取文本，以及用 #>、#>> 读取嵌套路径。读取 json 内部字段时，不需要先把整篇文档强制转换成 jsonb。性能区别在于重新解析文本还是处理已经拆解的表示，而不是 json 缺少这些操作符。

jsonb 还支持结构包含、键存在判断和 GIN 等索引策略。从两种类型提取出的标量表达式，也可以按实际需要建立适当的表达式索引。能否使用索引仍取决于准确的表达式、算子和负载，选了 jsonb 不代表任意嵌套条件都会变快。经常参与关联、约束或排序的字段，往往更适合独立的有类型列，以明确数据契约并方便优化。

输入成本和处理成本需要同时考虑。jsonb 转换时要做额外工作，某些文档占用的空间也可能更大。两种类型接受的输入几乎相同，但并非完全一致：PostgreSQL 的 numeric 范围限制和更严格的 Unicode 处理，会让某些可以存成 json 文本的输入无法转换成 jsonb。迁移现有列前，应检查有代表性的真实载荷，特别是极大数字和转义字符，不能只用一个短小示例推断整个数据集。

坏掉的样子

把 json 改为 jsonb，可能破坏导出程序依赖的原始表示。换类型也不等于执行应用 schema 校验：合法的 JSON 字符串、数字或数组仍然是 JSON，即使业务只接受对象。需要哪些字段、字段能取什么值，应通过实际结构和业务约束表达，不能把语法有效误当成业务有效。

更隐蔽的问题是默认所有解析器对重复键的解释一致。数据库采用最后值，并不能证明上游签名程序或下游读取程序采用了同一规则。需要一致理解的边界，应拒绝有歧义的输入。读取结果时，也要区分路径缺失、JSON null 和 SQL NULL；把三者全部转换成没有说明的空字符串，会丢掉排查和校验所需的信息。

快速验证

把下面内容保存为 json-types.sql，在可丢弃的 PostgreSQL 18 数据库中执行 psql -X -v ON_ERROR_STOP=1 -f json-types.sql。脚本只在事务内创建一张临时表，末尾回滚，数据和对象都不会留下。

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE sample (raw json, parsed jsonb);
INSERT INTO sample VALUES ('{ "b": 2, "a": 1, "a": 3 }','{ "b": 2, "a": 1, "a": 3 }');
SELECT raw::text, parsed::text, raw->>'a' AS json_a, parsed->>'a' AS jsonb_a FROM sample;
SELECT '{"user":{"name":"Ada"}}'::json #>> '{user,name}' AS json_path;
DO $$ BEGIN
 IF (SELECT raw::text FROM sample) IS DISTINCT FROM '{ "b": 2, "a": 1, "a": 3 }' THEN
 RAISE EXCEPTION 'json text was changed';
 END IF;
 IF (SELECT parsed FROM sample) IS DISTINCT FROM '{"a":3,"b":2}'::jsonb THEN
 RAISE EXCEPTION 'unexpected jsonb value';
 END IF;
 IF (SELECT raw->>'a' FROM sample) IS DISTINCT FROM '3' THEN
 RAISE EXCEPTION 'json extraction did not use the last duplicate key';
 END IF;
 IF '[2,1]'::jsonb = '[1,2]'::jsonb THEN
 RAISE EXCEPTION 'jsonb array order was ignored';
 END IF;
 IF '[2,1,2]'::jsonb = '[2,1]'::jsonb THEN
 RAISE EXCEPTION 'jsonb duplicate array elements were ignored';
 END IF;
END $$;
DO $$ BEGIN
 PERFORM '{broken'::json;
 RAISE EXCEPTION 'invalid JSON accepted';
EXCEPTION WHEN invalid_text_representation THEN RAISE NOTICE 'invalid JSON rejected';
END $$;
ROLLBACK;

历史 PostgreSQL 18.6 单用户检查记录的结果是（未验证 psql，本次未重跑）：raw 保持原来的空白文本；parsed 显示重新格式化、包含 a=3、b=2 的对象；两种提取表达式都返回 3。直接在 json 上读取嵌套路径，也能得到 Ada。断言覆盖保留文本、jsonb 对象值、json 字段提取，以及考虑顺序和重复元素的数组相等比较；jsonb 字段提取与嵌套路径仅打印结果，需要另行核对。捕获到预期的非法输入错误后，会打印“invalid JSON rejected”提示。如果错误类型变化或无效 JSON 被接受，脚本不会把它默认为成功。

这个实验验证表示与提取行为，并没有比较速度或存储效率。迁移生产列前，还要分别测量真实文档大小、写入频率和查询计划，确认转换失败数据的处理方式，以及哪些表示信息允许丢失。只有把这些取舍说明清楚后，才能决定是否替换原始数据；不能仅凭示例成功就删除仍然需要用于回放或签名校验的原文。

来源

PostgreSQL JSON 类型，表示形式、输入限制和索引，已核验 2026-10-15。
PostgreSQL JSON 函数与操作符，两种类型的提取操作符和空值行为，已核验 2026-10-15。

泄漏的连接会把连接池榨干

Fri, 05 Nov 2027 00:00:00 +0000

连接池泄漏首先是所有权问题：业务工作已经结束，但它借走的连接仍然处于借出状态。此时数据库可能仍然正常响应其他客户端，只有这个应用拿不到连接。应把归还资源视为操作契约的一部分，覆盖异常和提前返回，而不是只在成功路径末尾顺手清理一下。

一份借用应当有明确的主人和终点

SQLAlchemy Connection 表示从 Engine 所属池中取得的一次借用。关闭这个 Connection，通常是把底层 DBAPI 连接还回池里，而不一定真正断开数据库连接。归还借用与提交事务是两个独立决定：池可以运转正常，但业务修改已经回滚；池也可能耗尽，而底层数据库连接全部仍然存活。只检查连接是否活着，无法回答谁还占着它。

资源作用域应尽量短，但不能破坏事务要求的原子性。with engine.begin() 在代码块成功时提交，失败时回滚，并释放连接；with engine.connect() 管理的是连接作用域，不承诺自动提交写入，关闭时尚未结束的事务会被回滚。两者看起来都用了 with，但持久化语义不同，不能为了“统一写法”随意互换，否则资源不再泄漏了，数据却可能没有保存。

与当前事务无关的远程等待、用户交互，不应长时间占着事务和连接。这并不意味着可以把必须一起提交的变更拆开。若连接由调用方拥有，辅助函数不应私自关闭；若辅助函数自己借用，就应负责归还，或者在接口中明确把所有权交给谁。只有打开次数的指标，却说不清每份借用由谁结束，仍然没有定位真正的生命周期边界。

坏掉的样子

漏掉一次归还，就减少一份可用容量，后来者开始排队或超时。对于配置了有限容量和获取超时的 QueuePool，新调用并非一定永远挂住，而是可能在执行 SQL 之前就收到池超时。把上限调大可以暂时推迟复发，却也增加数据库压力；缺失的归还路径依然存在，不能算修复。

不过，“池满了”不是泄漏的充分证据。真实并发、长事务、数据库锁等待或应用自身死锁，都可能占住全部借用。数据库 CPU 很低也不决定原因，因为应用可能握着连接等待别的事情。需要把借出数量、获取等待、持有年龄、事务状态和仍在进行的业务工作关联起来，判断这些连接是否还处于合理的使用范围。

一个有说服力的泄漏复现，应证明已经结束的工作仍然保留借用，并且归还这些具体借用后容量恢复。不要依赖垃圾回收及时释放；对象何时被回收不是可靠的资源归还契约。Engine.dispose() 也不能强制收回仍然借出的连接，它处理的是池内已经空闲的连接。重启进程可能暂时清空症状，但不会改变下一次请求重新走进同一遗漏分支的事实。

连接池容量与持久化记录各有生命周期。保留的原样输出支持此本地示例，当前依赖工作流仍待验证。

快速验证

在 macOS 或 Linux 的空目录运行 python3 -m venv .venv，然后执行 .venv/bin/python -m pip install SQLAlchemy==2.0.52。把下面保存为 pool_probe.py，执行 .venv/bin/python pool_probe.py。原文报告使用 Python 3.14.4 和 SQLite 3.53.0；保留的原样代码输出记录 Python 3.12.14、SQLAlchemy 2.0.52 与 SQLite 3.53.1，本轮没有重跑安装或连接池练习。执行时应启用 Python 断言。数据库文件只存在于脚本自己的临时目录，结束后自动清理，不会访问生产数据库。

from pathlib import Path
from tempfile import TemporaryDirectory

import sqlalchemy
from sqlalchemy import create_engine
from sqlalchemy.exc import TimeoutError as PoolTimeout
from sqlalchemy.pool import QueuePool


class WorkFailed(Exception):
 pass


assert sqlalchemy.__version__ == "2.0.52"
with TemporaryDirectory(prefix="pool-leak-") as directory:
 engine = create_engine(
 "sqlite:///" + str(Path(directory) / "probe.db"),
 poolclass=QueuePool, pool_size=2, max_overflow=0, pool_timeout=0.05,
 )
 borrowed = []
 try:
 with engine.begin() as connection:
 connection.exec_driver_sql("CREATE TABLE ledger(id INTEGER PRIMARY KEY)")
 for _ in range(2):
 borrowed.append(engine.connect()) # Deliberately retain both leases.
 assert engine.pool.checkedout() == 2
 try:
 unexpected = engine.connect()
 except PoolTimeout:
 pass
 else:
 unexpected.close()
 raise AssertionError("retained leases must exhaust the two-slot pool")
 assert engine.pool.checkedout() == 2
 print("two retained leases exhaust the pool; the next checkout times out")

 borrowed[0].close()
 with engine.begin() as connection:
 connection.exec_driver_sql("INSERT INTO ledger VALUES (1)")
 assert engine.pool.checkedout() == 1
 print("returning one lease restores capacity without enlarging the pool")

 try:
 with engine.begin() as connection:
 connection.exec_driver_sql("INSERT INTO ledger VALUES (2)")
 raise WorkFailed("injected after the insert")
 except WorkFailed:
 pass
 assert engine.pool.checkedout() == 1
 with engine.connect() as connection:
 assert connection.exec_driver_sql("SELECT id FROM ledger").scalars().all() == [1]
 connection.exec_driver_sql("INSERT INTO ledger VALUES (3)")
 # No commit: this connection context rolls back when it closes.
 with engine.connect() as connection:
 assert connection.exec_driver_sql("SELECT id FROM ledger").scalars().all() == [1]
 print("an exception rolls back row 2 and returns its lease; closing without commit also removes row 3")

 def early_return():
 with engine.connect() as connection:
 return connection.exec_driver_sql("SELECT 1").scalar_one()

 assert early_return() == 1 and engine.pool.checkedout() == 1
 with engine.begin() as connection:
 connection.exec_driver_sql("INSERT INTO ledger VALUES (4)")
 with engine.connect() as connection:
 rows = connection.exec_driver_sql("SELECT id FROM ledger ORDER BY id").scalars().all()
 assert rows == [1, 4] and engine.pool.checkedout() == 1
 borrowed[1].close()
 assert engine.pool.checkedout() == 0 and engine.pool.checkedin() == 2
 print("early return releases its lease; successful transaction commits row 4; final rows", rows)
 finally:
 for connection in borrowed:
 connection.close()
 engine.dispose()

列表刻意保留两条借用的强引用，使模拟泄漏不依赖垃圾回收是否碰巧及时运行。第三次获取必须抛出 PoolTimeout。归还第一条后，不扩大池也能插入并提交编号一的记录，证明恢复来自资源归还，而不是新增连接预算。此时另一条故意保留的借用仍然存在，所以每次正常作用域结束后，预期借出计数是一，而不是零。

接着在插入编号二之后注入 WorkFailed。异常离开事务上下文，插入被回滚，借用也归还。另一段连接上下文插入编号三，却没有 commit；关闭连接同样回滚这条记录。提前 return 的函数也仍然执行上下文退出，因此不会绕过归还。最后用成功事务提交编号四，排序后的查询结果必须严格等于 [1, 4]，同时证明哪些路径提交、哪些路径回滚，而不只是打印“执行成功”。

关闭最后一条故意保留的借用后，借出数量降为零，池内仍有两条可复用的空闲物理连接。最后的清理先归还所有保留句柄，再 dispose Engine。这些断言验证的是本地池计数和事务结果，不是生产锁竞争、取消传播或分布式副作用；归还连接不会撤销已经发送到其他系统的 HTTP 调用。真正修改容量前，应把同样的所有权检查放到业务实际失败路径上，再决定问题是泄漏、持有过久还是容量确实不足。

来源

SQLAlchemy 连接池，借用、归还与有限 QueuePool 上限，已核验 2026-09-09。
SQLAlchemy Engine 与 Connection，事务上下文、关闭与 dispose 语义，已核验 2026-09-09。
SQLAlchemy 连接池耗尽错误，泄漏、长事务、并发与死锁原因，已核验 2026-09-09。

LSM 树把前台写入成本转移到后续归并

Tue, 02 Nov 2027 00:00:00 +0000

LSM 树把一部分分散更新的成本转移到内存缓冲与后续归并。这是一种设计取舍，不是“所有磁盘操作从此完全顺序”的承诺，也不保证随机写一定胜过 B 树。真正需要回答的问题，是前台写入、后台压实、读取和保留版本，能否同时放进同一份资源预算。不能用一个没有提供数据生成器的精确耗时，替代对实际工作负载的解释。

缓冲改变工作的发生时机

RocksDB 通常把新写入放入内存表，并可同时写入预写日志。是否启用 WAL、是否同步日志，是另外的持久性选择；仅仅采用 LSM 布局，不保证每个已应答写入都能抵御断电。内存表填满后刷成不可变有序表，产生零层文件，应用则通过其他可用缓冲继续写入。日志追加、刷盘和压实也不是同一个动作。

采用分层压实时，零层文件的键范围可以重叠。更深的层通常各自组成一个有序段，但一个段可以按键范围拆为多个不重叠 SST 文件，不能理解为每层只有一个文件。查找先利用文件范围选择候选，压实则把重叠区间归并成替代文件。动态层大小配置还可能让某些中间层为空，因此不能把所有层永远填满的示意图当作运行事实。

读取仍然需要处理多个版本

同一个键的旧值可能存在于多个段中。读取要选择可见版本，而删除标记必须阻止更老的值重新出现。布隆过滤器可以排除肯定不含目标键的候选文件；返回可能存在后，仍需进一步检查。一次最终成功的查找，也能通过过滤器跳过不相关文件，再到真正包含答案的文件中读取。因此，“过滤器只帮助未命中，对命中毫无作用”并不准确。

压实通过重写数据，降低这种搜索和空间负担。分层策略与通用策略通常在写放大、读放大、空间放大之间作不同选择，但真实结果仍取决于负载、压缩、缓存和配置。统计时必须统一口径：SST 写入字节、WAL 字节、设备写入字节与应用逻辑字节不是同一种量。不写清分子分母的倍率，不能直接用来规划存储吞吐。

坏掉的样子

刷盘或压实跟不上时，不可变缓冲和零层文件可能积累，读取成本上升，引擎还可能减速或暂停前台写入。历史阻塞计数非零，不足以诊断今天的瓶颈。应同时查看最近的阻塞时间、待处理工作、文件数量、存储延迟与应用吞吐。提高阈值可能暂时推迟压力，却把更多工作留到后面，并扩大恢复时需要处理的积压。

删除不会立刻回收所有旧值。只要更低的段仍可能暴露被遮住的值，或保留快照需要相关历史，墓碑就不能随意消失。回收空间取决于压实覆盖了哪些历史，以及版本保留规则是否允许丢弃。若数据已经全部删除，活跃字节数为零，就不能再报告一个有限的“物理字节除以活跃字节”空间放大率；此时应直接报告残留字节与回收条件。

归并版本，保留删除语义。依据原文绘制机制；模型值与原文报告的观察不代表本次运行测试。

快速验证

把程序保存为 lsm_model.py，用 Python 3 执行。它明确只是标准库内存模型，展示三个刷出段和覆盖全部历史的压实。程序不会执行 RocksDB，不会创建真正 SST，不做磁盘输入输出，不模拟引擎调度，也不测延迟。打印的计数不能被重新包装成生产性能结果；示例的作用是把版本选择与墓碑删除条件具体化。

from pprint import pprint

# A semantic model: sorted in-memory runs, not RocksDB or a disk benchmark.
runs = [] # newest run first
writes = 0
sequence = 0

def flush(operations):
 global writes, sequence
 memtable = {}
 for key, value in operations:
 sequence += 1
 memtable[key] = (sequence, value)
 run = dict(sorted(memtable.items()))
 runs.insert(0, run)
 writes += len(run)

def get(key, tables):
 for run in tables:
 if key in run:
 return run[key][1] # None is a tombstone: stop searching.
 return None

flush([("a", "one"), ("b", "old")])
flush([("a", "two"), ("c", "three")])
flush([("b", None)])
assert [get(k, runs) for k in "abc"] == ["two", None, "three"]
assert writes == 5 and sequence == 5
# Dropping a tombstone from only the newest run resurrects old b.
unsafe = [{k: v for k, v in runs[0].items() if v[1] is not None}] + runs[1:]
assert get("b", unsafe) == "old"
# Merge ALL history, with no retained snapshots, before dropping tombstones.
latest = {}
for run in reversed(runs):
 latest.update(run)
merged = {k: v for k, v in sorted(latest.items()) if v[1] is not None}
writes += len(merged)
assert [get(k, [merged]) for k in "abc"] == ["two", None, "three"]
assert (len(merged), writes, sequence) == (2, 7, 5)
pprint({"live_keys": list(merged), "logical_operations": sequence,
 "table_records_written": writes, "record_write_ratio": writes / sequence,
 "unsafe_partial_merge_resurrects": get("b", unsafe)})

第一次刷出保存 a 和 b；第二次替换 a 并新增 c；第三次删除 b。跨所有段读取时得到新的 a、缺失的 b 和 c。反例刻意只从最新段移除墓碑，结果旧段中的 b 重新出现。这说明一条表面上没有业务值的删除记录，仍可能承担遮住历史版本的职责，不能因为它“看起来没用了”就局部删除。

安全的模型归并检查全部段，并假设没有保留快照，最后只保留两个值。这次合并再写两个表记录，因此五个逻辑操作总共写出七个记录，记录数倍率为一点四。这不是字节写放大：值大小差异、WAL、压缩、元数据，以及真实引擎的中间压实都没有被计算。模型还没有模拟快照读取、并发写入或崩溃恢复，不能把这些性质附加到结果上。

对真实引擎，应在隔离数据库中重现代表性的插入、更新、删除和读取，记录选项与硬件，再检查实际计数器。SQLite 的顺序与乱序更新耗时，不足以证明 RocksDB 的行为；后台吞吐缺口也不能直接推出多久填满磁盘，除非另有关于保留、回收、限流和可用容量的模型。先明确每个观测量表示什么，再判断究竟需要更多带宽、更少版本、不同压实策略，还是更合适的写入节奏。

来源

RocksDB 概览，内存表、可选 WAL、持久性与压实，已核验 2026-10-15。
RocksDB 分层压实，有序段、文件、层大小与积压，已核验 2026-10-15。
RocksDB 布隆过滤器，候选过滤与假阳性，已核验 2026-10-15。
RocksDB 快照，压实时保留版本的要求，已核验 2026-10-15。

检查点为恢复建立起点

Sun, 17 Oct 2027 00:00:00 +0000

检查点记录一部分已经完成的工作，使数据库恢复不必把整个日志历史都视为待处理内容。具体操作取决于引擎：PostgreSQL 同步检查点要求的数据变更，建立重做起点；SQLite 的 WAL 模式则把符合条件的已提交页面帧从日志转移到主数据库文件。两者都不能简单当作事务提交的另一个名字。

坏掉的样子

已经请求检查点与检查点完整完成，是两个不同观察。SQLite 读者可能持有旧快照，阻止较新的日志帧写入主文件，或者阻止日志重置。被动检查点可以只做当前能够完成的部分，然后正常返回。若只看成功标志，不看日志总帧数与已完成帧数，就会漏掉尚未处理的工作，以及那个仍然阻止完成的读事务。

日志大小也要放在具体上下文中理解。文件可以继续复用原有空间，因此已分配大小不变时，检查点进度仍可能推进。PostgreSQL 完成检查点之后，也可能继续为归档或复制槽保留旧日志。为了让磁盘曲线变小而手动删除日志，会破坏恢复材料。应先核对引擎进度和保留义务，再判断文件大小究竟代表什么。

检查点间隔不是恢复时间的硬上限。重放速度、存储吞吐、写入形态以及实际崩溃位置，都会影响恢复耗时。更频繁的检查点可能减少未来重做，也可能增加平时写流量。把日志放到另一块设备，不会把所有数据页写入也搬过去，更不会使检查点的写盘成本自动消失。参数选择需要对应具体工作负载。

SQLite 的完成依赖旧读者释放；更新早于最终检查点提交。这里只保留历史本地证据。

快速验证

把下面内容保存为 checkpoint_lab.py，使用普通的 python3 checkpoint_lab.py 运行，保持断言开启。脚本只使用标准库 SQLite 模块与私有临时文件。本次记录来自 Python 3.14.4 搭配 SQLite 3.53.0。比较结果时应同时查看运行时的引擎版本，因为 Python 版本与实际链接的 SQLite 版本并不是一回事。

import sqlite3
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory(prefix="xbcatm-checkpoint-") as directory:
 path = Path(directory) / "test.db"
 writer = sqlite3.connect(path, isolation_level=None, timeout=0.1)
 reader = sqlite3.connect(path, isolation_level=None, timeout=0.1)
 try:
 assert writer.execute("PRAGMA journal_mode=WAL").fetchone() == ("wal",)
 writer.execute("PRAGMA synchronous=FULL")
 writer.execute("PRAGMA wal_autocheckpoint=0")
 writer.execute("CREATE TABLE marker (id INTEGER PRIMARY KEY, value INTEGER)")
 writer.execute("INSERT INTO marker VALUES (1,10)")
 assert writer.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone() == (0, 0, 0)
 reader.execute("BEGIN")
 assert reader.execute("SELECT value FROM marker").fetchone() == (10,)
 writer.execute("UPDATE marker SET value=20 WHERE id=1")
 assert writer.execute("SELECT value FROM marker").fetchone() == (20,)
 passive = writer.execute("PRAGMA wal_checkpoint(PASSIVE)").fetchone()
 blocked = writer.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()
 print("passive", passive)
 print("truncate_with_reader", blocked)
 assert passive[0] == 0 and passive[1] > passive[2] >= 0
 assert blocked[0] == 1 and blocked[1] > blocked[2]
 assert Path(str(path) + "-wal").stat().st_size > 0
 assert reader.execute("SELECT value FROM marker").fetchone() == (10,)
 reader.execute("COMMIT")
 completed = writer.execute("PRAGMA wal_checkpoint(TRUNCATE)").fetchone()
 print("truncate_after_reader", completed)
 assert completed == (0, 0, 0)
 assert Path(str(path) + "-wal").stat().st_size == 0
 assert reader.execute("SELECT value FROM marker").fetchone() == (20,)
 print("fresh_reader", 20)
 finally:
 reader.close()
 writer.close()

初始截断检查点把值十写入主文件，并重置日志。随后一个读者显式开启事务，读取十；另一个连接在关闭自动检查点之后，把值二十提交。写者立刻就能读到二十，而旧读者仍然需要自己的原始快照。这个顺序用真实连接建立约束，不依赖线程恰好在某个微小时间窗口发生竞争。

本次被动检查点得到三个数字零、一、零：没有报告阻塞失败，日志里存在一帧，尚未完成任何一帧。断言刻意检查帧数之间的关系，而不是要求所有引擎构建都产生完全相同的数字。这里关键的是被动调用成功返回，却仍然留下待处理工作，不能把第一个零直接当成“全部检查点工作已完成”。

接下来的截断请求在短暂忙等待后，返回一、一、零。第一个字段表示请求的完成动作受阻。日志仍然非空，旧读者仍然看到十。因此，Python 调用没有抛出异常、而是返回了一个元组，并不能证明截断已经成功；调用方必须检查元组中代表状态和进度的各个字段，才能正确解释结果。

旧读者提交之后，再次截断得到零、零、零。脚本不仅检查返回值，还确认实际日志文件长度为零，并确认新读取看到二十。值二十在最后这次检查点之前就已经提交，最后一步改变的是日志与主文件之间的状态。即使断言失败，两个连接仍会关闭，临时目录也会清理。

诊断尚未完成的工作

对于 SQLite，如果检查点不能完成，应查看长期持有的读事务与尚未结束的游标。然后决定只推进被动检查点是否足够，还是需要在受控维护窗口执行会等待的检查点。增加忙等待超时，只是对同一约束多等一会儿，不会替应用释放事务。每次写入后都强制截断，还可能增加竞争，抵消日志模式带来的并发收益。

对于 PostgreSQL，应使用与实际部署版本匹配的检查点和日志保留统计。检查点已经完成、旧日志仍被保留、业务事务还在继续，可以同时成立。调整频率时应比较前台请求延迟与实际重启演练结果，不要只看某个文件终于缩小。这个夹具验证的是 SQLite 的完成边界，没有测量生产恢复时间目标，也不表示所有数据库都提供相同的检查点接口。

来源

SQLite 预写日志，读者快照、检查点进度与日志复用，已核验 2026-09-12。
SQLite 检查点接口，被动、重启与截断模式的完成语义，已核验 2026-09-12。
SQLite 检查点指令，返回的忙标志与帧数，已核验 2026-09-12。
PostgreSQL 18 WAL 与检查点，检查点代价及独立的日志保留要求，已核验 2026-09-12。

预备语句把取值与 SQL 结构分开

Sat, 16 Oct 2027 00:00:00 +0000

参数绑定为数据库中的取值提供一个明确位置。姓名里即使带有引号或分号，也仍然只是值，不会因此变成另一段查询条件。复用命名预备语句则是另一项优化：服务端能够在同一个会话内，跨多次执行保留语句信息。安全地绑定数据，并不要求应用为每一条查询都显式建立一个命名语句，也不要求先证明查询会频繁重复。

绑定保护 SQL 语法边界，却不会禁用取值内部仍需解释的语言。例如，绑定后的 LIKE 模式仍把百分号与下划线当成通配符。入口究竟接收模式，还是字面子串，需要另行约定，必要时按该运算符的规则转义。正则、全文检索和业务授权同样具有绑定之后的语义，不能因为成功参数化就认为输入已经符合全部产品约束。

坏掉的样子

在 Psycopg 中，占位符 %s 属于驱动接口，不是让程序使用 Python 字符串格式化。值应作为 execute 的第二个参数传入，占位符不要加引号，只有一个位置参数时也需要单元素元组。如果先把值插入字符串，再调用一个支持参数化的接口，原本希望保护的边界早就已经被越过；接口名称本身不会替程序补救这次拼接。

占位符代表值，不代表表名、列名或关键字。动态标识符需要明确的结构选择：先用白名单限制支持的列，再用驱动的标识符组合功能正确引用选中的列名。升降序关键字也应由应用控制。分页的数量与偏移量可以直接绑定，同时仍须按产品要求验证范围。能在语法上接收一个整数，不代表允许请求任意大的页面或无限制消耗资源。

预备语句不会把第一次的执行计划永久钉死。PostgreSQL 区分根据本次参数生成的定制计划，以及跨不同参数复用的通用计划；自动选择时会考虑规划开销与估算执行成本。模式或统计信息变化也可能触发重新规划。因此，语句保持参数化时，访问路径仍可以变化。是否复用某种计划，与输入能否变成 SQL 语法，是不同的性质，不能混为一谈。

命名语句为零时仍可绑定。命名复用和定制／通用计划是独立性质。原文实验未重跑；强制模式不说明延迟。

快速验证

准备安装了 Psycopg 3 的 Python 环境，把 PG_DSN 设置为可丢弃的 PostgreSQL 数据库连接。连接配置沿用已有安全提供方式。实测版本为 Psycopg 3.3.5 与 PostgreSQL 18.6。将下面代码保存为 Python 文件，在已设置该环境变量的终端执行。使用的是临时表，连接关闭后会自动消失：

import os
import psycopg
from psycopg import sql

with psycopg.connect(os.environ['PG_DSN'], autocommit=True,
 prepare_threshold=5) as conn:
 conn.execute('CREATE TEMP TABLE people (id integer PRIMARY KEY, label text NOT NULL)')
 conn.execute("INSERT INTO people VALUES (1,'alice'),(2,'bob')")
 query = 'SELECT id FROM people WHERE label=%s ORDER BY id LIMIT %s'
 hostile = "' OR true --"
 assert conn.execute(query, (hostile, 10), prepare=False).fetchall() == []
 count = conn.execute('SELECT count(*) FROM pg_prepared_statements').fetchone()[0]
 assert count == 0
 print('bound without named preparation:', count, 'named statements; no match')
 for value in ("O'Reilly", r'a\b', 'x; DROP TABLE people; --'):
 assert conn.execute('SELECT %s::text', (value,), prepare=False).fetchone() == (value,)
 for label, expected in (('alice', [(1,)]), ('bob', [(2,)])):
 assert conn.execute(query, (label, 10), prepare=True).fetchall() == expected
 assert conn.execute('SELECT count(*) FROM pg_prepared_statements').fetchone() == (1,)
 print('named preparation reused: alice=1, bob=2')

 def ordered(column, limit):
 if column not in {'id', 'label'}:
 raise ValueError('unsupported sort column')
 if type(limit) is not int or not 1 <= limit <= 100:
 raise ValueError('limit must be an integer from 1 through 100')
 statement = sql.SQL('SELECT id FROM people ORDER BY {} LIMIT %s').format(
 sql.Identifier(column))
 return conn.execute(statement, (limit,), prepare=False).fetchall()

 assert ordered('label', 1) == [(1,)]
 for column, limit in [('label; DROP TABLE people', 1), ('id', 0), ('id', 101)]:
 try:
 ordered(column, limit)
 except ValueError:
 pass
 else:
 raise AssertionError('invalid request accepted')
 print('identifier allow-list and bound LIMIT checked')

 conn.execute('PREPARE plan_lab(text) AS SELECT id FROM people WHERE label=$1')
 conn.execute('SET plan_cache_mode=force_custom_plan')
 assert conn.execute("EXECUTE plan_lab('alice')").fetchall() == [(1,)]
 counters = "SELECT generic_plans,custom_plans FROM pg_prepared_statements WHERE name='plan_lab'"
 assert conn.execute(counters).fetchone() == (0, 1)
 conn.execute('SET plan_cache_mode=force_generic_plan')
 assert conn.execute("EXECUTE plan_lab('bob')").fetchall() == [(2,)]
 assert conn.execute(counters).fetchone() == (1, 1)
 print('same prepared statement: custom=1, generic=1')
 conn.execute('RESET plan_cache_mode')
 conn.execute('DEALLOCATE plan_lab')

第一项输出显示命名语句数量为零，而且看起来像注入的输入没有匹配任何记录。这次调用明确关闭命名预备，却保留参数绑定，证明安全边界在语句复用之前就存在。随后包含引号、反斜杠、分号的文本都原样返回，表仍可被后面的查询继续使用，字符串里写着删除命令也没有获得执行机会。

接下来两次显式预备调用复用了同一个命名语句，分别返回爱丽丝的编号一和鲍勃的编号二。连接的阈值配置允许显式预备。在本次驱动版本里，如果把 prepare_threshold 设为 None，命名预备整体被禁用，连显式请求也不会创建它。这个设置不等于关闭绑定，不能根据看不到命名语句就断言查询不安全。

排序函数对受支持的列和绑定上限返回一条结果；对不支持的列，以及一至一百之外的页大小，在发送 SQL 前拒绝。标识符引用负责保持语法正确，白名单负责说明这个入口究竟支持哪些合法结构。这两项职责不能交给任意请求文本决定，尤其不能以为加好了引号，就应该允许所有真实存在的列被外部选择。

最后，同一条 SQL 预备语句分别在强制定制计划与强制通用计划下执行。计数从通用零次、定制一次变成两种各一次，两次也都返回正确行。强制设置只是让差异能够稳定观察，并未测量自动模式面对真实倾斜数据会选择什么，更不是建议把整个服务永久改成某一种强制模式。退出前恢复设置并释放命名语句。

在真实部署中观察复用

PostgreSQL 默认的自动策略先用定制计划执行带参数语句，之后再比较通用方案。是否适合复用，需要结合真实参数分布和执行计划判断。这个只有两行数据的实验没有测量延迟，也没有统计协议往返次数；驱动如何批量发送协议消息、连接建立成本与查询本身开销，都会影响最终测量，不能从“预备”二字推导一个固定网络代价。

命名语句属于服务端会话，连接池和事务级代理必须正确处理这段生命周期。部署环境需要明确支持相应的预备语句行为，或者在不支持时关闭命名复用。即使只执行一次查询，也应默认绑定数据。租户过滤、对象授权和结果大小限制仍须单独成立：一条完全参数化的 SQL，也可能因为缺少业务权限条件而返回调用者无权查看的信息。

本次审阅没有改动或重新运行这个操作性实验。文中预期输出和此前的观察，仍需与本次实际执行证据区分。

来源

Psycopg 参数接口，绑定语法与标识符组合，已核验 2026-10-15。
Psycopg 预备语句，阈值、显式预备和会话生命周期，已核验 2026-10-15。
PostgreSQL 18 PREPARE，定制计划、通用计划和自动选择，已核验 2026-10-15。
PostgreSQL 18 模式匹配，LIKE 通配符与转义语义，已核验 2026-10-15。

部分唯一性约束保护有效子集

Fri, 15 Oct 2027 00:00:00 +0000

部分索引只为满足谓词的行保存索引项。需要的子集很小时，它可以缩小索引，但也可以表达只对这个子集生效的完整性规则。例如，同一个座位允许保留多条历史预订，却只能有一条当前有效预订。部分唯一索引可以把这条规则放在数据库边界上执行，而不只是提高某条查询的速度。

成员资格随谓词变化

CREATE INDEX ... WHERE active 只包含 active 为 true 的行，false 和 null 都不满足条件。是否允许 null 是独立的模型选择；下面实验把 active 定义为非空，使每条预订明确处于有效或无效状态。索引键也不必就是谓词中出现的列：这里用 seat 作为键，用 active 决定哪些行参与。

普通写入会改变成员资格。无效记录变成有效记录时，必须进入索引并接受检查；有效记录失效后，则离开当前有效子集。这个边界不是一旦建索引就永远固定的历史分界线。每次写入仍要判断谓词，状态切换也有维护成本，所以索引更小不意味着所有更新都免费，更不能无条件承诺写入一定更快。

唯一性可以只针对子集

在 seat 上建立 WHERE active 的唯一索引，会拒绝同一个座位出现两条有效记录，却允许任意多条无效历史记录。即使没有 SELECT 使用这个索引，数据库仍会执行唯一性检查。因此查询加速与数据完整性是保留索引的两种不同理由，不能只看扫描计数为零就把承担约束的索引删除。

应用先查“有没有”再插入，比数据库约束弱，因为另一个事务可能在检查与写入之间插入。唯一索引会在 PostgreSQL 中协调冲突写入，失败方需要处理唯一性错误或明确选择的冲突策略。下面夹具按确定顺序验证拒绝行为；并发协调属于数据库约束契约，不代表已经实现支付、扣款和跨服务预订的完整业务流程。

查询也要表达同一边界

规划器把部分索引用于访问路径时，必须能够证明查询条件蕴含索引谓词。仅按 seat 查询，并不能证明调用方只需要有效记录，因为历史记录也可能匹配。显式查询 active 记录才可能符合条件，但小表仍可能采用更便宜的顺序扫描。逻辑上相似的表达式，也只有在规划器能够识别其蕴含关系时才有用，不能仅凭人眼觉得相近。

也不要用数百个互相重叠的部分索引模拟分区。规划与维护成本会增长，优化器不会自动把这些独立索引当成一套协调的分区结构。谓词应来自稳定的工作负载或明确完整性需求，再通过真实查询与状态转换验证。建立索引不是给数据打上一个永不变化的标签，而是维护一个持续受规则约束的子集。

坏掉的样子

查询忘写有效状态条件时，可能把旧预订和当前预订一起返回，而唯一索引本身完全没有失效。反过来，应用把这个索引误当成全表唯一，也可能在业务层错误拒绝合法历史。应写清规则约束的是所有行还是当前子集，并同时测试这两类数据。否则列表页、恢复旧记录和导入流程很容易对同一座位产生不同理解。

重新激活失败是另一个关键边界。把旧记录改回 active，可能与当前持有人冲突。失败后旧记录应该仍保持无效，并向调用方报告冲突，不能悄悄替换已有有效预订。批量导入与状态迁移也必须接受同样检查，不能因为它们是运维任务就绕开当前有效唯一性；这样才能让不同写入入口共享同一规则。

谓词成员资格和唯一性转换独立于规划器选路；历史顺序 SQL 不证明并发预订。

快速验证

保存为 partial-unique.sql，使用 psql -X -v ON_ERROR_STOP=1 -f partial-unique.sql 连接可丢弃的 PostgreSQL 18 数据库。实验只创建会话临时预订表，不接触真实座位库存；所有记录和状态变化都在代码中给出。

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE reservations (id integer PRIMARY KEY, seat text NOT NULL, active boolean NOT NULL);
CREATE UNIQUE INDEX one_active_seat ON reservations (seat) WHERE active;
INSERT INTO reservations VALUES (1,'A1',true),(2,'A1',false),(3,'A1',false);
DO $$ BEGIN
 INSERT INTO reservations VALUES (4,'A1',true);
 RAISE EXCEPTION 'two active reservations accepted';
EXCEPTION WHEN unique_violation THEN RAISE NOTICE 'active duplicate rejected';
END $$;
UPDATE reservations SET active=false WHERE id=1;
INSERT INTO reservations VALUES (4,'A1',true);
DO $$ BEGIN
 UPDATE reservations SET active=true WHERE id=2;
 RAISE EXCEPTION 'reactivation bypassed uniqueness';
EXCEPTION WHEN unique_violation THEN RAISE NOTICE 'conflicting reactivation rejected';
END $$;
SELECT active,count(*) FROM reservations GROUP BY active ORDER BY active;
SELECT id FROM reservations WHERE active AND seat='A1';
DO $$ BEGIN
 IF (SELECT id FROM reservations WHERE active AND seat='A1') IS DISTINCT FROM 4 THEN
 RAISE EXCEPTION 'wrong active reservation';
 END IF;
 IF (SELECT count(*) FROM reservations WHERE NOT active) <> 3 THEN
 RAISE EXCEPTION 'history was not preserved';
 END IF;
END $$;
ROLLBACK;

最初的有效重复被拒绝，而两条历史重复成功保留。把一号预订设为无效后，四号预订可以取得该座位；再把二号重新激活则失败，因为四号仍有效。最后应有三条无效记录、一条有效记录，有效标识为四。断言同时检查当前持有人与历史数量，避免只验证拒绝消息而遗漏错误的数据变更。

保留的 PostgreSQL 18.6 单用户 SQL 日志记录了这些检查通过；本轮源文审阅没有重跑。早先的适配省略了 psql 指令并折叠语句空白，因此客户端调用与并发预订仍未经验证。异常块只捕获预期的唯一性违反；如果本应失败的操作意外成功，后面的不同异常会让脚本失败。最后回滚移除夹具。实验验证子集成员资格与唯一性转换，不证明支付原子性、分布式库存一致性，也没有测量巨大历史表上的性能收益。

来源

PostgreSQL 部分索引，谓词成员资格与部分唯一性，已核验 2026-10-15。
PostgreSQL CREATE INDEX，唯一索引检查与谓词，已核验 2026-10-15。

覆盖索引有条件地避免堆访问

Thu, 14 Oct 2027 00:00:00 +0000

覆盖索引包含某一条查询需要的值，PostgreSQL 有时可以通过 index-only scan 直接返回它们，避免访问对应的堆元组。这里的“有时”很关键：列是否齐全属于结构条件，执行时能否真正跳过堆访问，还取决于可见性信息。计划里出现 Index Only Scan，并不能单独证明没有访问表数据，更不能据此宣称任何写入状态下都能省掉堆读取。

覆盖提供查询值；堆页可见性标志决定 index-only 扫描是否仍须访问堆。写入和满足条件的 VACUUM 可以改变状态。堆访问不一定产生物理磁盘读取。

覆盖实际返回的列

按 sku 查价格时，可以建立 sku 的 B-tree，并用 INCLUDE (price) 把价格作为附加值存进去。搜索由 sku 键引导，附加的 price 不会自动成为第二个搜索键，也不提供按价格排序的顺序。如果这是唯一索引，唯一性约束针对键列，而不是键与附加列的整体组合。这些区别决定它究竟能回答哪些查询。

查询后来增加返回列，就可能破坏覆盖前提。例如 description 不在索引中，执行器需要从其他位置取得它，通常就是堆表。随手改成 SELECT 星号，也可能把原本专门优化的查找变成另一种访问模式。应从实际过滤条件和投影列出发，结合表达式与可见性需求设计，而不是把全部字段都塞进一个预想中的万能覆盖索引。

并非所有索引方法都能还原 index-only 执行所需的完整值。B-tree 支持这种扫描，GIN 通常保存的是从原值提取的键，而不是完整原值，因此不支持 index-only scan。索引不仅要包含或能够还原所需数据，也要支持对应操作。其他数据库也使用“覆盖索引”这个名称，但不能据此把 PostgreSQL 的可见性机制直接套过去。

可见性映射决定是否访问堆

PostgreSQL 必须判断候选元组是否对当前 MVCC 快照可见，索引项没有保存全部所需可见性信息。Index-only scan 会检查堆页在 visibility map 中的 all-visible 位；该位已设置时，才能直接返回索引中的值，而不读取堆元组。这样省下的是堆访问，仍然需要读取索引和可见性映射，并不等于完全没有 I/O。

写入可能清除页的 all-visible 状态，导致之后的查询重新访问堆，即使计划名称没有改变。VACUUM 可以在页内元组满足可见性条件时设置该状态，长事务和持续更新都会影响这一过程。它是页级属性，不是某个单独字段的属性；同一页上其他行被修改，也可能影响当前行的可见性检查路径。因此“这一行没改过”也不能直接推出零堆访问。

坏掉的样子

最常见的误判是只看 EXPLAIN 的计划标签就宣布优化成功。应在 EXPLAIN ANALYZE 中同时查看 Heap Fetches、相关缓冲区和实际返回值。频繁写入的表可能不断需要堆检查，读取收益下降，却仍承担附加值的复制与维护成本。每次业务写入后都运行 VACUUM，并不能代替对真实读写比例和维护成本的评估。

宽大的附加列还会占用磁盘和缓存，增加索引维护工作，甚至超过索引元组尺寸限制。更新 INCLUDE 列需要维护索引，也可能阻止原本可行的 heap-only update。应只覆盖读收益足以抵偿写入和存储成本的字段；覆盖索引不是免费物化的整表副本，也不能只用一次静态查询的耗时决定是否值得长期保留。

快速验证

把 SQL 保存为 covering.sql，运行 psql -X -v ON_ERROR_STOP=1 -f covering.sql，连接可丢弃的 PostgreSQL 18 数据库。保持 psql 默认自动提交，不要在外面加 BEGIN，因为 VACUUM 不能在显式事务块中运行。实验表是会话临时表，不会修改其他连接的数据，断言失败退出后临时表也会随会话消失。

\set ON_ERROR_STOP on
CREATE TEMP TABLE products (sku integer, price integer);
INSERT INTO products SELECT g, g*10 FROM generate_series(1,10000) AS g;
CREATE INDEX products_price_lookup ON products (sku) INCLUDE (price);
VACUUM (ANALYZE) products;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT price FROM products WHERE sku=4321;
UPDATE products SET price=price+5 WHERE sku=4321;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT price FROM products WHERE sku=4321;
VACUUM (ANALYZE) products;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT price FROM products WHERE sku=4321;
DO $$ BEGIN
 IF (SELECT price FROM products WHERE sku=4321) IS DISTINCT FROM 43215 THEN
 RAISE EXCEPTION 'covering lookup returned an obsolete price';
 END IF;
END $$;
DROP TABLE products;

第一次 VACUUM 让静止夹具满足无堆读取条件。保留的 PostgreSQL 18.6 执行报告中，三个计划都显示 Index Only Scan，但 Heap Fetches 依次是零、价格更新后的二、再次 VACUUM 后的零。断言同时确认返回的新价格是 43215，而不是旧索引值。实验最后显式删除临时表，避免把清理当成读者需要猜测的步骤。

中间的具体访问次数可以随实现和页状态变化，关键是相同计划标签下仍可能发生堆访问。Heap Fetches 统计堆访问，并不等于物理磁盘读取次数，所需页仍可能已经在缓存中。这个受控实验也不承诺生产中一次 VACUUM 就让所有页立刻 all-visible。真正评估覆盖收益时，应观察代表性查询在实际更新活动前后的表现，同时计算附加数据带来的维护成本，而不是只挑清理刚完成时的最好结果。

来源

PostgreSQL index-only 扫描，可见性映射与附加值，已核验 2026-09-10。
PostgreSQL CREATE INDEX，INCLUDE 语义与索引限制，已核验 2026-09-10。

查询优化器在成本上押注

Fri, 17 Sep 2027 00:00:00 +0000

查询规划器根据预计工作量选择执行路径，并不会先把所有候选方案运行一遍、计时后再保留冠军。PostgreSQL 用统计信息和成本模型比较扫描、连接、排序等操作，因此选定的计划始终是建立在当前假设上的预测。诊断预测为何偏离实际，需要找出失效的具体假设，而不是把顺序扫描或嵌套循环当成天生有问题的节点。计划好不好，要放在完整查询的输入和输出要求中判断。

ANALYZE 收集函数依赖后可纠正一种相关性估计，但仍可能误判不兼容的值组合。应比较预计与实际工作；成本不是毫秒，行数估计改善本身不代表执行变快。

成本描述的是一个模型

PostgreSQL 的成本综合页面访问、元组处理、运算符计算等估计工作量，单位并不是毫秒。只需要拿到少量记录时，启动成本可能特别重要；必须产生完整结果时，总成本的意义更大。一个扫描如果已经提供了后面需要的顺序，就可能省掉排序，因此单独看来最便宜的扫描，不一定是整条查询最合适的输入。只比较一个节点会漏掉它给后续处理带来的影响。

规划搜索也有边界。数据库会考虑不同路径和连接顺序，而不是实际执行全部候选。连接关系很多时，PostgreSQL 可以启用遗传查询优化器来控制规划开销。可用索引、合法变换、配置与搜索选择共同限制了候选集合，所以不能把最后的选择描述为“对所有想象得到的实现都保证数学最优”。这种边界并不表示规划器不可信，只是说明它需要接受真实测量的检验。

坏掉的样子

统计刚刷新也可能估错。普通统计分别描述每一列，在组合两个过滤条件时可能假设它们相互独立，而实际两列总是一起变化。中间结果被低估后，反复查找看起来就比实际便宜，后续连接顺序也可能受到影响。如果模型本身没有表达这两列的关系，重复运行相同的分析不会凭空补上这部分知识。统计陈旧与统计种类不足，不能混成一种诊断。

扩展统计也只解决特定问题。函数依赖可以帮助估计与常量比较且彼此兼容的等值条件，但它不保存具体值之间的完整对应关系，也不是范围条件或任意跨列比较的一般证明。即使已经收集到很强的依赖，一组实际上互不兼容的常量仍可能被严重高估。因此验证中既需要兼容的正向情况，也需要一个不成立的组合来展示限制。

快速验证

在 PostgreSQL 18 的 psql 中执行下面的临时表实验。两列始终保存相同的值，一共有一百种不同值，每种重复一百次。所有修改都放在事务中，最后回滚会一并移除表和相应统计对象。

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE dimensions (a integer,b integer);
INSERT INTO dimensions SELECT g%100,g%100 FROM generate_series(1,10000) AS g;
ANALYZE dimensions;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF) SELECT * FROM dimensions WHERE a=7 AND b=7;
CREATE STATISTICS pg_temp.dimensions_dependency (dependencies) ON a,b FROM dimensions;
ANALYZE dimensions;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF) SELECT * FROM dimensions WHERE a=7 AND b=7;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF) SELECT * FROM dimensions WHERE a=7 AND b=8;
DO $$ BEGIN
 IF (SELECT count(*) FROM dimensions WHERE a=7 AND b=7) <> 100 OR
 (SELECT count(*) FROM dimensions WHERE a=7 AND b=8) <> 0 THEN RAISE EXCEPTION 'wrong correlated population'; END IF;
END $$;
ROLLBACK;

保留的 PostgreSQL 18.6 执行报告中，在建立扩展统计之前，对 a=7 AND b=7 估计一行，实际返回一百行。两个条件单独都选中百分之一的数据；把选择率相乘，就得到一万行中的万分之一，也就是一行。这套算术在条件独立时有意义，而夹具故意让两列完全相关，所以假设与数据并不相符。

创建函数依赖对象，告诉下一次 ANALYZE 要收集哪组列之间的关系。第二份计划估计一百行，实际也返回一百行。仅仅创建统计对象还没有填入所需信息，后续分析这一步不能省略。扫描仍然是顺序扫描，因为本例没有任何索引，仍要检查这张小表的全部内容。这里证明的是行数预测改善，不能由此声称应用已经变快，更不能把节点没有变化当成实验失败。

最后一个条件改成 a=7 AND b=8。查询实际返回零行，但函数依赖给出的估计仍是一百行。这个负向案例说明：知道一列决定另一列，并不等于这种统计知道“七只能对应七”这一条具体映射。末尾断言分别核对兼容与不兼容条件的正确结果。估计失真影响规划选择，却不会把本来不符合条件的记录变成合法查询结果。

根据偏差选择下一次实验

如果缺少的是常见值组合的信息，多列常见值列表能够表达这些组合。其他负载可能需要不同类型的统计、恰当的索引，或者让可索引条件更清晰的表达式改写。应当根据真实过滤条件增加对象，而不是为所有列组合都预先配置扩展统计；收集和使用不必要的统计也会消耗分析与规划资源。

比较替代方案时，固定数据集、参数、相关设置和结果要求，同时观察处理行数、缓冲区访问、内存溢写与实际延迟。局部节点便宜，却把更多工作推给上层，不能算整个查询改善。反过来，即使估计行数准确，也没有排除等待、昂贵读写或成本模型不适合当前环境的可能。应沿预计工作与实际工作之间的具体差异继续验证，再决定是否调整全局规划参数。

来源

PostgreSQL 18：规划器与优化器，候选访问路径与连接策略，已核验 2026-09-10。
PostgreSQL 18：规划器统计，列分布与扩展统计的限制，已核验 2026-09-10。
PostgreSQL 18：多变量统计示例，相关条件与函数依赖估算，已核验 2026-09-10。

小表上全表扫描可能更快

Thu, 16 Sep 2027 00:00:00 +0000

索引用存储和写入成本，换取减少读取工作的机会。表很小，或者谓词选中大部分数据时，全表扫描可能更快，但行数与选择性都不能单独决定胜负。查询需要哪些列、排序要求、缓存状态、行宽和可用访问路径，都会改变比较结果。首先明确实际查询必须返回什么，再判断哪种访问方法做了更多有用工作。

看清两条路径实际做什么

B 树范围扫描并不是每匹配一个索引条目，都重新从根节点下降。定位范围起点后，可以沿相邻条目继续前进。非覆盖索引还可能需要回表取得缺少的列；宽谓词下，这部分工作可能成为主要成本。覆盖索引能够省去这些读取，因此，即使查询命中多数行，索引也仍有可能更划算，不能把宽谓词与索引无用直接画等号。

页很重要，但不是唯一成本。PostgreSQL 默认的 seq_page_cost 与 random_page_cost 是优化器使用的相对估计，不是毫秒，也不是每返回一行就机械收取一次的费用。缓存、数据相关性、CPU 工作、位图扫描与仅索引扫描，都影响计划选择。SQLite 普通表把行放在按 rowid 组织的 B 树中，与 PostgreSQL 堆表存储不同，不能直接把一种引擎测得的性能比例套到另一种引擎。

SQLite 的 PRAGMA page_count 返回整个数据库文件的页数，包括索引和其他对象，不能当作某个指定表的独立页数。逻辑页遍历也不保证磁盘上的连续物理读取。比较时应保持统计对象范围一致，记录页大小、模式、负载宽度和缓存条件，不能只报告行数，再把其他成本差异全部归因于扫描或索引。

保留历史测量的适用范围

此前笔记记录了 SQLite 3.53、二兆字节页缓存下的结果。宽谓词的扫描与索引时间，在一千行时为 0.04 与 0.05 毫秒，在五万行时为 1.79 与 6.61 毫秒，在百万行时为 44.37 与 531.18 毫秒。同一百万行表的高选择性查询，索引为 0.61 毫秒，扫描为 17.88 毫秒。相同行数的窄、宽负载样本还分别记录了十二与一千零十页，以及 0.02 与 1.30 毫秒。

这些是历史观察，不是通用阈值，也不是本轮重新取得的测量。此次审阅没有此前的数据生成器及完整基准环境，因此下面提供独立、可复现的比较，并输出实际运行时版本。它不声称重现历史时间、页数或自动优化器选择。记录旧观察与建立新实验可以同时进行，但不能把新实验的成功当作旧数字已经复核。

坏掉的样子

某个租户持续增长，可能让旧选择性估计失效，而所有查询仍然返回正确结果。统计信息只是一个调查方向，不是原因已经确定：参数变化、覆盖关系、缓存状态或竞争负载，也可能让同一计划变慢。强制长期使用某条路径之前，应比较估计工作量与实际工作量，确认问题出在哪里，再决定是否需要改索引、查询或维护策略。

新统计也不保证所有宽范围谓词都选择扫描。SQLite 构建时可能启用不同的可选统计支持，计划文本也可能随版本改变。SCAN 甚至可能表示覆盖索引扫描，而不一定是表扫描。要阅读完整计划，并比较等价查询的结果，不能把某一个关键词变成正确性判据，更不能因为计划没有按预想翻转，就宣布数据库违反了契约。

tenant 索引缺少 payload，因此范围路径需要回表。实验三条路径必须返回相等结果，不预定胜者。历史耗时未复测。

快速验证

保存为 scans.py 后执行 python3 scans.py。脚本使用 Python 自带的 SQLite 绑定，在自己创建的临时目录建立数据库，不会打开现有应用数据。三种路径对宽谓词都必须返回二百八十八万，对高选择性谓词都必须返回三千二百。七轮交替顺序的热缓存样本报告中位数，但不会断言哪条路径一定更快，避免把环境相关时序当成功能要求。

from pathlib import Path
from tempfile import TemporaryDirectory
from statistics import median
from time import perf_counter
import sqlite3

with TemporaryDirectory(prefix="scan-crossover-") as directory:
 db = sqlite3.connect(Path(directory) / "fixture.db")
 try:
 db.executescript("""CREATE TABLE events(id INTEGER PRIMARY KEY, tenant INTEGER, payload TEXT);
 CREATE INDEX events_tenant ON events(tenant);""")
 db.executemany("INSERT INTO events VALUES(?,?,?)",
 ((i, i % 1000, "x" * 64) for i in range(50000)))
 db.commit()
 db.execute("ANALYZE")
 print("SQLite", sqlite3.sqlite_version)
 print("database pages", db.execute("PRAGMA page_count").fetchone()[0],
 "page size", db.execute("PRAGMA page_size").fetchone()[0])
 for predicate, expected in [("tenant < 900", 2880000), ("tenant = 7", 3200)]:
 base = "SELECT sum(length(payload)) FROM events {} WHERE " + predicate
 paths = {"chosen": "", "scan": "NOT INDEXED", "index": "INDEXED BY events_tenant"}
 queries = {name: base.format(clause) for name, clause in paths.items()}
 samples = {name: [] for name in queries}
 for name, query in queries.items():
 assert db.execute(query).fetchone()[0] == expected
 print(predicate, name, db.execute("EXPLAIN QUERY PLAN " + query).fetchall())
 for repeat in range(7):
 names = list(queries) if repeat % 2 == 0 else list(reversed(queries))
 for name in names:
 start = perf_counter()
 result = db.execute(queries[name]).fetchone()[0]
 samples[name].append((perf_counter() - start) * 1000)
 assert result == expected
 print("warm median ms", {k: round(median(v), 3) for k, v in samples.items()})
 old = db.execute("SELECT stat FROM sqlite_stat1 WHERE idx='events_tenant'").fetchone()[0]
 db.execute("UPDATE events SET tenant=5")
 db.commit()
 stale = db.execute("SELECT stat FROM sqlite_stat1 WHERE idx='events_tenant'").fetchone()[0]
 assert stale == old
 db.execute("ANALYZE")
 fresh = db.execute("SELECT stat FROM sqlite_stat1 WHERE idx='events_tenant'").fetchone()[0]
 assert fresh.split()[:2] == ["50000", "50000"] and fresh != old
 print("statistics before/stale/fresh", old, stale, fresh)
 try:
 db.execute("SELECT * FROM events INDEXED BY absent_index")
 except sqlite3.OperationalError as error:
 assert "no such index" in str(error), error
 else:
 raise AssertionError("missing required index was silently ignored")
 print("missing INDEXED BY target rejected")
 finally:
 db.close()

负载表达式需要 tenant 索引中没有的数据，因此这里比较的是非覆盖路径。INDEXED BY 要求使用指定索引，并非温和建议；缺少索引的负向对照会明确失败。此处 NOT INDEXED 禁用次级索引，但在别的查询中并不禁止 rowid 查找。这些控制用于诊断，不应未经理由就复制到生产查询中，以免将某次测量得到的选择永久固定。

数据被改成同一个租户以后，sqlite_stat1 在 ANALYZE 之前保持旧值，更新后记录五万行共享同一个键。这个断言验证统计维护，而不是保证计划一定翻转。生产中应遵循当前 SQLite 版本建议的 PRAGMA optimize 流程，并为较昂贵的分析选择合适时机，避免把一次性实验里的维护命令不加判断地放进每个请求。

实验预热数据，只测一个进程，没有竞争写者，因此不能建立冷存储延迟、生产并发或长期索引成本结论。性能测试应保留代表性分布和实际投影，并随表增长重复检查。今天可以接受的扫描，可能在没有任何正确性错误的情况下变贵；要追踪的是业务所需结果的成本，而不只是某个计划名字是否保持不变。

来源

SQLite 查询规划，范围遍历、回表和覆盖索引，已核验 2026-10-15。
SQLite EXPLAIN QUERY PLAN，SCAN/SEARCH 含义和不稳定的展示格式，已核验 2026-10-15。
SQLite PRAGMA page_count，数据库整体页数，已核验 2026-10-15。
SQLite ANALYZE，统计信息与建议的 optimize 流程，已核验 2026-10-15。
SQLite INDEXED BY，索引要求与 NOT INDEXED 范围，已核验 2026-10-15。
PostgreSQL 优化器代价常量，相对成本与缓存假设，已核验 2026-10-15。
PostgreSQL 使用 EXPLAIN，行数估计、位图扫描与仅索引扫描，已核验 2026-10-15。

组合索引贴合多列的查询

Wed, 15 Sep 2027 00:00:00 +0000

复合 B-tree 索引先按第一个键排序，再在第一个键相同的组内按下一个键排序。这种元组顺序可以让“某个租户的一段时间”很容易定位。应理解的是条件能缩小多少索引扫描范围，而不是禁止查询后面的列，也不是要求 WHERE 中的条件必须按建索引的顺序书写。这几个概念混在一起，会导致错误的索引设计。

租户优先键顺序的局部片段，以及一种可能的后列搜索策略。重复搜索是否划算取决于成本；本图不是计划跟踪，最终输出顺序仍取决于实际路径。

排序的是键，不是 SQL 条件

对于 (tenant, happened) 索引，tenant 等值条件加 happened 范围条件描述了树中的一小段。PostgreSQL 可以定位这一段，而不用检查所有租户。即使把时间条件写在 WHERE 的前面、租户条件写在后面，逻辑上的合取关系也没有改变。数据库定义中的键顺序与查询文本的书写顺序，是两件不同的事情，不能拿文本位置判断索引是否可用。

通常，前导列的等值条件和第一个非等值键上的范围条件，决定必须扫描的区间。更后面的键条件仍可在索引中检查，即使不能继续缩小一个简单连续区间，也可能减少访问堆表的次数。调换索引键会改变这些机会，但不意味着某种排列在所有查询中都完全无用。需要结合查询实际要求的范围和返回列判断。

后面的键仍可能有用

PostgreSQL 18 在合适时可以使用 B-tree skip scan：如果遍历缺少等值条件的前导键取值，并在每组内重新搜索，比读取大部分索引更便宜，就可能采用这种路径。只有少数几个租户时，仅过滤 happened 也可能通过各租户分组完成查找；前导键不同值很多时，这种重复搜索可能太贵，规划器便可能选择顺序扫描或其他索引。

即使没有合算的 skip scan，某些只涉及后面键的条件仍可能扫描复合索引。问题是成本、覆盖范围与选择性，不是 SQL 是否合法，也不是索引必然被忽略。不能把“最左前缀”这种便于记忆的说法扩展成绝对禁令，尤其在目标数据库明确支持其他访问路径时。版本和真实计划必须优先于口号。

把排序和工作负载一起考虑

固定 tenant 后，后面的 happened 顺序可以支持该租户的时间排序。但跨多个租户时，索引先按租户分组，不会直接提供全局时间顺序。Bitmap 扫描也不保留索引顺序，仍可能需要单独排序。因此应看完整计划，而不是看到索引包含排序列就断言不会发生 Sort。LIMIT 对尽快返回前几行的需求也会改变最合适的路径。

“等值列在前、范围列在后”是一个查询形状的起点，并不是“永远把选择性最高的列放第一”的统一算法。多个查询共享的前缀、连接、排序方向、参数分布和写入成本都会影响选择。比较真正反复出现的查询，再保留必要的最小索引集合。重复且宽大的索引即使没有读者，也会占用缓存和写入维护资源。

坏掉的样子

团队可能为租户内查询建立 (tenant, happened)，随后增加全局时间线，却假定两者效率相同。新查询的顺序要求和过滤范围已经不同，需要重新评估。另一种回归来自测试参数：一个小租户的计划很好，不代表拥有大部分行的租户也同样便宜。同一条参数化 SQL 面对不同数据分布，成本可能差很多，统计信息和代表性参数比单次截图更可靠。

错误规则也会带来不必要的索引变更。因为“原索引绝不可能查后列”而为每个后缀新增索引，可能重复已有能力；反过来，相信 skip scan 总能补救缺失前缀，又可能掩盖昂贵路径。修改数据库结构前，应检查实际行数、缓冲区、排序与访问方式，说明哪个真实查询获得了什么改善。

快速验证

把代码保存为 composite.sql，用 psql -X -v ON_ERROR_STOP=1 -f composite.sql 连接可丢弃的 PostgreSQL 18 数据库。临时夹具包含四个租户取值和两万个事件编号，最后回滚删除全部实验对象，不依赖已有表或数据。

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE events (tenant integer, happened integer, body text);
INSERT INTO events SELECT g % 4, g, repeat('x',40) FROM generate_series(1,20000) AS g;
CREATE INDEX events_tenant_time ON events (tenant, happened);
ANALYZE events;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT happened FROM events WHERE tenant=2 AND happened BETWEEN 100 AND 120
ORDER BY happened;
SELECT array_agg(happened ORDER BY happened) AS matching_times
FROM events WHERE happened BETWEEN 100 AND 120 AND tenant=2;
EXPLAIN (ANALYZE, BUFFERS, TIMING OFF)
SELECT tenant FROM events WHERE happened=12346;
DO $$ BEGIN
 IF (SELECT array_agg(happened ORDER BY happened) FROM events
 WHERE happened BETWEEN 100 AND 120 AND tenant=2)
 IS DISTINCT FROM ARRAY[102,106,110,114,118] THEN
 RAISE EXCEPTION 'wrong composite range';
 END IF;
 IF (SELECT tenant FROM events WHERE happened=12346) IS DISTINCT FROM 2 THEN
 RAISE EXCEPTION 'suffix predicate lost the row';
 END IF;
END $$;
ROLLBACK;

租户范围查询精确返回 102,106,110,114,118，把 WHERE 条件反过来书写时结果相同。保留的 PostgreSQL 18.6 执行报告中，它使用 bitmap index scan 后再排序；仅按后列查询的语句通过带重复索引搜索的 index-only scan 返回租户二，直接证明没有 tenant 等值条件也存在可用路径。两种计划不同，但都符合各自的逻辑结果。

具体计划名称、缓冲区计数和搜索次数是这份数据上的观测，不是任何配置下都必须出现的常量。断言验证结果语义，性能判断还应增加前导键的不同取值数量，测量后列访问在真实分布下是否仍值得使用。这样才能把“索引可以参与”与“该索引在这个负载下划算”分开。

来源

PostgreSQL 多列索引，前导条件和 skip scan，已核验 2026-09-10。
PostgreSQL 索引与 ORDER BY，有序扫描与排序选择，已核验 2026-09-10。

只读副本服务查询需求

Mon, 12 Jul 2027 00:00:00 +0000

只读副本允许一份数据库服务查询，另一份数据库处理写入。报表、搜索或其他适合的读取，可以由此离开写入节点，但把连接路由到某个地址只是设计的一部分。应用还必须说明返回结果需要包含哪些已经提交的变更。本文采用 PostgreSQL 物理热备库，它在正常恢复模式下可以读取，但不能接受普通业务写入。

坏掉的样子

异步复制下，成功写入之后立刻查询副本，仍然可能读到旧值。用户刚修改账户并刷新页面，之前的内容却又出现了。此时副本可能连接健康、日志接收持续推进，只是相关提交还没有被重放。如果新鲜度检查只看接收位置、不看回放位置，就检查了错误的完成边界。

即使回放已经推进，旧事务快照仍然可能影响结果。可重复读事务本来就需要在恢复继续进行时保留自己的视图。等待副本应用某次写入，不会顺便刷新这个事务。因此，要实现写后读到本次修改，既需要足够的回放进度，也需要查询使用在这个进度条件满足之后取得的新快照，两个条件缺一不可。

新鲜度承诺也需要限定范围。包含这个用户较早的一次写入，不等于保证其他地方不存在更新的事务。若读取余额是为了批准下一笔扣款，仍然必须在写入路径中进行事务性核对。副本提供的查询容量，不能替代保护业务动作的并发控制，也不能使一个只读结果天然变成后续写入的有效授权。

回放覆盖不会刷新已有快照。100 与 80 是待运行验证的 PostgreSQL 夹具值，不是容量基准。

快速验证

在 Linux 环境中以非超级操作系统账户运行脚本，并准备 PostgreSQL 18 服务端和客户端程序。原文报告使用 PostgreSQL 18.6；本轮源文审阅未重跑夹具。脚本建立私有主备集群，通过 Unix 套接字连接，不打开 TCP 监听。Unix 套接字仍是监听端点，需要执行环境允许。一个命名管道保持读会话存活，让实验能够明确控制事务快照边界，无需额外安装数据库驱动。

#!/bin/sh
set -eu
umask 077
lab=$(mktemp -d /tmp/xbcatm-read-replica.XXXXXX)
mkdir "$lab/socket"
primary=$lab/primary
standby=$lab/standby
reader_pid=''
reader_open=0
cleanup() {
 if test "$reader_open" = 1; then exec 3>&-; fi
 if test -n "$reader_pid"; then wait "$reader_pid" || :; fi
 for cluster in "$standby" "$primary"; do
 if test -f "$cluster/postmaster.pid"; then
 pg_ctl -D "$cluster" -m fast -w stop >/dev/null
 fi
 done
}
trap cleanup EXIT
initdb -D "$primary" --no-locale --encoding=UTF8 --auth-local=trust --auth-host=reject >/dev/null
cat >> "$primary/postgresql.conf" <<CONF
listen_addresses = ''
unix_socket_directories = '$lab/socket'
port = 56432
wal_level = replica
wal_keep_size = '64MB'
CONF
pg_ctl -D "$primary" -l "$lab/primary.log" -w -t 15 start >/dev/null
export PGHOST=$lab/socket PGPORT=56432 PGDATABASE=postgres PGUSER=$(id -un)
export PGCONNECT_TIMEOUT=2
psql -X -v ON_ERROR_STOP=1 -qAt <<'SQL'
CREATE TABLE account (id integer PRIMARY KEY,balance integer);
INSERT INTO account VALUES (1,100);
SQL
pg_basebackup -D "$standby" -R -X stream -c fast -w
cat >> "$standby/postgresql.conf" <<CONF
port = 56433
hot_standby = on
CONF
pg_ctl -D "$standby" -l "$lab/standby.log" -w -t 15 start >/dev/null
mkfifo "$lab/reader.sql"
PGPORT=56433 PGAPPNAME=replica_snapshot psql -X -v ON_ERROR_STOP=1 -qAt <"$lab/reader.sql" >"$lab/reader.log" 2>&1 &
reader_pid=$!
exec 3>"$lab/reader.sql"
reader_open=1
printf '%s\n' 'BEGIN ISOLATION LEVEL REPEATABLE READ;' 'SELECT balance FROM account WHERE id=1;' >&3
attempt=0
while test "$(PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt -c "SELECT EXISTS (SELECT FROM pg_stat_activity WHERE application_name='replica_snapshot' AND state='idle in transaction' AND backend_xmin IS NOT NULL)")" != t; do
 attempt=$((attempt+1))
 test "$attempt" -lt 100 || exit 1
 sleep 0.1
done
PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT pg_wal_replay_pause()' >/dev/null
attempt=0
while test "$(PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt -c "SELECT pg_get_wal_replay_pause_state()='paused'")" != t; do
 attempt=$((attempt+1))
 test "$attempt" -lt 100 || exit 1
 sleep 0.1
done
psql -X -v ON_ERROR_STOP=1 -qAt -c 'UPDATE account SET balance=80 WHERE id=1'
target=$(psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT pg_current_wal_lsn()')
printf 'primary_balance '
psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT balance FROM account WHERE id=1'
printf 'paused_replica_balance '
PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT balance FROM account WHERE id=1'
for attempt in 1 2 3 4 5; do
 test "$(PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt -c "SELECT pg_last_wal_replay_lsn()>='$target'::pg_lsn")" = f
 sleep 0.1
done
echo fresh_read_gate_timed_out
PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT pg_wal_replay_resume()' >/dev/null
attempt=0
while test "$(PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt -c "SELECT pg_last_wal_replay_lsn()>='$target'::pg_lsn")" != t; do
 attempt=$((attempt+1))
 test "$attempt" -lt 150 || exit 1
 sleep 0.1
done
test "$(PGPORT=56433 psql -X -v ON_ERROR_STOP=1 -qAt -c 'SELECT balance FROM account WHERE id=1')" = 80
echo fresh_snapshot_after_replay_80
printf '%s\n' 'SELECT balance FROM account WHERE id=1;' 'COMMIT;' >&3
exec 3>&-
reader_open=0
wait "$reader_pid"
reader_pid=''
test "$(cat "$lab/reader.log")" = "$(printf '100\n100')"
echo old_repeatable_read_snapshot_still_100
printf 'lab_directory %s\n' "$lab"

初始余额是一百。备库上的可重复读事务先执行一次查询，再保持打开。脚本核对这个后端确实处于事务内空闲状态并持有快照，随后请求暂停日志回放，并等待实际暂停。主库把余额提交为八十，捕获提交之后的日志位置，作为这次读取需要达到的进度目标。

预期输出分别显示主库余额八十、暂停副本余额一百。五次回放检查之间进行短暂等待，结果都为假，于是输出新鲜读取门槛等待失败的标记。这表示必要变更尚未应用，不能确认读取足够新。实验不会悄悄接受旧结果，也不把这些轮询间隔解释成精确的端到端延迟保证，因为每次连接与查询本身同样需要时间。

回放恢复之后，脚本等待其位置达到目标，然后新建的备库查询必须读到八十。原有可重复读会话此时再次查询，却仍然看到一百。保存的会话输出必须连续包含两次一百，证明旧快照在回放进度变化之后仍然有效。因此，“服务端已经追上”和“这个事务仍然读取旧数据”可以同时成立，不能把它们误诊成相互矛盾的统计。

脚本提交保留的读事务，关闭管道，停止两个实验服务，并打印日志目录。断言检查真实数据库值和实际回放状态，不依赖应用缓存推测。这次演练不会修改任何生产路由或连接池；其完成条件是把不同读取边界分别观察清楚，而不是宣称已经完成业务系统的副本路由改造。

明确路由所承诺的结果

进度标识必须属于目标副本所在的同一条数据库历史。日志位置不是在无关集群或已经分叉的时间线之间全局唯一的业务版本。生产环境中的进度门槛需要绑定相关拓扑，并明确处理故障切换。这个夹具使用固定主库及其直接副本，所以身份关系由建立实验的过程保证，不能把这一前提从生产方案里省略。

如果请求预算内无法确认新鲜度，应明确返回应用能够解释的状态，或在已授权且容量允许时从写入节点读取。不能因为达到截止时间，就暗中降低结果含义。门槛满足后再取得新快照，并保持事务足够短，避免旧快照长期保留使后续进度检查失去意义。业务需要的是确定的读取契约，而不只是尽量快地返回一个数字。

备库上的长查询还可能与恢复工作冲突。PostgreSQL 可以取消它们以推进回放；反馈设置则会在减少取消与增加主库旧版本保留之间交换代价。应联合观察回放延迟、查询取消与事务年龄。评估副本收益时，也要测量真正从写入节点移走了多少读取工作，并把复制开销及维护副本的运行成本一起纳入判断。

来源

PostgreSQL 18 热备，只读恢复、事务快照与恢复冲突，已核验 2026-09-12。
PostgreSQL 18 管理函数，回放位置及暂停、继续语义，已核验 2026-09-10。
PostgreSQL 18 复制配置，备库延迟与反馈的代价交换，已核验 2026-09-12。

顺序标识会透露分配规律

Sat, 29 May 2027 00:00:00 +0000

顺序标识让相邻的值很容易被猜到。看到第四千号订单，观察者就知道可以从附近的编号继续探测；持续收集编号，也可能看出分配活动的大致变化。但这不代表系统恰好有四千张订单，不代表每个编号都对应成功购买，也不代表最大编号最后提交。想得出这些结论，还需要序列本身没有记录的业务事实。

坏掉的样子

PostgreSQL 序列取值不会跟随普通事务回滚而退回。一次最终放弃的插入，也可能永久消耗一个号码。删除记录、缓存预留区间、显式修改序列以及多个并发写者，都会进一步拉开计数器与当前行数的距离。因此，用最大编号充当客户数或销售数量，即使没有攻击者参与，也会生成错误的经营报表。号码可以提供线索，却不能直接当作精确统计结果。

分配顺序同样不等于提交顺序。事务甲可能先取得较小编号，随后停在那里；事务乙取得较大编号后，反而先完成提交。如果消费者把递增主键当作完整的已提交事件流，就可能先处理较大的行并推进位置，而较小的行此时还不可见。等它后来提交，消费者已经越过了它。数字主键不能直接替代变更捕获位置，也不能证明所有业务事件的先后关系。

随机标识让逐个递增枚举变得困难，却不会自动实施访问控制。UUID 仍可能出现在日志、分享链接或其他接口返回值里，拿到它的人仍须通过对象权限检查。第四版 UUID 使用随机位；第七版在开头放置毫秒时间戳，目标之一是支持时间排序，因此不能把它的前缀说成随机位，也不能把其中的时间当作数据库提交时间。降低可猜测性与确认谁有权读取，是两项不同职责。

分配、提交顺序、行数与授权是不同事实。所属策略改变访问结果时 UUID 没有变化。仅依据原文实验，本次未重跑。

快速验证

准备一个可丢弃的 PostgreSQL 18 数据库，打开两个管理员 psql 会话，分别称为甲和乙。这里要求第十八版，是因为使用了 uuidv7() 以及第七版 UUID 的时间提取；信息提取函数本身在第十七版已经存在。确认实验模式名和两个角色名尚未使用，初始保持自动提交，隔离级别采用通常的读已提交。先在乙中建立数据：

CREATE SCHEMA article_ids;
CREATE ROLE article_id_alice NOLOGIN;
CREATE ROLE article_id_bob NOLOGIN;
SET search_path=article_ids,public;
CREATE TABLE objects (
 id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
 public_id uuid NOT NULL DEFAULT gen_random_uuid() UNIQUE,
 owner text NOT NULL,
 label text NOT NULL
);

在甲中取出第一个编号，但暂时不要提交：

SET search_path=article_ids,public;
BEGIN;
INSERT INTO objects (owner,label) VALUES ('article_id_alice','allocated first') RETURNING id;

然后在乙中插入第二行并观察当前可见数据：

INSERT INTO objects (owner,label) VALUES ('article_id_bob','committed first') RETURNING id;
SELECT array_agg(id ORDER BY id) FROM objects;

乙返回编号二，此时只能看到 {2}。甲明明已经取得编号一，但那一行尚未提交，乙不能读取。这直接区分了“先拿到号码”与“先成为其他事务可见的数据”。现在回到甲完成提交：

COMMIT;

接着在乙中制造一个回滚缺口，并检查两种 UUID：

SELECT array_agg(id ORDER BY id) FROM objects;
BEGIN;
INSERT INTO objects (owner,label) VALUES ('article_id_alice','rolled back') RETURNING id;
ROLLBACK;
INSERT INTO objects (owner,label) VALUES ('article_id_alice','after gap') RETURNING id;
SELECT max(id),count(*) FROM objects;
SELECT bool_and(uuid_extract_version(public_id)=4) FROM objects;
WITH sample AS MATERIALIZED (SELECT uuidv7() AS value)
SELECT uuid_extract_version(value),uuid_extract_timestamp(value) IS NOT NULL FROM sample;

结果依次包含 {1,2}、随后放弃的编号三、新插入的编号四，以及 4|3。最后一项说明最大编号是四，真实行数却只有三。UUID 检查确认表中默认值属于第四版，第七版示例返回 7|t，说明版本为七且可以提取时间戳。每次生成的具体 UUID 都会变化，不应把某次随机值写成固定预期，也不应从这个小样本推导碰撞概率。

仍在乙中，把鲍勃的公开 UUID 保存为客户端变量。在尚未设置行策略时，切换成爱丽丝进行查询：

SELECT public_id AS bob_id FROM objects WHERE owner='article_id_bob' \gset
GRANT USAGE ON SCHEMA article_ids TO article_id_alice,article_id_bob;
GRANT SELECT ON objects TO article_id_alice,article_id_bob;
SET ROLE article_id_alice;
SELECT count(*) FROM objects WHERE public_id=:'bob_id'::uuid;
RESET ROLE;

爱丽丝得到一条记录，说明知道随机编号后，普通表级读取权限依然允许她访问别人的对象。接着启用按所属角色过滤的策略，再运行相同查找：

ALTER TABLE objects ENABLE ROW LEVEL SECURITY;
CREATE POLICY owner_only ON objects FOR SELECT USING (owner=current_user);
SET ROLE article_id_alice;
SELECT count(*) FROM objects WHERE public_id=:'bob_id'::uuid;
SELECT array_agg(id ORDER BY id) FROM objects;
RESET ROLE;
SET ROLE article_id_bob;
SELECT count(*) FROM objects WHERE public_id=:'bob_id'::uuid;
RESET ROLE;

现在爱丽丝按鲍勃的 UUID 查询得到零条，查看自己的数据只能看到编号一和四；鲍勃查询同一编号则得到一条。结果变化来自真实执行的权限策略，不是因为我们重新生成了 UUID。实验角色既不是表所有者，也不是超级用户；具有绕过行策略权限的角色不适合作为这项检查的观察者。确认甲已提交后，在乙中清理本次创建的对象：

DROP SCHEMA article_ids CASCADE;
DROP ROLE article_id_alice;
DROP ROLE article_id_bob;

分开选择标识与权限方案

内部使用序列、公开使用随机标识，可以同时保留内部连接的便利与较难猜测的 URL，但也会多出唯一索引以及两套编号的维护成本。是否值得，应由具体枚举压力和信息披露要求决定。按时间排列的 UUID 在部分工作负载下有利于插入局部性，同时会暴露时间信息；不能仅凭格式就承诺所有数据库、所有索引都变快。

无论接口接受哪种编号，都应结合已认证的主体与目标对象检查权限，其他查找入口也要遵循同样规则。本实验为了看清效果，把用户对应到数据库角色；实际应用必须建立可信身份上下文，不能直接相信请求者提交的所属用户名。统计数量应查询正确的业务口径；要求跨并发提交不丢事件时，应采用有明确完整性契约的事件位置或复制位置，而不是把主键增长误当作提交日志。

来源

PostgreSQL 18 CREATE SEQUENCE，序列缺口与分配语义，已核验 2026-09-10。
RFC 9562，第四版随机位和第七版时间戳布局，已核验 2026-09-12。
PostgreSQL 18 UUID 函数，实验使用的生成与信息提取函数，已核验 2026-09-12。
PostgreSQL 18 行安全，所属策略与特权角色绕过规则，已核验 2026-09-12。
PostgreSQL 17 UUID 函数，已有提取函数及第七版 UUID 的版本边界，已核验 2026-10-15。

外键让引用保持诚实

Tue, 25 May 2027 00:00:00 +0000

外键让关系在普通数据库写入中得到强制校验。任务可以引用已有项目，即使导入脚本或新应用路径忘了提前检查，数据库也能拒绝不存在的项目标识。这条约束定义的是引用完整性，并不决定某个业务操作选中的项目是否正确。明确这个范围，才能既利用数据库保证，也不把业务判断错误地交给外键。

把关系写准确

引用键指向父表中适用的唯一列，通常是主键。多条子记录可以引用同一父行，因此，只有外键并不代表一对一关系，也不要求每个父行必须拥有子记录。如果业务还需要唯一性或其他规则，应单独声明，不能从“存在引用”推导出实际上没有约束的基数关系。

是否允许空值，是另一项决定。单列外键通常允许 SQL NULL，表示没有引用；每个子记录都必须有父记录时，应另外声明 NOT NULL。对于复合键，PostgreSQL 默认的 MATCH SIMPLE 在任意引用列为空时，就允许该行不执行匹配；MATCH FULL 则要求全部为空或全部匹配。因此，只填写一部分的复合引用，在默认模式下不一定无效。

键的作用域也必须准确。如果标识只在某个租户内部唯一，就应引用适当的“租户与标识”组合键，不能默认其他租户里存在相同编号就算正确。即使引用范围定义正确，外键仍不是授权检查：某个项目确实存在，也可能不属于当前用户或当前工作流应操作的对象。

父行删除需要生命周期规则

NO ACTION 是 PostgreSQL 默认的删除动作。在通常的立即检查模式下，删除仍被引用的父行会失败，除非语句结束时约束依然满足。如果约束声明为可延迟，NO ACTION 可以推迟检查；RESTRICT 则不允许延迟这项删除限制。两者不能在任何场景下都当成同义词，迁移或批量操作尤其需要检查其差别。

CASCADE 会在父行删除时自动删除引用它的子行，适合没有独立生命周期的组成部分，但删除范围可能沿多层关系扩张。SET NULL 保留子行并清空引用，前提是空值及其他约束允许这样做。SET DEFAULT 也必须留下有效引用，不能因为设置了默认值就绕开完整性规则。

ON UPDATE 则单独规定被引用键变化时的动作。更新级联会把新键复制到引用行，并不代表覆盖子记录其他无关字段。应根据所有权与保留要求选择动作。为了让报错消失，就把限制删除改为级联，可能把本来有价值的完整性失败变成意外数据删除；约束动作不是单纯的语法偏好。

坏掉的样子

应用先查父行是否存在，仍可能与另一个事务删除父行发生竞态。数据库约束会协调真正写入，因此，应把它作为关系的权威校验，而不是只依赖更早的读取。高权限操作禁用执行，或迁移尚未验证旧数据，是不同状态，不能默认它们拥有已经完整启用并验证的外键保证。

写入成本也取决于负载。删除父行可能需要查找大量子行、获取锁并执行级联。被引用键必须已经具有适用的主键、唯一约束或合适的唯一索引；添加外键不会自动给子表引用列建立索引。需要检查这些访问路径和删除关系图的规模。关系有声明，也不保证优化器一定消除关联，更不代表所有 JOIN 都变成低成本操作。

第一次父行删除整体失败。先移除阻塞任务，CASCADE 与 SET NULL 才分别执行其生命周期规则。依据原文已有结果，本次未运行数据库。

快速验证

把下面内容保存为 foreign-key-actions.sql，在可丢弃的 PostgreSQL 18 数据库中执行 psql -X -v ON_ERROR_STOP=1 -f foreign-key-actions.sql。实验用临时表分别表示任务、随项目存在的文件和需要保留的历史，并选择不同删除动作。末尾回滚会清除全部对象和修改。

\set ON_ERROR_STOP on
BEGIN;
CREATE TEMP TABLE projects (id integer PRIMARY KEY);
CREATE TEMP TABLE tasks (id integer PRIMARY KEY,project_id integer REFERENCES projects ON DELETE NO ACTION);
CREATE TEMP TABLE files (id integer PRIMARY KEY,project_id integer REFERENCES projects ON DELETE CASCADE);
CREATE TEMP TABLE audit_history (id integer PRIMARY KEY,project_id integer REFERENCES projects ON DELETE SET NULL);
INSERT INTO projects VALUES (1),(2);
INSERT INTO tasks VALUES (10,1),(11,NULL);
INSERT INTO files VALUES (20,1);
INSERT INTO audit_history VALUES (30,1);
DO $$ BEGIN
 INSERT INTO tasks VALUES (12,999);
 RAISE EXCEPTION 'dangling reference accepted';
EXCEPTION WHEN foreign_key_violation THEN RAISE NOTICE 'missing project rejected';
END $$;
DO $$ BEGIN
 DELETE FROM projects WHERE id=1;
 RAISE EXCEPTION 'referenced project deleted';
EXCEPTION WHEN foreign_key_violation THEN RAISE NOTICE 'NO ACTION blocked parent deletion';
END $$;
DO $$ BEGIN
 IF (SELECT count(*) FROM files) <> 1 OR
 (SELECT project_id FROM audit_history WHERE id=30) IS DISTINCT FROM 1 THEN
 RAISE EXCEPTION 'failed deletion left partial side effects';
 END IF;
END $$;
DELETE FROM tasks WHERE id=10;
DELETE FROM projects WHERE id=1;
SELECT * FROM tasks;
SELECT * FROM audit_history;
SELECT count(*) AS remaining_files FROM files;
DO $$ BEGIN
 IF (SELECT array_agg(id ORDER BY id) FROM projects) IS DISTINCT FROM ARRAY[2] THEN
 RAISE EXCEPTION 'wrong surviving project';
 END IF;
 IF (SELECT count(*) FROM files) <> 0 OR
 (SELECT count(*) FROM audit_history WHERE id=30 AND project_id IS NULL) <> 1 OR
 (SELECT count(*) FROM tasks WHERE id=11 AND project_id IS NULL) <> 1 THEN
 RAISE EXCEPTION 'wrong delete action or null handling';
 END IF;
END $$;
ROLLBACK;

PostgreSQL 18.6 拒绝了引用项目九百九十九的任务，却接受了引用为空的任务十一。第一次删除项目一失败，因为任务十仍然引用它。失败的语句不会只删掉其他依赖数据而留下半套结果，这一点也需要与成功删除后的级联行为区分。

显式删除任务十之后，再删父行就成功了。文件通过 CASCADE 消失；历史记录三十仍然存在，但项目列变为 NULL；原来就没有项目引用的任务十一也保留下来。项目二没有子记录，照样合法存在。断言检查这些不同结果，说明“引用必须有效”与“子记录必须跟着删除”是不同契约。审阅 schema 变更时，可以用同样的生命周期案例与应用负责人核对，而不是只确认建表语句能执行。

来源

PostgreSQL 约束，引用完整性、空值、删除动作和索引，已核验 2026-09-10。
PostgreSQL CREATE TABLE，外键匹配与延迟检查语法，已核验 2026-09-10。

EXPLAIN 计划揭示查询路径

Fri, 21 May 2027 00:00:00 +0000

EXPLAIN 展示数据库为语句选择的执行计划，可以帮助定位昂贵工作与错误估算。不过，慢请求也可能涉及锁等待、网络传输或计划之外的应用行为。应利用计划检验一个明确假设，而不是认定每次性能问题都需要换扫描方式或增加索引。计划是诊断证据的一部分，不是整条请求链路的完整时间账本。

读计划树时避免重复计数

在 PostgreSQL 中，叶节点通常扫描关系，上层节点负责连接、排序、聚合或修改行。上层也会做真实工作，不能说全部工作都在叶子。上层成本包含子节点成本，把所有显示的 cost 相加会重复计算。rows 估算表示节点输出的行数，不一定是它检查过的全部行；过滤可以造成输入与输出差距，这本身并不能证明规划错误。

普通 EXPLAIN 只有估算；EXPLAIN ANALYZE 会真正执行语句并补充观察。loops 大于一时，actual rows 与时间通常是每次执行的平均值，要结合循环次数解释。比较估算时，应对照同一节点的实际输出，而不是无关的整表规模。buffers 也包含子节点活动，并不是去重后的页面计数，不能把所有层的数字直接相加当作总读取量。

统计信息影响选择

行数、分布、相关性、查询结构与成本设置都会影响规划。ANALYZE 更新统计信息，但行数估算严重错误，并不唯一指向统计过期。抽样误差、相关谓词、缺少扩展统计和参数选择率，也可能产生偏差。适当时刷新相关统计，再看差距是否真正改善，不要把一次较大的估算偏差当作已经完成根因诊断。

规划器也不是看见刚刚测到的缓存命中率变化，就自动决定改道。effective_cache_size 等设置表达缓存假设；真实缓存冷热可以改变执行时间，即使计划完全相同。比较结果时，应记录数据规模、参数、相关设置和测量条件。查询需要大部分表数据时，顺序扫描可能正是合理选择，不能把出现 Seq Scan 当成索引失效的通用判据。

坏掉的样子

预编译语句要按具体版本解释。PostgreSQL 自动策略可以比较定制计划与通用计划，并不是简单把首次参数的计划固定给所有后续值。应使用有代表性的参数执行 EXPLAIN EXECUTE，检查计划里出现的是常量还是参数占位符。不同数据库产品的缓存机制不同，不能把某一个产品的解释直接套到另一个实现。

函数、类型转换和排序规则，可能让某个索引无法匹配谓词，但不代表一定强制全表扫描。表达式索引可以支持 lower(column)，一些跨类型运算也仍可使用索引。PostgreSQL 遇到不支持的 varchar 与整数比较时，还可能直接拒绝语句，而不是静默转换后扫描。决定改写之前，应检查真实运算符、类型和索引条件，避免凭语法外观推断执行路径。

EXPLAIN ANALYZE 不是无副作用的查看命令。写入、触发器、锁和被调用函数都会实际执行；事务回滚也无法撤销所有效果，例如已经消费的序列值或外部动作。应使用受控数据及合适的测试环境，即使 SELECT 也可能调用具有副作用的函数。诊断前评估负载，不能因为命令以 EXPLAIN 开头，就自动视为生产环境里的安全读取。

确认收益，而不只是计划形状变化

保留可比较的前后结果。计划变了可能更慢，计划形状没变也可能因实际工作量、数据或执行条件改善而更快。应一起查看耗时、输出正确性、行数估算、buffers、loops 和磁盘溢出。cost 单位不是毫秒，低成本估算不保证实际延迟。目标是能解释并复现的收益，不是让计划截图看起来更像预期答案。

所有条形使用相同相对成本尺度。反转来自玩具公式与给定选择率，并非数据库执行测量。本次未运行模型。

快速验证

把下面程序保存为 plan_route_check.py，用 python3 plan_route_check.py 执行。它只使用标准库，在刻意错误的选择率下模拟两条候选路径，不调用 PostgreSQL，也不复现真实优化器。过期输入是这个用例预先设定的事实；告警要求继续调查，不能把所有真实计划里的估算偏差都诊断为统计过期。

#!/usr/bin/env python3
"""教学用规划器模型：按估算成本选路线，按实际行数验路线。

仅用标准库。它模拟统计信息过期：规划器以为只有 500 行命中，
实际有 600,000 行，并检查估算偏差告警是否触发。
"""

from __future__ import annotations


def seq_scan_cost(pages: float, rows: float) -> float:
 return pages * 1.0 + rows * 0.01


def index_scan_cost(selectivity_est: float, pages: float, rows: float) -> float:
 heap_pages = selectivity_est * pages
 return 4.0 + heap_pages * 4.0 + selectivity_est * rows * 0.01


def main() -> None:
 pages, rows = 8_000.0, 1_000_000.0
 stale_selectivity = 0.0005 # 规划器的信念：500 行
 true_selectivity = 0.60 # 现实：600,000 行
 est_rows = stale_selectivity * rows
 actual_rows = true_selectivity * rows

 seq = seq_scan_cost(pages, rows)
 idx_est = index_scan_cost(stale_selectivity, pages, rows)
 idx_true = index_scan_cost(true_selectivity, pages, rows)
 chosen = "索引扫描" if idx_est < seq else "顺序扫描"
 print(f"估算行数：{est_rows:.0f}；实际行数：{actual_rows:.0f}")
 print(f"估算成本：顺序扫描={seq:.1f} 索引扫描={idx_est:.1f} -> 规划器选择{chosen}")
 print(f"实际区分度下的真实成本：顺序扫描={seq:.1f} 索引扫描={idx_true:.1f}")

 error = abs(actual_rows - est_rows) / actual_rows
 print(f"估算偏差：{error:.1%}")
 warned = False
 if error > 0.50:
 warned = True
 print("告警：行数估算偏差超过 50%——请检查统计信息、谓词与参数选择率。")
 if chosen == "索引扫描" and idx_true > seq:
 warned = True
 print("告警：在真实区分度下所选路线更贵——请对照 EXPLAIN ANALYZE。")
 assert warned, "该用例应当触发统计信息过期告警"
 assert est_rows < actual_rows / 10, "用例需保持估算比实际低一个数量级"
 print("PASS：规划器选中了过期路线，估算偏差告警已触发")


if __name__ == "__main__":
 main()

模型按估算选择索引扫描，成本二十五，小于顺序路径的一万八千。在给定实际选择率下，模型的索引成本变成二万五千二百零四；程序输出百分之九十九点九的估算偏差，在告警后输出 PASS。这些成本都是简化公式的结果，不是真实数据库执行耗时，也不是从生产计划中采集的数字。

实验确认算术与预先构造的反例，不验证某个 PostgreSQL 计划，不足以批准增加索引，也不能证明 ANALYZE 会修好线上查询。调整真实负载之前，仍需用实际计划和受控执行证据重复调查。保留玩具模型与数据库实验的区别，才能避免把教学示例的成功误报为优化器已经完成验证。

来源

PostgreSQL：EXPLAIN，生成计划，已核验 2026-10-15。
PostgreSQL：使用 EXPLAIN，解读输出，已核验 2026-10-15。
PostgreSQL：规划器与优化器，路线如何被选定，已核验 2026-10-15。
MySQL：EXPLAIN 语句，计划格式与输出列，已核验 2026-10-15。
PostgreSQL PREPARE，通用计划与定制计划选择，已核验 2026-10-15。
PostgreSQL 表达式索引，包括 lower(column) 的表达式索引，已核验 2026-10-15。

查询参数守住取值与 SQL 的边界

Mon, 17 May 2027 00:00:00 +0000

参数化查询通过不同的接口参数传递数据库指令与实际取值。数据库把指令解释为 SQL，再把各个参数用于需要值的位置。这种边界既适用于 SQLite 这样的嵌入式引擎，也适用于客户端连接服务端的数据库；它不依赖一次网络交互，更不要求应用显式管理命名的服务端语句。重点在真实调用如何传值，而不是有没有某个名为“预编译”的包装函数。

坏掉的样子

字符串拼接会拆掉这条边界。姓名中的一个引号可能提前结束原本的字面量，后面的文本就有机会变成条件或注释。仅仅禁用分号无法修复问题，因为攻击者可以在不追加第二条语句的情况下，改变同一条查询的含义。同样，一个接口即使拒绝一次执行多条语句，也仍然需要正确绑定参数，不能把这个限制当作注入防护已经完成的证据。

绑定可以防止值变成 SQL 语法，但所选运算符仍会按自身规则解释这个值。对于 LIKE，百分号匹配一段字符，下划线匹配一个字符。因此，一个经过绑定的搜索串，仍可能比用户期望的普通文本搜索匹配更多记录。这属于模式语义的问题，不说明绑定失效，却说明“输入不会执行成 SQL”还不等于“搜索符合产品要求”。

另外一些错误也不会造成注入，却会给出错误结果。把逗号分隔的文本交给一个 IN 占位符，它仍是一个标量，不会自动展开成列表。把列名当作值绑定，得到的仍是文本，不是列引用。因此，类型检查、允许的查询结构与业务权限，都需要在绑定之外独立成立。

绑定保护 SQL 语法，LIKE 仍解释通配符。列表、标识符和页大小政策分别有自己的契约。本地 SQLite 断言，不代表生产保障。

快速验证

直接运行下面的完整 Python 脚本，只需要标准库 sqlite3。它创建内存数据库作为样本，完成断言后关闭连接。记录中的运行环境为 Python 3.12.14 与 SQLite 3.53.1。故意保留的脆弱查询仅用于比较三个虚构用户的结果，不连接任何真实业务数据：

import sqlite3

with sqlite3.connect(':memory:') as db:
 db.execute('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)')
 db.executemany('INSERT INTO users VALUES (?, ?)', [(1, 'Alice'), (2, 'A_1'), (3, 'Ab1')])
 payload = "' OR 1=1 --"
 # Deliberately vulnerable comparison, only against this in-memory fixture.
 unsafe = "SELECT id FROM users WHERE name='" + payload + "' ORDER BY id"
 assert sorted(db.execute(unsafe).fetchall()) == [(1,), (2,), (3,)]
 assert db.execute('SELECT id FROM users WHERE name=?', (payload,)).fetchall() == []
 print('concatenated: 3 rows; bound: 0 rows')
 for value in ("O'Reilly", r'a\b', 'x; DROP TABLE users; --'):
 assert db.execute('SELECT ?', (value,)).fetchone() == (value,)
 assert db.execute('SELECT count(*) FROM users').fetchone() == (3,)
 print('quote, backslash, semicolon: literal round trips')
 assert db.execute('SELECT id FROM users WHERE name LIKE ? ORDER BY id', ('A_1',)).fetchall() == [(2,), (3,)]
 literal = 'A_1'
 escaped = literal.replace('!', '!!').replace('%', '!%').replace('_', '!_')
 assert db.execute("SELECT id FROM users WHERE name LIKE ? ESCAPE '!' ORDER BY id", (escaped,)).fetchall() == [(2,)]
 assert db.execute('SELECT id FROM users WHERE name=?', (literal,)).fetchall() == [(2,)]
 print('bound LIKE: 2 rows; escaped LIKE and equality: 1 row')
 assert db.execute('SELECT id FROM users WHERE id IN (?)', ('1,3',)).fetchall() == []
 assert db.execute('SELECT id FROM users WHERE id IN (?,?) ORDER BY id', (1, 3)).fetchall() == [(1,), (3,)]
 assert db.execute('SELECT ? FROM users LIMIT 1', ('name',)).fetchone() == ('name',)
 assert db.execute('SELECT id FROM users ORDER BY id LIMIT ? OFFSET ?', (1, 1)).fetchall() == [(2,)]
 assert db.execute('SELECT id FROM users ORDER BY id LIMIT ?', (-1,)).fetchall() == [(1,), (2,), (3,)]
 assert db.execute('SELECT id FROM users ORDER BY id LIMIT ?', (0,)).fetchall() == []
 print('IN needs separate values; bound column is a literal; LIMIT/OFFSET bind')
 print('negative LIMIT removes the cap; zero LIMIT returns no rows')
db.close()

拼接查询返回三个编号，绑定查询面对相同输入则没有任何匹配。恶意输入中的注释还会删掉原先追加的排序部分，因此断言先对脆弱查询的结果排序，再比较编号集合；实验没有依赖未声明顺序的查询恰巧按插入顺序返回。这也展示了注入会改变原指令的多个部分，不只是多匹配一行那么简单。

接下来的断言确认引号、反斜杠和带有分号的字符串全部原样往返，表中记录数仍为三。这些检查真正调用了 SQLite 驱动，并非模拟字符串转义，也不是看查询文本中有没有问号。审阅真实调用点时，应把 SQL 文本与参数传入方式一起看，不能只审一个看似安全的查询模板，却忽略调用方已经提前拼接了值。

绑定后的模式 A_1 同时匹配名字 A_1 和 Ab1。指定感叹号作为转义字符并转义下划线后，结果才缩小到原样名字。如果搜索文本本身可能包含感叹号，必须先转义这个转义字符，再处理百分号和下划线。若需求只是完全相等匹配，直接使用等号更简单，在本例中也只返回那个原样名字，没有必要先引入模式语义再尝试消除它。

单个参数中的 1,3 没有匹配任何编号；两个占位符分别绑定两个整数，才返回编号一和三。后一个查询返回字面文本 name，说明值占位符不能用来选择某列。最后，数量和偏移量都采用数字绑定，返回编号二。分页不需要把数字先转换为字符串再拼进 SQL。SQLite 的 LIMIT 绑定负一会取消数量上限，绑定零则不返回记录；新增断言展示了，即便语法传参安全，应用仍需独立规定页大小范围，不能把已绑定整数直接当成资源限制已经成立。

检查完整数据路径

占位符必须符合实际驱动接口。Python 的 SQLite 接口支持问号与命名参数，Psycopg 则使用另一套记法。参数集合应独立传入，不应先做宿主语言的格式化。即使某个值来自自己的数据库，再次用于查询时也仍是数据；它曾经被存储过，并不能使下一次把它拼进 SQL 的操作自动安全。持久化来源不是语法信任标记。

对于长度变化的列表，只构造必要的占位符结构，再逐项绑定；驱动提供受支持的集合能力时，可按其文档使用。同时定义空列表语义，并遵守参数数量上限。动态标识符和排序关键字需要在允许的查询结构中选择；对任意 SQL 文本删掉几个标点，并不能可靠替代这项选择，也可能改变合法输入的含义。

即使所有值都已绑定，仍应限制页大小，并按对象检查权限。参数化保护的是 SQL 语法边界，不是整个业务操作。验证应同时覆盖正常返回、看起来像攻击的字符串以及所用运算符的特殊输入，避免一次安全改写悄悄扩大搜索范围、改变排序，或者因为原本就缺少权限条件而继续暴露其他用户的记录。

来源

SQLite SELECT，负数与零 LIMIT 的行为，已核验 2026-10-15。
Python sqlite3，驱动占位符与参数绑定接口，已核验 2026-09-12。
SQLite 表达式，参数、LIKE 转义与 IN 语义，已核验 2026-09-12。
OWASP SQL 注入防护，参数化取值与允许的结构选择，已核验 2026-09-12。

事务让提交是原子的

Wed, 12 May 2027 00:00:00 +0000

事务让相关数据库变更一起提交，或者一起放弃。如果一次操作要求扣减一个账户、增加另一个账户，并写入流水，那么这三步就应属于同一个决定。PostgreSQL 通过 BEGIN、COMMIT 和 ROLLBACK 提供这个边界，但应用仍须把正确的语句放进去。原子执行不会自动发现漏掉的入账，也不会替业务补出一个没有编写的校验。事务保护的是被明确纳入其中的工作，而不是开发者脑中尚未落实的意图。

第二次转账失败后，应恢复已提交余额与流水行数。COMMIT 回复丢失则属于另一种不确定状态，须核对实际结果。此概念图不增加运行验证证据。

决定一个工作单元包含什么

普通 psql 在没有显式事务块时使用自动提交，每条语句各自处于一个事务里。因此，扣款可能已经成功提交，之后的流水插入才失败。显式分组改变了失败边界：其他事务看不到这组操作尚未提交的表数据中间状态；回滚直接丢弃其事务性变更，而不是依赖应用事后再发几条补偿更新来还原。

原子性与隔离性、持久性并不是同一件事。如果隔离级别或加锁协议不足，一组完整提交的操作仍可能基于错误的并发判断。数据库确认提交后的持久保障，也受到实际持久化配置影响。仅在代码里找到 BEGIN，还不能回答这些问题。同样，PostgreSQL 的每条语句本来就运行在事务中，读取也不例外；显式读事务可以用于重复读取快照或事务局部设置，不能一概视为无用开销。

坏掉的样子

PostgreSQL 中未处理的 SQL 错误通常会让显式事务块进入失败状态。客户端必须整体回滚，或者回滚到适用的早期保存点，才能恢复正常执行。关闭客户端的遇错停止功能，并不会修复服务器端已经失败的事务。如果把这种连接直接还给连接池，下一个请求可能接着遇到失败状态，而不是从干净边界开始。

服务器明确拒绝提交，与提交确认在网络中丢失，是不同证据。如果连接在等待 COMMIT 回复时断开，客户端可能不知道数据库是否已先完成提交。盲目重发支付可能导致重复操作。持久的操作标识和结果核对用于处理这种不确定性；普通回滚语义不能证明一个暂时无法联系的服务器究竟完成了什么。不能把所有客户端报错都解释成“肯定什么也没发生”。

快速验证

在可丢弃的 PostgreSQL 18 数据库中打开新的 psql -X -v ON_ERROR_STOP=1 会话，运行下面代码。临时表让这些账户编号只属于本会话。代码仅在两个刻意制造的失败周围关闭遇错停止，以便观察 SQLSTATE，随后立即重新开启。

\set ON_ERROR_STOP on
CREATE TEMP TABLE accounts (id integer PRIMARY KEY,balance integer CHECK(balance>=0));
CREATE TEMP TABLE ledger (id integer PRIMARY KEY,amount integer CHECK(amount>0));
INSERT INTO accounts VALUES (1,100),(2,100);
BEGIN;
UPDATE accounts SET balance=balance-20 WHERE id=1;
UPDATE accounts SET balance=balance+20 WHERE id=2;
INSERT INTO ledger VALUES (1,20);
COMMIT;
SELECT id,balance FROM accounts ORDER BY id;
BEGIN;
UPDATE accounts SET balance=balance-30 WHERE id=1;
\set ON_ERROR_STOP off
INSERT INTO ledger VALUES (1,30);
\echo duplicate_error :SQLSTATE
SELECT balance FROM accounts WHERE id=1;
\echo aborted_error :SQLSTATE
\set ON_ERROR_STOP on
ROLLBACK;
SELECT id,balance FROM accounts ORDER BY id;
SELECT count(*) AS ledger_rows FROM ledger;
DO $$ BEGIN
 IF (SELECT array_agg(balance ORDER BY id) FROM accounts) IS DISTINCT FROM ARRAY[80,120]
 OR (SELECT count(*) FROM ledger) <> 1
 OR (SELECT amount FROM ledger WHERE id=1) IS DISTINCT FROM 20 THEN
 RAISE EXCEPTION 'partial transfer survived';
 END IF;
END $$;
DROP TABLE ledger,accounts;

第一个事务提交后，余额是八十和一百二十，流水表有一行。第二个事务又扣减三十，接着尝试复用流水编号一。保留的 PostgreSQL 18.6 执行报告记录唯一性错误 23505；本次评审没有重跑客户端流程。紧跟着的普通读取返回 25P02，证明即使客户端继续发送命令，服务器中的事务也已经处于失败状态。这个阶段看不到正常读取结果，不能误以为失败只影响那一条插入。

回滚后，余额仍然是八十和一百二十，流水仍只有一行，第二次扣款没有保留下来。断言检查相关余额与流水状态；两个打印的 SQLSTATE 仍需单独核对，不能仅凭看见错误就认定回滚一定正确。最后显式删除临时夹具；关闭会话也会移除这些临时表。实验把成功提交、数据库拒绝和清理后的结果分开展示，便于判断每一步实际发生了什么。

这是一项受控的原子性实验，不是完整转账服务。真实操作还应验证目标账户存在、影响行数符合预期、金额满足业务要求，并保护并发决策。否则事务完全可能把一组本来就错误的变更原子提交。原子性不能替代输入校验、行数检查或隔离协议，但可以让这些已经写清楚的步骤共享一个可靠提交边界。

让恢复遵守同一份契约

保存点允许撤销指定范围的工作，同时保留更早的事务性变更。只有部分成功本来就是允许结果时，这才符合业务意图。对于本例，吞掉必需的流水失败后继续提交扣款，就违反了操作契约。数据库过程块捕获异常时，也可能形成更小的回滚范围，因此需要沿真正的异常处理路径理解结果，不能只看最外层有没有事务。

序列已经发出的号码，以及发送邮件等外部动作，不会随着表写入回滚而撤销。可能重试的尝试应避免直接携带不可逆外部效果，或者使用持久协议进行协调。短而明确的事务让提交决定更容易理解；经过检查的结果和清楚的恢复路径，则确保这个决定仍然表达应用真正需要的工作。

来源

PostgreSQL 18：事务，原子分组与回滚边界，已核验 2026-09-10。
PostgreSQL 18：事务隔离，可见性与序列的非事务性行为，已核验 2026-09-10。
PostgreSQL 18：SAVEPOINT，事务内有意保留部分工作的回滚，已核验 2026-09-10。

连接池摊薄缓慢的建连

Thu, 28 Jan 2027 00:00:00 +0000

连接池把一次物理建连的成本分摊到多次使用中，但不会让建连成本消失，也不保证创建池时就已经打开连接。先分清两个对象：业务代码短期持有的借用句柄，以及底层真正连接数据库的连接。关闭前者，通常只是把后者归还池中，等待下一次复用，而不是立即断开数据库连接。

复用是一段生命周期，不是免费执行的承诺

远程数据库建连可能包含 TCP 握手、TLS、认证和会话初始化。复用能够减少每个请求重复执行这些步骤的次数，但 SQL 本身仍然需要时间。连接过期、断线、显式失效或进程替换之后，建连成本还会重新出现。一个进程内应长期复用其拥有的 SQLAlchemy Engine；如果每次请求都重新创建 Engine，那么每次也在重新创建自己的池，原本可以复用的资源就被拆散了。

SQLAlchemy 的池按需增长。配置 pool_size=2 的 QueuePool 起初是空的，并不意味着已经预热两条连接。先后执行的两次借用可以一直使用同一条物理连接；同时发生的借用才可能促使池增长。本例允许保留两条连接，再临时溢出一条，所以有限的 max_overflow=1 对应最多三条同时借用。全部归还后，最多留下两条空闲连接，而不是一直维持三条。

这些参数语义属于具体实现，不应套用到所有连接池。QueuePool 的 pool_size=0 表示取消大小限制，而不是关闭池化；max_overflow=-1 则允许无限溢出。需要限制数据库连接预算时，必须核对所用库的准确契约，并写出明确、有限的值，不能看到零就自行理解为禁用。

坏掉的样子

池被占满，可能是实际并发超过容量，也可能是长事务或借用后未归还。业务看到的总延迟因此需要拆成获取连接的等待与执行查询的时间。pool_timeout 限制的是等待可用槽位，不是新建物理连接的完整耗时，也不是 SQL 执行时间。实验用了很短的浮点数超时，便于触发失败，但这不是精确到几十毫秒的硬实时承诺，不能据此推导整个请求的截止时间。

归还也不等于抹掉上一个借用者留下的所有状态。SQLAlchemy 的默认归还重置通过回滚清理事务状态，并与 Connection.close() 协同完成；已经提交的临时表等会话状态仍可能保留。不要仅凭“用了上下文管理器，连接已经还回去”就推断租户隔离成立。应用需要哪些会话初始化与清理，应按具体数据库的能力和自身契约明确规定。

断线则是另一个边界。显式 invalidate 会丢弃当前底层 DBAPI 连接，之后使用逻辑 Connection 时，再从池取得替代连接。这个替代品可能是另一条现成空闲连接，不一定刚刚新建。如果失效时已有事务，必须先结束该事务才能重连；重连也不是自动恢复一个可能已经产生效果的事务，不能把连接生命周期管理当成业务重试保证。

SQLite 与 SQLAlchemy 实验通过库事件检查生命周期及有限容量，不测量网络建连节省或吞吐。

快速验证

在 macOS 或 Linux 的空目录执行 python3 -m venv .venv，再执行 .venv/bin/python -m pip install SQLAlchemy==2.0.52。把代码保存为 pool_probe.py，用 .venv/bin/python pool_probe.py 运行。本次验证环境是 Python 3.14.4 与 SQLite 3.53.0。脚本自行创建并清理临时数据库，不连接任何数据库服务器，也不使用生产凭据。

from pathlib import Path
import sqlite3
from tempfile import TemporaryDirectory

import sqlalchemy
from sqlalchemy import create_engine, event
from sqlalchemy.exc import TimeoutError as PoolTimeout
from sqlalchemy.pool import QueuePool


assert sqlalchemy.__version__ == "2.0.52"
with TemporaryDirectory(prefix="pool-reuse-") as directory:
 engine = create_engine(
 "sqlite:///" + str(Path(directory) / "probe.db"),
 poolclass=QueuePool, pool_size=2, max_overflow=1, pool_timeout=0.05,
 )
 events = {"opened": 0, "closed": 0}

 @event.listens_for(engine, "connect")
 def opened(dbapi_connection, entry):
 events["opened"] += 1
 entry.info["serial"] = events["opened"]

 @event.listens_for(engine, "close")
 def closed(dbapi_connection, entry):
 events["closed"] += 1

 try:
 assert engine.pool.checkedin() == 0 and events["opened"] == 0
 with engine.begin() as connection:
 serial = connection.info["serial"]
 connection.exec_driver_sql("CREATE TEMP TABLE marker(value INTEGER)")
 connection.exec_driver_sql("INSERT INTO marker VALUES (42)")
 with engine.connect() as connection:
 assert connection.info["serial"] == serial
 assert connection.exec_driver_sql("SELECT value FROM marker").scalar_one() == 42
 assert events["opened"] == 1 and engine.pool.checkedout() == 0
 print("lazy start: 0 physical connections; two sequential leases reuse 1; committed temp state persists")

 held = []
 try:
 for _ in range(3):
 held.append(engine.connect())
 assert len({connection.info["serial"] for connection in held}) == 3
 assert engine.pool.checkedout() == 3 and events["opened"] == 3
 try:
 unexpected = engine.connect()
 except PoolTimeout:
 pass
 else:
 unexpected.close()
 raise AssertionError("the fourth concurrent lease must time out")
 assert events["opened"] == 3
 finally:
 for connection in held:
 connection.close()
 assert engine.pool.checkedout() == 0 and engine.pool.checkedin() == 2
 assert events["closed"] == 1
 print("2 persistent slots + 1 overflow allow 3 leases; the fourth times out; only 2 remain idle")

 with engine.connect() as connection, engine.connect() as occupied:
 previous = connection.info["serial"]
 occupied_serial = occupied.info["serial"]
 connection.invalidate() # No transaction has started on this lease.
 assert connection.exec_driver_sql("SELECT 1").scalar_one() == 1
 assert connection.info["serial"] != previous
 assert occupied.info["serial"] == occupied_serial
 assert connection.exec_driver_sql(
 "SELECT count(*) FROM sqlite_temp_master WHERE name = 'marker'"
 ).scalar_one() == 0
 assert events["opened"] == 4
 print("with the other slot occupied, invalidation forces a new physical connection without the old temp table")
 finally:
 engine.dispose()
 assert events == {"opened": 4, "closed": 4}
print("all 4 connect events have matching close events; SQLite", sqlite3.sqlite_version)

第一行输出通过 connect 事件和保存在底层连接上的序号，证明池从零开始、两次顺序借用只创建一条物理连接。第一次借用提交的临时标记在下一次仍然可见，因此事务回滚式重置并不是完整会话重置。接着同时保留三份借用，第四次获取抛出 PoolTimeout；归还之后只剩两条空闲连接，并出现一次 close 事件。这同时区分了借用数量、可保留的空闲数量和真实建连次数。

失效检查特意先占住另一条空闲连接，保证后续 SQL 不能直接借到现成的替代品，因而确实触发新建物理连接。新连接的临时模式中没有旧标记。如果不占住那个槽位，池完全可以借出另一条空闲连接，因此“invalidate 必然建连”的断言就是错的。最后先归还全部借用，再 dispose 池，观察到四次 connect 与四次 close 事件对应。这里统计的是库事件，不是对任意后端关闭失败情形的资源回收强保证。

这个本地实验验证生命周期和容量，并没有测量 TCP、TLS 的节省时间，也不是吞吐基准。真正调整生产池时，应同时记录建连频率、获取等待、持有时长和查询延迟，辨别时间到底花在哪里。增大池必须仍然满足共享数据库的预算；它不能单独修好泄漏，也不能让慢查询自动变快。

来源

SQLAlchemy 连接池，按需创建、QueuePool 上限与归还重置，已核验 2026-09-09。
SQLAlchemy Engine 与 Connection，Engine 生命周期、连接信息与失效处理，已核验 2026-09-09。
SQLAlchemy 连接池事件，connect 与 close 事件语义，已核验 2026-09-09。
Python sqlite3，实验使用的本地数据库运行时，已核验 2026-09-09。

迁移是可版本化的 schema 变更

Sun, 24 Jan 2027 00:00:00 +0000

数据库的 schema 不是一次性的设计;它随使用它的软件一起演进。与其临时编辑 schema,不如用迁移应用一组命名、有序的变更,让任何环境都能重放。

把 schema 当代码

把 schema 当源代码一样对待：每一条迁移都是一个带顺序、带编号、被命名的小步骤，把库从一个状态推进到下一个状态，整个序列都收进仓库。全新的库从空库开始重放这些步骤直到当前版本，这正是测试建库、临时环境克隆、安装新机器的统一口径；没有人再对着线上实例随手敲一条 ALTER TABLE。schema 也因此从「某个实例才知道的事实」变成有历史、可 review、有 diff 的正式产物。

顺序就是契约

在起始结构相同、引擎兼容、所需扩展齐备且步骤确定的前提下，有序重放才能复现预期结构。只有顺序相同，不能消除环境差异或依赖已有数据的变化。这种可预测性就是契约：它让测试能创建全新数据库、让暂存能克隆，让运维升级时不用靠猜。随之而来的铁律是——凡是已经被任何环境执行过的迁移，都不得重写或重排，因为执行器依靠已记录的身份决定哪些步骤已经执行；这种身份不一定包含内容校验和。篡改历史可能造成环境分叉，需要检查实际状态，再通过明确的前向修复恢复一致。

危险在不可逆

删除列或表的迁移一旦提交，就会丢失所存数据；只重建结构不能找回原值，必须谨慎对待。给它们配一张清单：先备份，把 drop 拆成单独的后续迁移，这样能先回滚前面的 schema 改动，最后再面对不可逆的破坏。真正的纪律是「只能向前、但留有退路」——绝不要写一条把维护者锁在门外的迁移。上线前一定要在 staging 上跑一遍这类破坏性迁移，让失败模式在真正投入生产前就变成一件平淡无奇的事。

坏掉的样子

最贵的一种坏法，是把不可逆迁移直接送上生产。在 PostgreSQL 里，删除列不需要重写表，但仍需取得 ACCESS EXCLUSIVE 锁。许多类型转换或新增带易变默认值的列需要重写；符合条件的二进制兼容转换可以免去重写，却不会因此免去所需的锁及等待时间。大型重写可能长期等待或运行。PostgreSQL 的事务性 DDL 失败后可以回滚；是否留下部分结果，取决于先前提交、非事务步骤与执行器事务边界，不能把超时一概理解为半张表已经改好。而 down 迁移并不能撤销数据丢失：删掉邮箱列再加回来，得到的是空列，而不是被删掉的地址。破坏性步骤应当拆成独立的后续迁移，上线前先备份，优先使用扩张再收缩的顺序，先加新结构，再回填数据，最后删除旧结构，让每一次发布都平淡无奇。换句话说，只要迁移涉及删数据，就默认它回不来。

另外两类经典故障是并发双跑和篡改历史。如果两个发布副本在没有任何锁的情况下同时执行迁移，它们可能重复应用同一版本，也可能把版本顺序搅乱。生产级的 runner 因此只允许单个执行者，或者借助 PostgreSQL 咨询锁之类的机制加锁，而 golang-migrate 在失败后会把库标记为 dirty，而不是假装一切正常。重写已经被应用过的迁移，或者合并了两个各自新增版本 7 的分支，都会让历史分叉：环境可能分叉。还要检查执行器到底保存什么：golang-migrate 的 PostgreSQL 账本保存版本与 dirty 状态，并不为每份文件保存内容校验和。先核对实际状态，再设计前向修复，不能假定工具自动发现所有历史编辑。strong_migrations 这类工具会在执行迁移时检查危险操作；应先在开发环境运行检查，再安排部署，不能把它当成自动覆盖所有风险的静态审查。

版本与名称账本让本地迁移链可重复执行，但不能发现任意代码编辑，也不能恢复被删数据。历史通过仅覆盖内存模型，未测试真实锁、并发迁移器或备份恢复。本次绘图未重跑示例。

快速验证

把下面代码保存为 migration_chain_check.py，运行 python3 migration_chain_check.py（需要 Python 3.10 或更新版本）。它只用标准库，以内存中的字典模拟 schema，用 applied 账本模拟 schema_migrations 表，按顺序执行三个迁移的 up 与 down，不需要真实数据库。身份只由版本与名称组成，不是代码内容摘要；它能发现重命名，不能发现任意函数体修改。账本为空时高版本无法先行，也不代表完整生产迁移器的全部行为。

"""Simulate a versioned migration chain with an applied ledger (stdlib only)."""

# Each migration is (version, name, up, down). down=None means irreversible.
# The `applied` dict emulates a schema_migrations table: version -> a name-based identity (not a content digest).

def identity(version, name):
 return "%d:%s" % (version, name)


def make_migrations():
 db = {"users": []}

 def up1():
 db["users"] = []

 def down1():
 del db["users"]

 def up2():
 for user in db["users"]:
 user["email"] = None
 db["has_email_column"] = True

 def down2():
 # Irreversible in effect: dropping the column destroys its data.
 for user in db["users"]:
 del user["email"]
 del db["has_email_column"]

 def up3():
 db["index_on_email"] = True

 def down3():
 del db["index_on_email"]

 migrations = [
 (1, "create_users", up1, down1),
 (2, "add_email_column", up2, down2),
 (3, "add_email_index", up3, down3),
 ]
 return db, migrations


def apply_single(db, applied, migrations, version):
 by_version = {m[0]: m for m in migrations}
 assert version in by_version, "unknown migration version: %r" % (version,)
 wanted = by_version[version]
 if version in applied:
 if applied[version] != identity(version, wanted[1]):
 raise RuntimeError("version drift: v%d was edited after apply" % version)
 return "skipped" # idempotent re-run
 missing = [m[0] for m in migrations if m[0] < version and m[0] not in applied]
 if missing:
 raise RuntimeError("out of order: v%d needs missing %s first" % (version, missing))
 wanted[2]()
 applied[version] = identity(version, wanted[1])
 return "applied"


def migrate_up(db, applied, migrations):
 results = []
 for m in migrations:
 results.append((m[0], apply_single(db, applied, migrations, m[0])))
 return results


def migrate_down(db, applied, migrations, target):
 by_version = {m[0]: m for m in migrations}
 while applied and max(applied) > target:
 version = max(applied)
 migration = by_version[version]
 assert migration[3] is not None, "v%d is irreversible" % version
 migration[3]()
 del applied[version]
 return sorted(applied)


# 1. Fresh database replays the whole chain in order.
db, migrations = make_migrations()
applied = {}
assert migrate_up(db, applied, migrations) == [(1, "applied"), (2, "applied"), (3, "applied")]
assert sorted(applied) == [1, 2, 3] and db["has_email_column"] is True
print("fresh replay applies v1..v3 in order:", sorted(applied))

# 2. Re-running is idempotent: the applied ledger makes it a no-op.
assert migrate_up(db, applied, migrations) == [(1, "skipped"), (2, "skipped"), (3, "skipped")]
assert sorted(applied) == [1, 2, 3]
print("second run is a no-op; applied ledger still:", sorted(applied))

# 3. Out-of-order apply is rejected instead of silently forking history.
db2, migrations2 = make_migrations()
applied2 = {}
try:
 apply_single(db2, applied2, migrations2, 3)
except RuntimeError as error:
 assert "out of order" in str(error), error
 print("out-of-order v3 rejected:", error)
else:
 raise AssertionError("applying v3 before v1..v2 must fail")
assert applied2 == {} and "index_on_email" not in db2

# 4. Rollback runs downs in reverse and only to the requested target.
assert migrate_down(db, applied, migrations, 2) == [1, 2]
assert "index_on_email" not in db and sorted(applied) == [1, 2]
assert migrate_up(db, applied, migrations) == [(1, "skipped"), (2, "skipped"), (3, "applied")]
print("rollback to v2 drops the index; re-up restores it:", sorted(applied))

# 5. A down migration destroys data: emails do not come back on re-up.
db["users"].append({"id": 1, "email": "a@example.com"})
assert migrate_down(db, applied, migrations, 1) == [1]
assert db["users"] == [{"id": 1}] # email column (and its values) is gone
assert migrate_up(db, applied, migrations)[1] == (2, "applied")
assert db["users"] == [{"id": 1, "email": None}] # re-up gives NULL, not the old address
print("down v2 drops stored emails; re-up yields None instead of the original")

# 6. Editing an already-applied migration is version drift, not a fix.
drifted = [(v, n + "_renamed" if v == 2 else n, u, d) for v, n, u, d in migrations]
try:
 migrate_up(db, applied, drifted)
except RuntimeError as error:
 assert "drift" in str(error), error
 print("edited history detected:", error)
else:
 raise AssertionError("renaming applied v2 must fail")

print("PASS: ordered up, idempotent ledger, rejected jump, ordered rollback, lossy down, drift check")

六个场景依次验证：全新库按顺序重放版本一到版本三；第二次运行因为账本已经记录名称身份而成为空操作；跳过前置版本直接应用版本三会被拒绝；回滚到版本二只撤销索引，重跑后索引恢复；回滚版本二证明 down 是有损的，存入的邮箱地址在重新应用后变成空值而不是原文；重命名已应用的迁移会被判定为版本漂移。只有全部断言通过，最后一行才会打印 PASS。

这个实验只验证顺序、幂等、回滚与漂移逻辑，不覆盖真实数据库锁、并发执行者与备份恢复。修订后的完整示例已在 Linux、Python 3.12.14 下运行通过。动生产之前，请先在暂存环境的副本上演练真实迁移，并确认 down 路径能恢复到预期状态。

来源

golang-migrate/migrate，带 dirty 状态跟踪的版本化 up/down 迁移，已核验 2026-10-15。
PostgreSQL：ALTER TABLE，表变更的锁与重写行为，已核验 2026-10-15。
strong_migrations，拦截危险迁移如阻塞性操作，已核验 2026-10-15。

有界重试给事务一次重新执行的机会

Mon, 09 Nov 2026 00:00:00 +0000

重试可以帮助恢复因为并发而被拒绝的事务，但不能保证成功，也不会自动让外部副作用变成幂等。重试单位应包含决定写入内容的所有数据库读取与应用判断。如果新事务仍使用第一次快照算出的金额或目标值，即使执行了新的开始事务命令，也没有真正重新做出适合当前数据的决策。

收到明确并发拒绝后，在统一预算内重做读取、判断与写入。永久错误或预算耗尽应停止，提交结果未知时先核对；数据库回滚不能撤销外部副作用。

坏掉的样子

PostgreSQL 用 40001 表示序列化失败，用 40P01 表示死锁。收到这些明确拒绝后，可以在回滚并检查剩余预算的前提下再次尝试完整操作。唯一约束错误却可能是永久的：同一个无效标识不会因为多等一会儿就变成合法输入。某些键值确实由此前查询结果决定，需要特定业务的重算策略，不能据此将所有异常都塞进统一重试循环。

错误既可能发生在语句执行期间，也可能出现在提交阶段。服务器明确拒绝事务，与客户端等待提交确认时连接断开，是两种不同情况。后一种可能已经提交，只是确认没有传回来；盲目重放就可能重复操作。在数据库事务之外已经完成的支付、发信等动作，也不会随着数据库回滚自动撤销。循环本身既不能回收这些副作用，也不能凭空识别重复。

快速验证

准备 Linux 或 macOS 上的 Python 3，以及可通过命令路径运行的 PostgreSQL 18 客户端 psql。设置 PGDATABASE、PGHOST 及必要连接参数，明确指向允许创建模式的可丢弃数据库。提前配置好认证，示例禁止交互式密码提示。把下面的程序保存为 retry-demo.py，再执行 python3 retry-demo.py。请独占一个可丢弃数据库；同名实验模式已经存在时，初始化会失败。初始化位于清理块之前，后续初始化步骤失败可能留下刚创建的对象；应先检查该次失败，再决定重试或清理，不能删除来源不明的同名模式。

import os
import random
import re
import selectors
import subprocess
import time

PSQL = ['psql', '-X', '-w', '-qAt', '-v', 'ON_ERROR_STOP=1', '-v', 'VERBOSITY=sqlstate']
ENV = dict(os.environ, PGCONNECT_TIMEOUT='2')


def run(sql):
 return subprocess.run(PSQL, input=sql, text=True, capture_output=True,
 check=True, timeout=5, env=ENV).stdout.strip()


def read_value(worker):
 deadline = time.monotonic() + 5
 data = bytearray()
 with selectors.DefaultSelector() as ready:
 ready.register(worker.stdout, selectors.EVENT_READ)
 while b'\n' not in data:
 remaining = deadline - time.monotonic()
 if remaining <= 0 or not ready.select(remaining):
 raise TimeoutError('Initial read was not confirmed')
 chunk = os.read(worker.stdout.fileno(), 4096)
 if not chunk:
 raise RuntimeError('Connection ended before initial read')
 data.extend(chunk)
 return int(data.strip())


def attempt(mode, number):
 worker = subprocess.Popen(PSQL, stdin=subprocess.PIPE, stdout=subprocess.PIPE,
 stderr=subprocess.PIPE, text=True, env=ENV)
 try:
 worker.stdin.write("SET statement_timeout='1s';\n"
 'BEGIN ISOLATION LEVEL REPEATABLE READ;\n'
 'SELECT n FROM retry_demo.counter WHERE id=1;\n')
 worker.stdin.flush()
 observed = read_value(worker)
 # A real second connection commits after this attempt's snapshot.
 if mode == 'always' or (mode == 'once' and number == 1):
 run('UPDATE retry_demo.counter SET n=n+1 WHERE id=1;')
 statement = ('INSERT INTO retry_demo.counter VALUES (1,99);' if mode == 'permanent'
 else f'UPDATE retry_demo.counter SET n={observed + 1} WHERE id=1;')
 finish = r'''
\set ON_ERROR_STOP off
__STATEMENT__
\if :ERROR
 \echo ATTEMPT :SQLSTATE
 ROLLBACK;
\else
 COMMIT;
 \if :ERROR
 \echo ATTEMPT :SQLSTATE
 \else
 \echo ATTEMPT 00000
 \endif
\endif
'''.replace('__STATEMENT__', statement)
 output, _ = worker.communicate(finish, timeout=5)
 match = re.fullmatch(r'ATTEMPT ([0-9A-Z]{5})', output.strip())
 if worker.returncode != 0 or match is None:
 raise RuntimeError('No confirmed transaction outcome; do not replay blindly')
 return match[1], observed
 finally:
 if worker.poll() is None:
 worker.kill()
 worker.communicate()


def increment(mode):
 observations = []
 for number in range(1, 4):
 state, observed = attempt(mode, number)
 observations.append(observed)
 if state not in {'40001', '40P01'} or number == 3:
 return {'attempts': number, 'state': state, 'reads': observations}
 time.sleep(random.uniform(0, 0.01 * 2 ** (number - 1)))


run('CREATE SCHEMA retry_demo; '
 'CREATE TABLE retry_demo.counter (id integer PRIMARY KEY,n integer); '
 'INSERT INTO retry_demo.counter VALUES (1,0);')
try:
 cases = [
 ('once', {'attempts': 2, 'state': '00000', 'reads': [0, 1]}, 2),
 ('permanent', {'attempts': 1, 'state': '23505', 'reads': [0]}, 0),
 ('always', {'attempts': 3, 'state': '40001', 'reads': [0, 1, 2]}, 3),
 ]
 for mode, expected, expected_value in cases:
 run('UPDATE retry_demo.counter SET n=0 WHERE id=1;')
 result = increment(mode)
 value = int(run('SELECT n FROM retry_demo.counter WHERE id=1;'))
 assert result == expected and value == expected_value, (mode, result, value)
 print(mode, result, 'stored', value)
finally:
 run('DROP SCHEMA retry_demo CASCADE;')

程序使用真实的两条数据库连接。每次尝试都开启可重复读事务，先读计数值，再由应用算出要写入的绝对值。竞争连接可以在读取之后、更新之前提交一次增量，迫使原快照下的更新失败。这种调度刻意检查“重试有没有重新读取和计算”，而不只是看程序有没有再次发送更新语句。

第一种情况只制造一次冲突。预期尝试两次，最终状态成功，两次读取依次为零和一，数据库最终存储二。其中一次增量来自竞争连接，另一次来自应用成功的重试。被拒绝的第一次尝试没有贡献任何提交。如果第二次只是复用原先算好的值，就不能保留两次合法增量的结果，因此最终数据也是判断重试边界的重要证据。

第二种情况制造永久错误：向已有主键再次插入相同标识。预期只尝试一次，状态为 23505，读取零，存储仍为零。分类器应立即停止，而不是把三次机会全部浪费在未改变的无效输入上。此时不能报告应用完成了加一，也不能仅因为客户端没有崩溃就把业务状态改成成功。

第三种情况在每次尝试中都安排竞争者先提交。预期尝试三次后退出，最终仍是 40001，读取依次为零、一、二，存储值为三。这里的三次增量全部属于竞争连接，应用自己的操作一次也没有提交。这是达到预算上限的失败结果，不是“重试终于成功”。断言同时检查控制流程报告与持久化数据，因为单看表里的数字无法知道是哪一方完成了操作。

让错误处理覆盖完整决策

示例从客户端取得结构化错误码，再输出专用结果标记，没有根据本地化错误文字猜测类型。预期语句错误后执行回滚，提交阶段则单独检查。若缺少确认、进程异常退出或传输等待超时，异常会离开重试分类器，不能被随意当作一次可安全重放的并发拒绝。首次读取与进程完成分别设置等待边界。这三个场景没有制造死锁，也没有注入提交确认丢失；工具本身没有实现统一总期限或调用方取消，不能把这些生产要求记为本实验已经覆盖。

真实应用应使用数据库驱动的事务接口和结构化异常接口，而不是直接复制这个进程调度工具。请求总预算还应包含获取连接、全部尝试以及退避时间；调用方取消后要停止继续重放，并记录尝试次数和最终错误。随机退避有助于打散同时重试的请求，却不能修复永久占用、保证公平，或让有限次数必然成功。

对外部可见操作，应使用稳定操作标识和可查询的持久化结果。提交结果不确定时，先核对结果，再决定是否重新发起非幂等动作。不可逆副作用不应直接放进会被多次执行的回调，除非相应的交付协议已经明确处理重复。让一次失败尝试可以正确退出、让重复决策基于新状态、让未知结果得到核实，才构成可靠恢复；循环次数和短暂睡眠只是其中负责安排时间的部分。

来源

PostgreSQL 18 序列化失败处理，重试错误分类和完整事务重算，已核验 2026-09-10。
PostgreSQL 18 事务隔离，实验使用的快照冲突规则，已核验 2026-09-10。
PostgreSQL 18 psql，错误状态变量、条件执行和客户端错误处理，已核验 2026-09-10。

零停机迁移在旧代码运行时就改表结构

Tue, 03 Nov 2026 00:00:00 +0000

零停机迁移是兼容性与可用性目标，不是把语句变短之后自动获得的保证。数据变化时，新旧应用可能同时运行，因此需要一起安排表结构、写入行为、回填、读取切换以及恢复方式。删除信息并不会因为前面采用了增量步骤就变得可逆；是否还能回退，取决于旧程序需要的数据是否仍然存在且正确。

取锁等待、行级冲突、资源消耗和应用假设都重要。只改元数据的操作也可能被别的事务挡住；回填没有持有排他表锁，也可能耗尽磁盘吞吐或复制容量。验收不能只测一条语句有多快，还需要观察并发业务、队列等待与恢复条件。

先扩展，再回填，后收缩

扩展阶段引入旧读写方能够容忍的新表示。先部署兼容写入方，再依赖新数据；回填存量行并验证不变量后，才切换读取。收缩必须等旧二进制、后台任务和回退需求都不再依赖旧结构。增加可空列经常有用，但仍需取锁和兼容性检查，不能把任何增加列操作都宣布为绝对安全。

双写必须定义失败与先后顺序。同一数据库事务中更新两列，可以维持一致性；分开提交则可能只成功一半。仍然只更新旧列的老写入方，会让已经回填的新列再次过时。因此需要先退役这些写入方，或提供经过验证的同步机制，再宣布已经收敛。回滚只有在它所依赖的旧表示仍然准确时才安全，不是打开双写就自动保证不丢数据。

回填应采用可重启的小批次和稳定进度键。需要防止旧快照覆盖并发应用刚写入的新值，例如事务内检查版本号，或使用符合业务不变量的条件更新。仅检查新列为空并非通用答案，它是否足够取决于写入行为。跳过的行和并发变化的行还要复查，写入方收敛之后再次验证。分批缩短单次事务，却可能增加总工作量，更不能替代正确的发布顺序。

锁是其中一道失败边界

PostgreSQL 的 ACCESS EXCLUSIVE 会与普通读写冲突。许多 ALTER TABLE 形式即使不用重写数据，也要获取它。普通 UPDATE 则获取 ROW EXCLUSIVE 和行锁，不会因此把所有其他写入方都全局排除。具体冲突取决于命中的行和并发操作；长事务会一直持有相关锁，直到事务结束，而不是语句返回后就全部释放。

排队中的强锁可能继续延迟后来的冲突请求。应识别实际阻塞关系、事务边界与等待事件，不能仅凭哪个事务最老就认定它是原因。SQLite 的回滚日志与 WAL 模式属于不同引擎契约。旧文中的毫秒和页数对比，在本次审阅中没有建立精确基准证据；它们不能当作 PostgreSQL 预测，也不是本轮测量结果。

在较弱锁下验证

以 PostgreSQL 17 为例，只有当前写入方已经满足条件时，才添加合适的 CHECK ... NOT VALID。这个选项延后检查旧行，却立即约束新的插入和更新。随后 VALIDATE CONSTRAINT 用 SHARE UPDATE EXCLUSIVE 扫描，它允许普通数据读写，但会与部分维护和结构操作冲突。因此验证并非完全不取锁，也不是对所有并发活动都没有影响。

若已经验证的 CHECK 能证明该列不会为空，且没有在同一条命令中删除它，SET NOT NULL 可以跳过扫描。这仍不会免除最终修改所需的更强锁，而设置 NOT NULL 本身也不必然重写整表。PostgreSQL 18 扩展了非空约束能力，所以必须按实际部署的大版本查语法，不能把不同版本的规则混在一起。

坏掉的样子

回填刚完成一次，仍存活的旧写入方又把新表示变旧。切读前要监控不一致计数和写入方版本。收缩涉及破坏性删除时，恢复可能依赖备份恢复或向前修复；应在删除数据之前演练，而不是承诺任何阶段都能简单撤销。只有进度百分比到达一百，还不足以证明线上不变量成立。

普通 CREATE INDEX 在构建期间阻止写入。CREATE INDEX CONCURRENTLY 允许普通数据修改，但需要额外扫描和等待，不能放进事务块，失败后还可能留下无效索引。这样的索引可能继续增加更新开销，甚至继续执行唯一性约束。应检查具体状态，再进行获授权的恢复操作，不能把无效索引一概当作没有任何效果。

迁移兼容性：机制与证据边界。

快速验证

下面保留的是运维检查清单，不是隔离的迁移实验。只应在明确选定的一次性 PostgreSQL 数据库中使用，其中已有自己拥有的 events 表且没有 note 列。先确认连接、search_path、目录可见权限、DDL 权限，以及独立的整条语句超时。第四条命令确实改变表结构，不要直接粘贴到生产数据库。

psql -c "SELECT pid, state, now()-xact_start AS age, left(query,50) FROM pg_stat_activity WHERE xact_start IS NOT NULL ORDER BY xact_start;"
psql -c "SELECT pid, mode, granted, left(relation::regclass::text,40) FROM pg_locks WHERE NOT granted;"
psql -c "SELECT indexrelid::regclass, indisvalid FROM pg_index WHERE NOT indisvalid;"
psql -c "SET lock_timeout='3s'; ALTER TABLE events ADD COLUMN note text;"
psql -c "SELECT conname, convalidated FROM pg_constraint WHERE conrelid='events'::regclass;"

活动查询只列出候选事务，不能证明谁正在阻塞；pg_blocking_pids 才提供阻塞关系。未授予的锁也不是所有持锁者清单。lock_timeout 限制每次取锁等待，不限制执行时间或总体影响。单看 convalidated 也不能知道证明了哪个条件。本轮没有运行这些命令；发布兼容性、并发回填、约束状态转换和恢复，仍需获授权且固定版本的夹具验证。

来源

PostgreSQL：ALTER TABLE，SET NOT NULL、NOT VALID 与 VALIDATE CONSTRAINT，已核验 2026-09-16。
PostgreSQL：CREATE INDEX，并发建索引与失败后留下无效索引的形态，已核验 2026-09-16。
PostgreSQL：显式锁，哪些命令会取 ACCESS EXCLUSIVE 与 SHARE，已核验 2026-09-16。
Martin Fowler：并行变更，扩展/收缩模式的另一个名字，已核验 2026-09-16。
PostgreSQL 17：ALTER TABLE，特定版本的 CHECK 验证与非空状态转换，已核验 2026-10-18。
PostgreSQL 17：客户端默认设置，取锁等待超时与语句时长的区别，已核验 2026-10-18。
PostgreSQL 17：系统信息函数，通过 pg_blocking_pids 查询实际阻塞关系，已核验 2026-10-18。
PostgreSQL 17：事务隔离，并发更新与条件重新检查，已核验 2026-10-18。