superior-database

卓越数据库

确保数据变更符合实际的数据存储、工作负载和发布环境。保留既有迁移工具和所有权边界；未经验证引擎行为和仓库实践，不要照搬通用数据库惯例。

确定数据契约

在更改架构、查询或迁移之前，先确定：

• 数据存储引擎、版本、拓扑结构及相关扩展；
• 权威架构和迁移历史；
• 实体所有权、标识符、关系和租户边界；
• 写入和读取时必须满足的不变量；
• 预期基数、访问模式、排序方式和保留期限；
• 应用版本、工作进程和副本之间的兼容窗口；
• 数据量、流量特征、锁敏感性和恢复预期。

只能通过获准的非敏感证据检查实际生产约束。不要假定本地测试数据能代表生产环境中的数据量、分布偏斜、可空性或旧有状态。

将架构设计与查询一并考虑

添加或更改表、集合、字段、关系、索引、查询形态、分页或保留行为时，请阅读 references/schema-query-and-index-design.md。

• 在引擎和发布条件允许时，将持久性不变量编码到数据存储中。
• 保留应用层验证以便向用户提供反馈，但不要将其作为防范并发写入者或其他写入者的唯一保护措施。
• 根据实际谓词、联接、排序、唯一性和基数选择索引，不要给每个筛选字段都建索引。
• 验证空值、排序规则、时区、排序平局和空集合的查询语义。
• 限制结果集和写入批次；避免隐式全表扫描、无界扇出和逐行查询。

没有经证实的工作负载压力和明确的一致性负责人时，不要进行反规范化、分区、分片或引入缓存。

保持事务真实性

当工作涉及相关写入、并发参与者、副本、队列、缓存、幂等性或跨服务工作流时，请阅读 references/transactions-and-consistency.md。

• 定义不变量以及必须保持原子性的确切边界。
• 有意使用数据存储的保证；不要根据应用请求顺序推断事务可串行化。
• 保持事务简短；除非既有架构能够证明安全，否则在持锁期间避免远程调用。
• 使可重试操作具备幂等性，并区分事务重试与业务操作重放。
• 将缓存失效、副本延迟和事件发布视为明确的一致性契约。

将迁移规划为部署

对于面向生产环境的架构更改、约束引入、类型更改、表重写、回填、数据修复或旧表示形式移除，请阅读 references/safe-migrations-and-backfills.md。

• 多个应用版本可能并存时，优先采用先兼容、再扩展、迁移、验证，最后收缩的阶段式方案。
• 执行前，确认锁、重写、验证成本、复制影响以及故障恢复方式。
• 在实际可行时，使回填有界、可观察、可续传且具备幂等性。
• 在执行破坏性或不可逆操作之前，定义验证方式以及回滚或向前恢复方案。
• 未经明确授权并确认目标环境，不得运行生产迁移、破坏性查询、大范围数据修正或共享环境负载测试。

迁移文件在本地编译成功，并不能证明其在生产环境中的执行是安全的。

验证结果

使用仓库现有的数据库和测试工具，按需进行验证：

• 迁移能否从受支持的先前状态应用，并达到预期的架构；
• 在承诺回滚且语义上可行时，回滚是否有效；
• 旧版和新版应用是否按照兼容性计划运行；
• 约束能否拒绝无效状态并保留有效的旧数据；
• 代表性查询能否返回正确结果，且排序稳定；
• 如果性能属于范围，是否针对具有代表性形态和规模的数据检查了查询计划和运行时行为；
• 回填计数、检查点、错误处理和重跑是否能维持不变量。

报告实际运行的命令、使用的数据存储及其版本、所代表的数据规模，以及未测试的条件。没有相关引擎、拓扑、工作负载和部署顺序的证据时，绝不要声称实现了零停机。

有针对性地组合技能

• 将 superior-logic 用于持久化相关的领域行为、API 契约和应用编排。
• 当迁移、集成、兼容性或并发测试设计是主要关注点时，使用 superior-testing。
• 当数据问题的因果机制不明确时，使用 superior-debugging。
• 当代表性查询、容量、资源或延迟测量是主要关注点时，使用 superior-performance。
• 当复制、可用性、故障转移、备份目标或恢复就绪情况是主要关注点时，使用 superior-reliability。
• 当迁移必须与制品晋级、部署或回滚协调时，使用 superior-delivery。
• 对于租户隔离、不安全的查询构造、敏感数据泄露或滥用导致的资源控制，使用 superior-api-security。
• 在经过验证的架构、迁移、恢复或运维流程发生变更后，使用 superior-docs。

除非范围有明确要求，否则不要将聚焦于数据库的变更扩大为替换数据存储、重写 ORM 或迁移基础设施。