数据库 · XB 现场笔记

Postgres 的 jsonb 专为查询而生

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

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

保留文本还是保留结构值

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 的实测结果是：raw 保持原来的空白文本；parsed 显示包含 a=3、b=2 的规范化对象；两种提取表达式都返回 3。直接在 json 上读取嵌套路径，也能得到 Ada。断言检查这些语义，并分别验证数组相等比较会考虑顺序与重复元素；捕获到预期的非法输入错误后，会打印“invalid JSON rejected”提示。如果错误类型变化或无效 JSON 被接受，脚本不会把它默认为成功。

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

来源

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

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

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，数据库文件只存在于脚本自己的临时目录，结束后自动清理，不会访问生产数据库。

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

B 树会在行所在的那一页上就地更新，于是「键随机到达」的写入模式就变成了「页随机写」的模式。LSM 树拒绝这笔交易：它只追加，把重写留到后面成批去做。这套设计里的其他部分——内存表、布隆过滤器、压实策略——全都从这一个拒绝里推出来。

支撑它的测量很容易复现。在同一张 20 万行的 sqlite 表上做同样 20 万次就地更新，配 2 MB 页缓存和一次持久提交：键按顺序到达时耗时 0.17 秒，打乱顺序到达时 2.60 秒——行完全一样、页数完全一样，差了 15.25 倍。多出来的时间花在散落的页重写，以及由此引发的缓存淘汰上。

先缓冲，再刷盘，再合并

写入先进预写日志保证持久性，再进内存表保证速度。内存表满了就作为一段不可变的有序段刷到磁盘；在 RocksDB 里这一段落在 level 0，而它下面的每一层只保存一段有序数据，且尺寸目标按指数增长。于是键层面随机的负载，落到磁盘上就变成了完全顺序的负载，无论应用在做什么，写路径都是一次大块的有序追加。

账单在读取路径上付。一次点查要考虑每一层，所以引擎给每段配了布隆过滤器，用来廉价地回答「不在这里」。在一次 40 万次写入、6 万个不同键的模拟里，2 万次点查平均探了 8.9 个段，但真正去读的只有 0.6 个：布隆过滤器在 177937 次探测里否掉了 166622 次，占 93.6%。查不存在的键时仍然要探 11.0 个段才能返回空——布隆过滤器让「未命中」变便宜，对「命中」则毫无帮助。

压实就是代价

写路径之所以便宜，是因为从来不做就地更新；代价是每个逻辑值都会被写不止一次。同一份模拟里，56000000 字节的逻辑数据变成了 149031040 字节的物理写入，来自 54 次刷盘和 4 次压实——写放大 2.66 倍，而且这还是在刻意放宽了压实预算的情况下。

level 0 是特殊的：它里面那些段直接来自内存表刷盘，键区间可以互相重叠，所以一次点查必须把 L0 的每一段都问一遍。更深的层不是这样——每一层整体是一段有序数据，内部按区间切成多个 SST 文件，查找先二分定位到可能包含该键的那一个文件，再在文件内二分。读放大因此主要被 L0 的段数牵着走，而 L0 的段数正是压实跟不跟得上的直接读数。

RocksDB 把这个旋钮明确写了出来。Level 风格压实把 Ln 里的一个文件与 Ln+1 中所有重叠文件合并，最小化了参与的文件数，因而优化的是空间放大。Universal 风格压实一次合并多个文件与多层，降低了写放大，却抬高了空间放大和读放大。没有任何一组配置能同时压低这三个；你只能选一个，看你这类负载付得起哪一个。

坏掉的样子

第一种失败是压实跟不上写入速率。压实吞吐是一道硬下限：按 64 MiB/s 的写入速率和 2.66 倍的写放大算，后台必须搬动 170 MiB/s 才能原地不动。如果实际只有 145 MiB/s，缺口就是 25.5 MiB/s，每小时堆积 91973 个内存表大小的段，11.4 小时就能把 1 TiB 的盘填满。拿 2000 个 level 0 段实测，一次点查平均要探 775 个段，而不是 8.9 个。先是读变慢，再是盘写满，两个症状指向同一个数字。

第二种失败是墓碑过重的负载。删除不是抹掉，而是写入一个墓碑，它必须活得比它遮住的那个值更久。插入 4 万个键再把它们全部删掉，为 5720000 字节的活跃数据写下了 12160000 字节，并留下 4 万个墓碑占着 5600000 字节的已删负载——光是这些已经不存在的行，就带来相当于活跃数据 0.98 倍的空间放大。查询这些已删键时，仍然要探段才能确认它不在。只有某次压实真的碰到那个墓碑，空间才会回来；所以删得和写得一样快的负载，两头的账都得付。

快速验证

先量出你想避开的那笔 B 树开销，再读压实的计数器：

sqlite3 kv.db "PRAGMA cache_size=-2000; PRAGMA synchronous=FULL; PRAGMA journal_mode=WAL;"
sqlite3 kv.db "SELECT count(*) FROM kv; PRAGMA page_count;"
ldb --db=./db stats | sed -n '/Compaction Stats/,/^$/p'
ldb --db=./db stats | grep -i stall
python3 -c "import rocksdb; d=rocksdb.DB('./db'); print(d.get_property(b'rocksdb.num-files-at-level0'))"

把同一批键插两遍，一遍有序一遍打乱，前两行就给出基线差距：行数相同、页数相同，墙上时间差很远。Compaction Stats 区块按层报出 W-Amp 与 R-Amp——写放大随数据量增长而上升，说明 fanout 设小了；读放大上升，说明压实已经落后。stall 计数只要大于零就是欠账信号，而 level 0 的文件数长期贴着压实触发阈值，说明后台只是勉强跟得上。

来源

RocksDB wiki：RocksDB 概览，内存表、层结构与写/读/空间放大的取舍，已核验 2026-09-16。
RocksDB wiki：分层压实，level 0 刷盘、按指数增长的层尺寸目标与逐层查找成本，已核验 2026-09-16。

检查点为恢复建立起点

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

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

坏掉的样子

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

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

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

快速验证

把下面内容保存为 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

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

坏掉的样子

在 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-09-12。
Psycopg 预备语句，阈值、显式预备和会话生命周期，已核验 2026-09-12。
PostgreSQL 18 PREPARE，定制计划、通用计划和自动选择，已核验 2026-09-10。

部分索引只覆盖有用行

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，可能与当前持有人冲突。失败后旧记录应该仍保持无效，并向调用方报告冲突，不能悄悄替换已有有效预订。批量导入与状态迁移也必须接受同样检查，不能因为它们是运维任务就绕开当前有效唯一性；这样才能让不同写入入口共享同一规则。

快速验证

保存为 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 通过。异常块只捕获预期的唯一性违反；如果本应失败的操作意外成功，后面的不同异常会让脚本失败。最后回滚移除夹具。实验验证子集成员资格与唯一性转换，不证明支付原子性、分布式库存一致性，也没有测量巨大历史表上的性能收益。

来源

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

覆盖索引不必回表

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

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

覆盖实际返回的列

按 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 用统计信息和成本模型比较扫描、连接、排序等操作，因此选定的计划始终是建立在当前假设上的预测。诊断预测为何偏离实际，需要找出失效的具体假设，而不是把顺序扫描或嵌套循环当成天生有问题的节点。计划好不好，要放在完整查询的输入和输出要求中判断。

成本描述的是一个模型

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 树，而不是把那些页按顺序读一遍。

优化器给两条路线都算了账，所以真正有意思的问题不是"原则上谁更快"，而是交叉点落在哪里。表小并不等于工作量小，你在 1000 行时看到的计划，也不是 1000 万行时该期待的计划。

真正的货币是页，不是行

顺序扫描按物理顺序读表的页，一页能拿到很多行。PostgreSQL 用 seq_page_cost（默认 1.0）对 random_page_cost（默认 4.0）来给这件事定价：非顺序取到的页按顺序页的四倍计价，而把 random_page_cost 相对 seq_page_cost 调低，正是让优化器开始偏好索引扫描的那个开关。文档也指出，如果整个数据库都能装进缓存，把两者设成相等是合理的。

机械盘上一次随机寻道以毫秒计，而顺序读完一整条磁道几乎免费；NVMe 把这个差距压到微秒级，但页数本身并没有变，所以代价模型里「页数」这一项始终在。既然货币是页，行数就是一个很差的规模代理。同样是 1000 行的两张表：4 字节负载的那张是 12 页，4000 字节负载的那张是 1010 页。在 sqlite 3.53 上配 2 MB 页缓存，命中约 90% 行的宽谓词查询在窄表上 0.02 ms 跑完，在宽表上要 1.30 ms——行数完全一样，差了 65 倍。只有其中一张算"小"。

索引从哪里开始不划算

把两条访问路径分别钉死，交叉点就露出来了。表是 events(id, tenant, payload)，1000 个不同 tenant，tenant 上有索引，谓词命中约 90% 的行：

1000 行、21 页：扫描 0.04 ms，索引 0.05 ms，打平。这个规模上索引什么也没买到，而每次写入都还要维护它。
50000 行、767 页：扫描 1.79 ms，索引 6.61 ms，扫描赢 3.7 倍。
1000000 行、15474 页（63 MB）：扫描 44.37 ms，索引 531.18 ms，扫描赢 12 倍；采七次样本，比值最低也有 11.3 倍。

还有一层细节：如果查询只需要索引里已经有的列，引擎就完全不必碰表，这时候索引在宽谓词上也依然便宜。上面的测试刻意用 sum(length(payload)) 而不是 count(*)，就是为了把数据行拉进来，让两条路径真正可比。覆盖索引会把整个交叉点挪走，代价是索引本身变大、每次写入更贵。

同一个索引在同样这张百万行表上，遇到选择性谓词却是 29 倍的优势：tenant = 7 只覆盖约 0.1% 的行，走索引 0.61 ms，扫描 17.88 ms。索引本身不坏，它只是对这个谓词坏。决定权在选择性手上，而且表越大，它决定得越狠。

让优化器做主，但把它的输入喂诚实

三种规模上，sqlite 都为宽谓词选了扫描，为选择性谓词选了索引。这是正确的默认值；当计划看起来不对时，该动的杠杆是统计信息，不是 hint。把强制索引当成诊断证据而不是长期策略：先钉死两条路径各量一次，再回头去修数据或统计。

统计信息会过期，计划跟着一起过期。把百万行的表 ANALYZE 一遍，然后把所有行都改成 tenant = 5 而不再分析：sqlite_stat1 仍然写着每个键 1000 行，于是优化器继续为一个命中全表 100% 的谓词选 SEARCH ... USING INDEX。再跑一次 ANALYZE，统计变成每个键 1000000 行，计划当场翻成 SCAN。这里错误计划只贵了 1.2 倍，原因是 sqlite 的表 b 树按 rowid 排序，索引游走取页时仍接近物理顺序；在 PostgreSQL 里，每一次索引命中都是一次按 random_page_cost 计价的独立堆取页，同样的错误要贵得多。

坏掉的样子

最经典的是统计信息陈旧导致的计划翻转。夜间任务灌进来一个逐渐占满全表的 tenant，直方图还描述着上周；原本走索引查找的看板查询，现在变成透过索引读掉五分之一张表。没有任何报错。延迟就那么抬了一级，而且恰好抬在没人盯着的那些查询上。

第二种失败与形状无关，只与规模有关。21 页上花 0.03 ms 的那次扫描，在 767 页上是 1.88 ms，在 15474 页上是 41.34 ms，因为代价对页数是线性的。今天还行的表，长一年之后就变成付不起的全表扫描。解法不是 hint，而是让优化器真正会选的那个索引，或者一条返回更少行的查询。

快速验证

先确认这张表在页数上确实小，再看优化器是否和现实一致：

sqlite3 events.db "PRAGMA page_count; PRAGMA page_size;"
sqlite3 events.db "EXPLAIN QUERY PLAN SELECT sum(length(payload)) FROM events WHERE tenant < 900;"
sqlite3 events.db "EXPLAIN QUERY PLAN SELECT sum(length(payload)) FROM events NOT INDEXED WHERE tenant < 900;"
sqlite3 events.db "ANALYZE; SELECT stat FROM sqlite_stat1 WHERE idx='events_tenant';"
printf '.timer on\nSELECT sum(length(payload)) FROM events NOT INDEXED WHERE tenant < 900;\n' | sqlite3 events.db

第一条给出页数，那才是关键数字。中间两条对宽谓词应该报出同一条路径：如果优化器说 SEARCH ... USING INDEX，而被钉死的 SCAN 明显更快，嫌疑就在统计信息上。sqlite_stat1 给出每个键的平均行数——当它仍旧写着 1000、而实际已有一个键占满全表时，重跑 ANALYZE 再看一次计划。

来源

PostgreSQL：优化器代价常量，seq_page_cost 与 random_page_cost，已核验 2026-09-16。
PostgreSQL：使用 EXPLAIN，如何读计划与行数估计，已核验 2026-09-16。
SQLite：EXPLAIN QUERY PLAN，扫描与查找步骤如何呈现，已核验 2026-09-16。

组合索引贴合多列的查询

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 物理热备库，它在正常恢复模式下可以读取，但不能接受普通业务写入。

坏掉的样子

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

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

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

快速验证

在 Linux 环境中以非超级操作系统账户运行脚本，并准备 PostgreSQL 18 服务端和客户端程序。本次使用 PostgreSQL 18.6。脚本建立私有主备集群，通过 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 使用随机位；第七版在开头放置毫秒时间戳，目标之一是支持时间排序，因此不能把它的前缀说成随机位，也不能把其中的时间当作数据库提交时间。降低可猜测性与确认谁有权读取，是两项不同职责。

快速验证

准备一个可丢弃的 PostgreSQL 18 数据库，打开两个管理员 psql 会话，分别称为甲和乙。下文提取 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。

外键让引用保持诚实

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

坏掉的样子

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

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

快速验证

把下面内容保存为 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 逐节点画出规划器选择的路径，让你针对真正耗时的步骤去修，而不是凭猜测。

把计划当作路线来读

EXPLAIN 输出是一棵树:根节点是最终答案,真正的活是子节点干的。每个节点有操作名、行数估算和成本,真正值得盯的是离群点——行数估算远大于实际返回数的大扫描,或者与实际执行差距巨大的估算。读树的顺序很关键:要顺着成本最大的节点找,而不是盯着模式里第一个出现的那层。把 EXPLAIN 和 EXPLAIN ANALYZE 并排看,能直接看到规划器「猜的」和真实「跑出来」的差距,慢查询多半就藏在那里。

统计信息决定路线

有索引只是「有了选项」,不等于「会走到那里」。规划器是根据观测到的统计量——行数、可空性、列值分布——来选路线,所以一次 autovacuum、一次大量导入、一次缓存命中率变化,都可能让同一条 SQL 改道。卡在热点路径上的查询,应该在数据画像变化时重新分析,而不是只在建的时候看一次。统计信息过期时,一个 ANALYZE 有时比一顿索引微调改写更能改变计划。把计划当成需要拿真实 EXPLAIN 数据反复复核的证据,而不是背下来就完事的快照。

确认路线真的变了

把计划塞进改动循环:先留下基线 EXPLAIN ANALYZE,加索引或用改写后的 SQL,确认路线真的移动了再宣布成功。如果目标节点还是那个大的扫描、成本结构没变,那这改动无论听起来多顺,都只是表面功夫。经验再丰富,也不如前后两份计划来得实在;真实的执行耗时、取行数也要一并记录。新计划生效后,把前后对比放进合入请求里,让这次收益可追溯、可复现。

坏掉的样子

统计信息过期会让规划器走错路。一次大批量导入之后，如果很久没有跑过 ANALYZE，规划器可能还以为表里只有几千行，而实际已经有几百万行，于是继续选择只在小数据量下才划算的索引或嵌套循环。EXPLAIN ANALYZE 会露出马脚：估算行数与实际行数差出数量级。先跑 ANALYZE 再对比这两个数字，确认路线是基于新鲜画像选出来的，而不是急着加索引。数据分布变化之后不复核计划，再合理的索引也可能建在错误的假设上。

预编译语句会把某一次参数的计划复用到所有参数上。围绕高区分度的首个参数缓存下来的计划，对它很快，对匹配半张表的值却很慢；而你用 EXPLAIN 拿字面量测出的计划，往往并不是线上真正绑定的那个值。排查时要把区分度最高和最低的两个极端值都测一遍，并确认到底命中了定制计划还是通用计划，再下结论。只测一个最顺的值，就等于只看了一半的路线图。

隐式转换会悄悄让索引退休。拿 varchar 列直接和数字比较、排序规则不一致，或者在列上套 LOWER、日期截断，规划器只能全表扫描再过滤，索引明明存在却用不上。症状很固定：Seq Scan 上被过滤掉的行数远大于最终返回行数。修法是把调用处的类型改对，或者补一个匹配表达式的函数索引，让写法和索引站在同一边。类型不对时加再多索引，也只是给用不上的路线添摆设。

只看 cost 是最后一个陷阱。cost 是无量纲的规划估算，不是执行耗时；估算最便宜的计划，实际可能打出天文数字的共享缓冲命中，或者把排序溢出到临时文件。务必用 EXPLAIN (ANALYZE, BUFFERS) 确认，把实际耗时、buffers、被过滤掉的行数和 cost 并排读，几个数字一致向好，才能说这条路线真的健康。脱离 buffers 谈 cost，和脱离实际行数谈估算一样，都是在看路线的广告而不是路况。

快速验证

把下面程序保存到临时工作目录的 plan_route_check.py，运行 python3 plan_route_check.py。它只用标准库模拟两条候选路径——顺序扫描与索引扫描：先按过期的行数估算各自成本，让规划器选出路线，再用实际行数重新打分。程序会打印估算成本与真实成本、估算偏差和统计信息过期告警，并断言告警一定触发：

#!/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%——统计信息已过期，请重新 ANALYZE。")
 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。这组数字是教学用的玩具模型，不是真实优化器：页面成本都是常量，且只有两条路径竞争。它训练的是关键习惯——先记录估算，再拿实际行数对质——带着这个习惯去读生产环境的计划，就不容易被漂亮的 cost 骗过。该实验不连接任何数据库，也无需安装依赖；发布前仍需在真实链路上用 EXPLAIN (ANALYZE, BUFFERS) 复核热点查询，确认路线真的搬动了。

来源

PostgreSQL：EXPLAIN，生成计划，已核验 2027-05-19。
PostgreSQL：使用 EXPLAIN，解读输出，已核验 2027-05-19。
PostgreSQL：规划器与优化器，路线如何被选定，已核验 2027-05-19。
MySQL：EXPLAIN 语句，计划格式与输出列，已核验 2027-05-19。

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

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

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

坏掉的样子

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

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

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

快速验证

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

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,)]
 print('IN needs separate values; bound column is a literal; LIMIT/OFFSET bind')
db.close()

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

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

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

单个参数中的 1,3 没有匹配任何编号；两个占位符分别绑定两个整数，才返回编号一和三。后一个查询返回字面文本 name，说明值占位符不能用来选择某列。最后，数量和偏移量都采用数字绑定，返回编号二。分页不需要把数字先转换为字符串再拼进 SQL，业务允许的范围与 SQL 传参方式应分别处理。

检查完整数据路径

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

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

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

来源

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 提供这个边界，但应用仍须把正确的语句放进去。原子执行不会自动发现漏掉的入账，也不会替业务补出一个没有编写的校验。事务保护的是被明确纳入其中的工作，而不是开发者脑中尚未落实的意图。

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

普通 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，证明即使客户端继续发送命令，服务器中的事务也已经处于失败状态。这个阶段看不到正常读取结果，不能误以为失败只影响那一条插入。

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

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

让恢复遵守同一份契约

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

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

来源

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 时，再从池取得替代连接。这个替代品可能是另一条现成空闲连接，不一定刚刚新建。如果失效时已有事务，必须先结束该事务才能重连；重连也不是自动恢复一个可能已经产生效果的事务，不能把连接生命周期管理当成业务重试保证。

快速验证

在 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 锁，读写请求全部排在部署后面。表越大，迁移看起来越像卡死，直到语句超时或值班同学手动终止，留下一个需要手工修复的半成品状态。而 down 迁移并不能撤销数据丢失：删掉邮箱列再加回来，得到的是空列，而不是被删掉的地址。破坏性步骤应当拆成独立的后续迁移，上线前先备份，优先使用扩张再收缩的顺序，先加新结构，再回填数据，最后删除旧结构，让每一次发布都平淡无奇。换句话说，只要迁移涉及删数据，就默认它回不来。

另外两类经典故障是并发双跑和篡改历史。如果两个发布副本在没有任何锁的情况下同时执行迁移，它们可能重复应用同一版本，也可能把版本顺序搅乱。生产级的 runner 因此只允许单个执行者，或者借助 PostgreSQL 咨询锁之类的机制加锁，而 golang-migrate 在失败后会把库标记为 dirty，而不是假装一切正常。重写已经被应用过的迁移，或者合并了两个各自新增版本 7 的分支，都会让历史分叉：校验和对不上，环境之间互相矛盾，唯一安全的修复是再写一条新的前向迁移，而不是改写旧文件。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 -> checksum.

def checksum(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] != checksum(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] = checksum(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。

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

来源

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

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

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

一条语句就重写完繁忙大表的迁移，既耗时长又全程加锁。把它换成一系列小而向后兼容的改动，同一份表结构照样能往前推，而且不需要停机窗口——原因不是技巧，而是每一步都能单独部署、单独回退。

真正被管理的东西是一把锁。每一次结构变更都会取锁；问题只在于锁被拿多久，而答案取决于这条语句要碰多少数据。

先扩展，再回填，后收缩

三个阶段：扩展先加上新列，同时旧结构继续可用；回填负责把数据灌进去，而且必须分批；收缩只在没有任何代码再读旧结构之后，才把它请出去。

夹在扩展和回填之间的是双写阶段：应用会同时写新旧两列，这样回退不丢任何东西，等新列可信了再把读切过去。

旧代码还需要旧结构，于是顺序规则也就定了：加一个可空列是安全的，删列不安全，改名要拆成两步，NOT NULL 永远排在回填之后。在一张 50 万行的 sqlite 表上，ADD COLUMN note TEXT 耗时 2.0 ms，页数仍停在 13926——这是一次只改元数据的编辑。把它改成 NOT NULL 则必须真的重写：115.4 ms，页数从 13926 变成 28532。同一个结构变更，两种代价，区别只在于引擎要不要碰每一行。

分批比阶段顺序更重要。50 万行放在一个事务里回填，写锁被持有 671.2 ms；同样这些行按每批 2 万切分，共 25 个事务，锁持有时间中位数 7.3 ms、p90 是 7.8 ms。总工作量完全一样——不同的只有最长的那一次持锁，而那恰好就是应用真正感受到的数字。

锁才是全部问题

PostgreSQL 的 ACCESS EXCLUSIVE 与所有其他锁模式都冲突，包括一条裸 SELECT 取的 ACCESS SHARE。TRUNCATE、VACUUM FULL、不带 CONCURRENTLY 的 REFRESH MATERIALIZED VIEW，以及很多 ALTER TABLE 形式都会取它。读者和写者一起等。

迁移本身也可能被挡住，一旦被挡住，它就变成了挡别人的那一方。在回滚日志模式下，另一会话开着读事务时执行 ALTER TABLE，会为等它结束而卡住 1512 ms，这期间应用有 4 次写入失败；同样的迁移在 WAL 模式下 0.3 ms 就完成，零失败。教训不是关于日志模式的：一个忘了提交的 BEGIN、一条 idle-in-transaction 的连接，就能把 3 ms 的结构编辑变成 1.5 秒的中断，并且让所有人排在它后面。

校验放在锁外，强制放在锁内

SET NOT NULL 是文档里把这层拆分写得最清楚的一例：它通常会扫描整张表来证明没有 NULL，除非已经存在一个有效的 CHECK 约束能证明这一点，或者该约束是以 NOT VALID 加上的。ADD CONSTRAINT ... NOT VALID 只登记约束、不检查存量行，VALIDATE CONSTRAINT 之后再用更弱的锁去做那次扫描。

这正是该有的分工。夹具里对 50 万行的校验扫描耗时 16.3 ms，完全不需要写锁——期间应用写入零失败；而真正重写表的强制步骤要 210.4 ms。贵的那部分是扫描，而扫描恰好是可以在不挡任何人的前提下做完的那部分。

坏掉的样子

第一种失败是放在一个事务里的回填。它既锁表又膨胀：一条覆盖大表的 UPDATE 在整个执行期间握着写锁，在 PostgreSQL 里还会为每一行被碰过的数据写一个新版本，之后都得靠 vacuum 收回去。实测形态就是 671 ms 的独占访问对 p90 的 7.8 ms，而影响范围是应用里的每一次写入——只要连接池超时比这把锁短，它们就会在同一瞬间集体失败。

第二种失败是迁移持锁久到触发了应用自己的超时。普通 CREATE INDEX 取的是 SHARE，挡写不挡读，而且整个构建期间都握着；夹具里三次构建在 50 万行上分别持有写锁 67、83、69 ms，而生产表比这大得多。CREATE INDEX CONCURRENTLY 就是为此存在的，代价也不小：它取 SHARE UPDATE EXCLUSIVE，要扫两遍表，必须等待任何可能修改该表的事务结束，不能放在事务块里，而且一旦失败会留下一个无效索引——查询会忽略它，写入却仍要替它付账。

快速验证

先找出锁的持有者，再让 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;"

第一条点出你的迁移将要排在其后的那个事务：xact_start 非空且 age 很大就是元凶。第二条显示正在等锁的迁移，如果有读者排在它后面，你就找到了影响范围。第三条抓的是失败的 CONCURRENTLY 留下的无效索引。第四条是你应该对每一条 DDL 都采用的跑法——lock_timeout 把「堵住所有人四十秒」换成「快速失败然后重试」。最后一条给出 convalidated，用来确认那个 CHECK 约束确实已经被验证过，然后才敢靠它去支撑 SET NOT NULL。

来源

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。

数据库 · XB 现场笔记

Postgres 的 jsonb 专为查询而生

保留文本还是保留结构值

两种类型都支持路径提取

坏掉的样子

快速验证

来源

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

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

坏掉的样子

快速验证

来源

LSM 树吞下随机写入

先缓冲，再刷盘，再合并

压实就是代价

坏掉的样子

快速验证

来源

检查点为恢复建立起点

坏掉的样子

快速验证

诊断尚未完成的工作

来源

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

坏掉的样子

快速验证

在真实部署中观察复用

延伸阅读

来源

部分索引只覆盖有用行

成员资格随谓词变化

唯一性可以只针对子集

查询也要表达同一边界

坏掉的样子

快速验证

来源

覆盖索引不必回表

覆盖实际返回的列

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

坏掉的样子

快速验证

来源

查询优化器在成本上押注

成本描述的是一个模型

坏掉的样子

快速验证

根据偏差选择下一次实验

来源

小表上全表扫描反而赢

真正的货币是页，不是行

索引从哪里开始不划算

让优化器做主，但把它的输入喂诚实

坏掉的样子

快速验证

来源

组合索引贴合多列的查询

排序的是键，不是 SQL 条件

后面的键仍可能有用

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

坏掉的样子

快速验证

来源

只读副本服务查询需求

坏掉的样子

快速验证

明确路由所承诺的结果

来源

顺序标识会透露分配规律

坏掉的样子

快速验证

分开选择标识与权限方案

来源

外键让引用保持诚实

把关系写准确

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

坏掉的样子

快速验证

来源

EXPLAIN 计划揭示查询路径

把计划当作路线来读