database-sharding

database-sharding 是一套面向 PostgreSQL/MySQL 的数据库分片技能，目标是帮助实现水平扩展、多租户隔离，以及支撑数十亿级记录的数据规模。

用途该技能围绕数据库分片（sharding）展开，提供哈希、范围、目录三种分片策略的模板与参考文档，并给出分片键选择、路由实现、跨分片事务、再平衡与监控等实践指引。

主要能力

分片策略：哈希（均匀分布）、范围（时间序列/日志/追加写入）、目录（多租户/复杂路由）。
模板与代码示例：templates/hash-router.ts、templates/range-router.ts、templates/directory-router.ts、templates/cross-shard-aggregation.ts。
参考文档：references/sharding-strategies.md、references/shard-key-selection.md、references/implementation-patterns.md、references/cross-shard-queries.md、references/rebalancing-guide.md、references/error-catalog.md。
分片键选择标准：高基数、分布均匀（单值不超过总量 5%）、不可变、查询对齐（80% 以上 WHERE 子句包含）、数据局部性。
路由实现示例：HashRouter、RangeRouter、DirectoryRouter 的初始化与查询调用方式。
跨分片事务：两阶段提交（2PC）或 Saga 模式。
再平衡：一致性哈希、虚拟分片，减少新增分片时的键迁移。
监控指标：每分片记录数、查询分布、存储、p99 延迟。

使用方式资料给出的快速开始流程为：先从模板中选择分片策略，再选择分片键标准，然后实现路由。示例代码包括：

import { HashRouter } from './hash-router';

const router = new HashRouter([ { id: 'shard_0', connection: { host: 'db0.example.com' } }, { id: 'shard_1', connection: { host: 'db1.example.com' } }, { id: 'shard_2', connection: { host: 'db2.example.com' } }, { id: 'shard_3', connection: { host: 'db3.example.com' } }, ]);

const user = await router.query('user_123', 'SELECT * FROM users WHERE id = $1', ['user_123']);

范围路由示例：

import { RangeRouter } from './templates/range-router';

const router = new RangeRouter(shardConfigs, [ { start: Date.parse('2024-01-01'), end: Date.parse('2024-04-01'), shardId: 'shard_q1' }, { start: Date.parse('2024-04-01'), end: Date.parse('2024-07-01'), shardId: 'shard_q2' }, { start: Date.parse('2024-07-01'), end: Infinity, shardId: 'shard_q3' }, ]);

const janEvents = await router.queryRange( Date.parse('2024-01-01'), Date.parse('2024-02-01'), 'SELECT * FROM events WHERE created_at BETWEEN $1 AND $2' );

目录路由示例：

import { DirectoryRouter } from './templates/directory-router';

const router = new DirectoryRouter(directoryDBConfig, shardConfigs);

await router.assignShard('tenant_acme', 'shard_enterprise');

const users = await router.query('tenant_acme', 'SELECT * FROM users');

适用场景

用户数据、负载均衡要求高的场景（哈希）。
时间序列、日志、追加写入场景（范围）。
多租户 SaaS、复杂路由场景（目录）。
需要跨分片聚合（COUNT、SUM、AVG）、跨分片连接、跨分片分页的场景。
需要新增分片、迁移数据、零停机迁移、平衡不均负载的场景。

限制与注意事项资料列出多项关键规则与常见错误：查询必须包含分片键，否则会扫描全部分片；需监控分片分布以发现热点；需提前规划再平衡；分片键应不可变；应使用生产数据测试分布；应为数据局部性做反规范化。应避免：顺序 ID 配合范围分片、时间戳作为分片键、无 2PC 的跨分片事务、无一致性哈希的简单取模、可空分片键、无分片路由层。资料还列出 10 项已记录错误及修复方式，并给出完整设置检查清单，包括初始 4-8 个分片、每分片连接池、每分片副本与备份、应用层查询改造等。

生产示例资料给出单库到 8 分片的对比示例：单库 1000 万用户查询耗时 5000ms、CPU 95%、磁盘 500GB；分片后单用户查询 10ms、全分片并行查询 800ms、每分片约 125 万用户、CPU 20%、磁盘 65GB，并可借助一致性哈希扩展到 16 分片。

资源模板：templates/hash-router.ts、templates/range-router.ts、templates/directory-router.ts、templates/cross-shard-aggregation.ts。参考：references/sharding-strategies.md、references/shard-key-selection.md、references/implementation-patterns.md、references/cross-shard-queries.md、references/rebalancing-guide.md、references/error-catalog.md。生产案例：Instagram（媒体范围分片）、Discord（消息哈希分片）、Salesforce（组织目录分片）。资料标注为生产验证、预防 10 类错误、MIT 许可证。

技能介绍