40 最后再考虑分片

我们为本章搭建了一个小型分片集群。同样是连接 projects 和 users，一种写法耗时约 10 毫秒，另一种约 950 毫秒。行相同，机器相同，结果也相同，区别只在于 on 子句里多了一项等式：u.account_id = p.account_id。有了它，每个分片在本地连接自己的行；没有它，集群就得先通过网络重新分配两张表的数据，而且默认会拒绝执行。

分片就是这样。每个查询，要么靠分片键留在本地，要么付出网络开销。选定分片键的那一天，你就决定了它会走哪条路。

我们认为，多数团队分片过早，而在分片之前就为它做好设计的团队又太少。从第一天起就为分片做好设计，然后能等多久就等多久。等到那一天，工具的重要性远不及分片键。

分片让一切成倍增加

分片把一个逻辑数据库拆到多个独立的主库上。分片（shard）是行的一个子集；分片键（shard key，也称分布列）决定一行落在哪个分片上。本章用的是 account_id，前面有一个路由器，知道每个账户在哪。

除按功能拆分数据库以外，这是扩展阶梯中唯一能抬高写入量和数据总量上限的一阶。代价是：PostgreSQL 原本在一台服务器内替你处理的所有事情，现在都被一道边界切开了：

• 查询不指定一个分片键值，就会发到所有分片，再合并结果；跨分片连接则要通过网络传送行。
• 跨分片的事务需要两阶段提交（two-phase commit）来保持原子性。
• 约束只管一个分片：(account_id, email) 可以唯一，单独的 email 却不行。
• 迁移与运维要做 N 遍：N 套副本、备份、清理积压，以及可能在凌晨 3 点发来告警的地方。

这都不是永远不分片的理由，而是提醒你：先确认其他选择更糟。

一个主库再也扛不住写入或装不下数据时，才分片

即便用了你愿意运维的最大机器，以下三个信号仍说明，一个主库已经扛不住你的写入，或装不下你的数据：

• 写入吞吐量碰顶：即使调优了WAL 和检查点，也做了批处理，写入仍让主库饱和。这里说的是写入，不是读取。
• 从运维角度看，数据已经超出单机容量：恢复时间超过恢复时间目标，清理永远追不上。
• 硬性要求必须隔离租户：数据驻留要求，或合同约定的专用硬件。这是应当提前分片的唯一情形。

以下都不是信号：“我们以后可能会很大”、慢查询、连接数、读取负载。先试成本更低的几级阶梯，包括经常被低估的那一级：按功能拆分。把 events 和写入它的程序迁到独立的数据库，两边仍然各自像一个 PostgreSQL 那样运作。

分片键就是整个设计的核心

选择分片键时，要让负载最高的查询，以及不能拆开的事务，都留在同一个分片上。好的分片键几乎出现在每个高频查询的过滤条件里，被一起连接或写入的行共用，而且取值众多、分布均匀。

对于多租户 SaaS，这就是租户 ID：应用一次服务一个账户，同一账户的行会相互连接，却从不与其他账户的行连接。若把 events 按 id 分片，每个“我这个账户的事件”查询都会访问所有分片；若按 created_at 分片，今天的所有写入都会落到同一个分片。跨租户报表则变成扇出（fan-out）查询：只要不常做，就没问题。

**哈希分散的是租户，不是负载。**一个客户的 CI 系统新增 400,000 个事件，就把它所在的分片从 13 MB 撑到了 61 MB，而哈希到这里的其他账户也共用这个分片。大租户需要独立分片，所以迁移单个租户必须成为日常操作。

共置（colocation）让连接留在本地。把 users、projects 和 events 用相同的方式按 account_id 分片，账户 42 的行就会放在一起，在本地连接——前提是连接条件包含分片键。这就是 10 ms 与 950 ms 的差别。每个租户都要读取的小表，则作为参考表（reference table）复制到每个分片上。

 shardid | nodename | size
---------+----------+-------
  102147 | citus-w1 | 61 MB
  102166 | citus-w2 | 14 MB
  102169 | citus-w1 | 13 MB

prove "account 7's shard is now the largest, over 3 times the median events shard" \
  holds citus-coord "with s as (select shardid, shard_size from citus_shards where table_name = 'events'::regclass),
    seven as (select shardid from pg_dist_shard where logicalrelid = 'events'::regclass and hashint8(7) between shardminvalue::int and shardmaxvalue::int)
    select (select shardid from s order by shard_size desc limit 1) = (select shardid from seven)
       and (select max(shard_size) from s) > 3 * (select percentile_cont(0.5) within group (order by shard_size) from s)"

从第一天就留好余地

不实际分片，也能让将来的分片成本降低。同样的习惯还能让行级安全更简单，让跨租户的 bug 更难出现。每张属于租户的表都加上 account_id，每个主键、唯一约束、外键，以及每个查询的 where 子句都带上它（让租户无处不在、让跨租户引用不可能发生）。在单机上，这些复合键防止跨租户引用；分片后，只有这种键才能得到强制约束。

已经用了单列键？先在单机上逐步迁移：复合唯一约束、复合外键（先 not valid，再 validate），最后改查询。每一步本身都值得做。

按租户路由，绝不按 ID 路由

每个分片都有自己的序列，因此两个分片都会分配出 id = 1。如果 ID 要在数据库之外使用，就采用分片位（shard bits，用 bigint 的高位标识分片，类似 Snowflake）或 UUIDv7（无需协调，PostgreSQL 18 中有 uuidv7()）；ID 格式概览比较了其他选择。

用 16 位标识分片，每个分片就能分配 281 万亿个 ID。但 ID 说明的是一行创建时所在的位置，不是租户迁移后的所在位置：按租户路由，绝不按 ID 路由。

-- on citus-coord
   id    | node_bits
---------+-----------
 2000001 |         0

-- on citus-w1
       id        | node_bits
-----------------+-----------
 281474976710657 |         1

-- on citus-w2
       id        | node_bits
-----------------+-----------
 562949953421313 |         2

id_sql="insert into events (account_id, project_id, kind)
  select 42, id, 'login' from projects where account_id = 42 order by id limit 1
  returning id >> 48"
c_bits=$(coord -c "$id_sql"); w1_bits=$(on citus-w1 -c "$id_sql"); w2_bits=$(on citus-w2 -c "$id_sql")
prove "the same insert accepted on every node, ids carry the node's group in the top 16 bits" \
  [ "$c_bits $w1_bits $w2_bits" = "0 1 2" ]

跨分片查询会扇出

查询不带分片键，就会发往每个分片，并由某个组件合并结果：求和可以直接相加，平均值需要总和与计数，limit 10 需要每个分片的前 10 条，去重计数需要拿到各个值。延迟取决于最慢的分片；32 个分片上每秒 100 次这样的查询，就是每秒 3,200 个任务。增加分片后，租户内查询给每个节点带来的开销会下降，扇出查询却不会。把它限于后台作业和内部工具。

跨分片事务需要两阶段提交

写入也有同样的边界。向两个分片写入，就是两个事务；如果其中一个失败，转账就只做了一半。两阶段提交会先让所有分片执行 prepare transaction，然后才允许提交。直到第二阶段，它都在各处持有锁；如果协调节点在两个阶段之间宕机，留下的预备事务（prepared transaction）会继续持锁，阻碍清理。普通 PostgreSQL 默认关闭这项功能（max_prepared_transactions = 0），postgres_fdw 也不使用它。最好的跨分片事务，是分片键让你根本不必执行的那一种。

out=$(coord -c "set citus.log_remote_commands = on" -c "set client_min_messages = notice" \
  -c "update events set kind = kind where kind = 'alert'" 2>&1)
prove "an update with no tenant filter commits with two-phase commit on both workers" \
  bash -c 'grep -q "PREPARE TRANSACTION" <<<"$1" && grep -q "COMMIT PREPARED" <<<"$1" && grep -q "citus-w1" <<<"$1" && grep -q "citus-w2" <<<"$1"' _ "$out"

重新分片就是迁移租户

迟早会有一个租户需要独占一台机器。带行过滤的逻辑复制（PostgreSQL 15+，参见它的用途）会复制一个租户的行，然后持续传送变更。

有了租户目录——记录每个租户属于哪个分片的表——迁移只需四步：发布 where (account_id = 42) 所匹配的数据并订阅；延迟接近零时，把租户标为只读；延迟归零时，把目录指向目标；分批清理源端。只读窗口持续几秒钟。逻辑复制不复制序列，因此目标端生成的 ID 不能与迁入的 ID 冲突。这也是采用分片位或 UUIDv7 的又一个理由。

Citus（在 PostgreSQL 内部分片的扩展，下文介绍）的分片迁移，以及 PgDog（分片代理，下文介绍）的重新分片，都使用同一个协议。这很好地说明，选它作为基础机制是合适的。

-- on the source
create publication move_acct_42 for table events where (account_id = 42);

-- on the destination, which already has the table
create subscription move_acct_42
  connection 'host=citus-w1 dbname=fdwshard user=postgres'
  publication move_acct_42;

prove "the subscription copies account 42's 500 existing rows, and only those" \
  wait_for pg dest "select count(*) = 500 and min(account_id) = 42 and max(account_id) = 42 from events"

PostgreSQL 负载有七种分片方式

七种方式的区别在于：路由在哪里，谁来合并跨分片结果，以及保留多少 PostgreSQL 功能。本节关于其他项目的每项事实，都取自截至 2026 年 10 月它们自己的文档；选定之前请再核查。我们运行了 postgres_fdw 和 Citus，因为两者都是开源软件，能在任何地方运行：便于演示，并非默认答案。

应用路由器把每个难题都交给你

你运行普通主库，由代码中的路由器查询每个租户所在的分片。托管或自建的 PostgreSQL 都行，但每个难题——合并、迁移、原子性——都归你解决。

create table tenant_shards (
  account_id  bigint primary key,
  shard       text   not null,
  state       text   not null default 'active'
              check (state in ('active', 'read_only', 'moving'))
);

// Router sends every query for an account to the database that owns it.
type Router struct {
	mu        sync.RWMutex
	directory map[int64]string   // account_id -> shard, loaded from tenant_shards
	shards    map[string]*sql.DB // shard name -> connection pool
}

func (r *Router) For(accountID int64) (*sql.DB, error) {
	r.mu.RLock()
	defer r.mu.RUnlock()
	name, ok := r.directory[accountID]
	if !ok {
		return nil, fmt.Errorf("account %d has no shard", accountID)
	}
	return r.shards[name], nil
}

postgres_fdw 是一块积木

把哈希分区表的每个分区都设为另一台服务器上的外部表，父表就能把行路由到不同机器。租户内查询会把过滤条件下推到一台服务器；跨租户聚合则会把所有行拉回来。没有两阶段提交、约束或再均衡：它是一套零件，不是一辆整车。

create server shard1 foreign data wrapper postgres_fdw
  options (host 'citus-w1', dbname 'fdwshard', async_capable 'true');
-- shard2 likewise, plus user mappings

create table events (
  account_id bigint not null,
  id         bigint not null,
  kind       text   not null
) partition by hash (account_id);
create foreign table events_s1 partition of events
  for values with (modulus 2, remainder 0)
  server shard1 options (table_name 'events');
-- events_s2: remainder 1, server shard2

prove "50,000 rows for 100 accounts route 26,000 to one server and 24,000 to the other" \
  [ "$(on citus-w1 -d fdwshard -c 'select count(*) from events') $(on citus-w2 -d fdwshard -c 'select count(*) from events')" = "26000 24000" ]
plan=$(on pg -d router -c "set enable_partitionwise_aggregate = on" -c "explain (verbose, costs off) select kind, count(*) from events group by kind")
prove "grouping by anything else pulls the rows back and counts locally" \
  bash -c 'grep -qF "Remote SQL: SELECT kind FROM public.events" <<<"$1" && ! grep -q "Relations: Aggregate on" <<<"$1"' _ "$plan"

Citus 在 PostgreSQL 内部路由与合并

Citus 是一个开源扩展（AGPL-3.0），把一组 PostgreSQL 服务器组成一个分布式数据库：你连接协调节点，工作节点保存分片，路由、合并、两阶段提交、DDL 和再均衡都由它代劳。

最新版本是 14.2.0（14.0 加入了 PostgreSQL 18 支持）。我们的集群使用 Citus 14.2.0，运行在镜像自带的 PostgreSQL 18.4 上；两个工作节点，按 account_id 划分的 32 个共置分片。租户内查询是在一个工作节点上执行的一个任务，跨租户查询是由协调节点合并的 32 个任务，而本章开头那个不带 account_id 的连接则被拒绝执行。

约束必须包含分布列

分片只能检查自己的行，因此 Citus 会拒绝任何不带分布列的主键、唯一约束或排他约束：原来的 primary key (id) 无法按 account_id 分布，unique (email) 也不行。外键必须通过分布列连接共置的表，或指向参考表。从第一天就采用的复合键全部得到了接受。

select create_reference_table('accounts');
select create_distributed_table('users',    'account_id');
select create_distributed_table('projects', 'account_id',
                                colocate_with => 'users');
select create_distributed_table('events',   'account_id',
                                colocate_with => 'users');

ERROR:  cannot create constraint on "t1"
DETAIL:  Distributed relations cannot have UNIQUE, EXCLUDE, or PRIMARY KEY
constraints that do not include the partition column (with an equality
operator if EXCLUDE).

 Custom Scan (Citus Adaptive) (actual rows=5.00 loops=1)
   Task Count: 1
   Tuple data received from nodes: 68 bytes
   ->  Task
         Node: host=citus-w2 port=5432 dbname=postgres
         ->  GroupAggregate (actual rows=5.00 loops=1)
               Buffers: shared hit=1092 read=10
               ...
                     ->  Bitmap Heap Scan on events_102166 events
 Execution Time: 1.747 ms

prove "account 42's users, projects, and events sit on the same worker" \
  holds citus-coord "select count(distinct nodename) = 1 from citus_shards s join pg_dist_shard d using (shardid) where s.table_name in ('users'::regclass, 'projects'::regclass, 'events'::regclass) and hashint8(42) between d.shardminvalue::int and d.shardmaxvalue::int"
join_sql="select u.email, count(*) from projects p join users u on u.id = p.owner_id group by u.email order by 2 desc limit 3"
prove "a join without account_id is refused by default" \
  fails_with "the query contains a join that requires repartitioning" citus-coord "$join_sql"
slow=$(best_ms "select count(*) from projects p join users u on u.id = p.owner_id")
fast=$(best_ms "select count(*) from projects p join users u on u.account_id = p.account_id and u.id = p.owner_id")
prove "adding account_id to the join makes it at least 5 times faster" \
  awk -v s="$slow" -v f="$fast" 'BEGIN { exit !(s > 5 * f) }'

select isolate_tenant_to_new_shard(
  'events', 7,
  cascade_option      => 'CASCADE',
  shard_transfer_mode => 'block_writes');

new_shard=$(coord -c "select isolate_tenant_to_new_shard('events', 7, cascade_option => 'CASCADE', shard_transfer_mode => 'block_writes')")
prove "isolate_tenant_to_new_shard gives account 7 a shard whose hash range is a single value" \
  holds citus-coord "select shardminvalue = shardmaxvalue and shardminvalue::int = hashint8(7) from pg_dist_shard where shardid = $new_shard"

代理让分片保持普通 PostgreSQL

分片代理放在通常放连接池的位置，解析每条查询，再把它发给正确的普通 PostgreSQL 主库，因此分片无需安装扩展。有三个项目公开了代码：PgDog、SPQR 和 Multigres。代理能合并哪些跨分片结果，取决于它目前的解析器支持什么；要拿自己的查询去测试。

托管分片的代价是功能受限，也更难退出

三家服务商替你运行集群：Amazon Aurora PostgreSQL Limitless Database（自 2024 年 10 月 31 日起正式可用）、Azure Database for PostgreSQL elastic clusters（托管 Citus），以及 PlanetScale Neki（自 2026 年 9 月 10 日起进入平台预览）。你要接受服务商提供的版本和功能子集，退出也更困难（参见托管平台本身）。

分布式 SQL 会说 PostgreSQL 的话，却不是 PostgreSQL

CockroachDB 和 YugabyteDB 支持 PostgreSQL 协议及其大部分 SQL，但底下是不同的数据库：由 Raft 复制的小单元组成，能自行拆分和再均衡，内置分布式事务。本书关于页、清理和堆的论述描述的是 PostgreSQL，不是它们。选择其中一个，就是迁移到另一种引擎。

每租户一个模式，成本随租户数增长

技术上最简单的选择，是为每个租户分配一个模式，甚至一整个数据库，放在你想放的服务器上。结构本身就实现了隔离，迁移一个租户只需导出一次。成本随租户数增长：1,000 个租户，每个只有三张空表，还没存一行数据，就新增了 16,000 个关系和超过 40 MB 的系统目录；每次模式变更都要执行 1,000 遍，每一遍都有自己的锁，也有失败的可能。

                          before    after 1,000 tenants
 relations in pg_class       415             16,415
 pg_attribute rows         3,161            100,161
 system catalog size      7.7 MB            56.0 MB
 database size, no rows   7.6 MB           134.0 MB

prove "1,000 tenants with three empty tables add exactly 16,000 relations" [ $((rel1 - rel0)) -eq 16000 ]
prove "the system catalogs grow by more than 40 MB before storing a row" [ $(( (cat1 - cat0) / 1048576 )) -gt 40 ]

按难题落在哪里来选择

每种方案都把难题移到别处

各种方案如何处理这些难题：

长期使用它们的成本：

托管服务一行的注释：（1）Limitless 和 elastic clusters 的跨分片写入具备原子性；处于预览阶段的 Neki 则逐个分片提交。（2）Limitless 能拆分分片，却不能合并；Neki 能在线重新分片。（3）Limitless 和 Neki 的锁定程度高，elastic clusters 较低，因为它使用的 Citus 可以自行运行。“代理”指 PgDog 及前述其他项目；Citus 的“任意节点”能力始于 Citus 11。自行构建的方案运维负担高，因为你要运行 N 个主库，加上自己开发的工具；代理在关键路径上增加了一个服务；分布式 SQL 则是一种需要重新学习的数据库。

多数团队还不需要分片

• 你还不需要分片：如果更大的机器、副本、分区，或拆出一项负载能再撑两年。多数团队都属于这种情况。
• **几十个大租户，或有数据驻留要求：**每租户一个数据库，或者带目录的应用路由器。
• **许多租户共用表，希望由 PostgreSQL 合并结果：**自建或托管的 Citus（Azure elastic clusters），或者采用分片代理，让分片无需安装扩展。两种方案都做原型测试。
• **深度依赖 AWS，也接受它的功能子集：**Aurora PostgreSQL Limitless Database。先读它不支持的功能清单。
• **想在普通 PostgreSQL 上使用托管路由器，暂时不要求跨分片写入原子性：**预览阶段的 PlanetScale Neki。先读它的限制。
• **比起完整兼容性，更看重多地域写入或自动重新分片：**分布式 SQL 数据库，同时明白它是另一种引擎。

无论考虑哪一种，都拿最重要的十条查询去运行，并阅读执行计划。

本章要点

• 最后再分片。除按功能拆分以外，这是唯一能让写入量和存储容量超越单机的一级阶梯，也会让每个跨分片查询、事务、约束和模式变更都更难。
• 真正的信号是：写入让最大的主库饱和，数据多到无法在 RTO 内恢复，或存在数据驻留要求。不是读取负载，也不是“将来某一天”。
• 多租户 SaaS 按租户 ID 分片，从今天就开始准备：每张租户表、每个键、每条查询都带上 account_id。
• 按分片键做共置连接，就能留在本地：把 account_id 写入 on 子句时约 10 ms，没有时约 950 ms。
• 邮箱之类需要全局唯一的值，都需要独立的未分片表。
• 为迁移热点租户做好准备：目录，加上带行过滤的逻辑复制。
• 按路由、合并和两阶段提交应放在哪里来选择方案，并检查负载最高的查询的计划中是否存在扇出。

延伸阅读

• postgres_fdw，PostgreSQL 文档。外部表、下推、async_capable，以及不支持两阶段提交的说明。
• Citus，源码仓库。本章所用的扩展、许可证，以及按行和按模式分片。
• Aurora PostgreSQL Limitless Database architecture，AWS 文档。路由器、分片和表类型；同时阅读旁边的要求页面。
• PgDog，源码仓库。从分片代理的角度介绍路由、合并、两阶段提交与重新分片。
• Neki query planning，PlanetScale 文档。路由器如何选择一个分片或所有分片，以及跨分片操作不提供哪些保证。
• CockroachDB PostgreSQL compatibility，CockroachDB 文档。具体差异清单。