superior-database

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Superior Database

Make data changes correct for the actual datastore, workload, and rollout environment. Preserve established migration tools and ownership boundaries; do not import generic database conventions without verifying engine behavior and repository practice.

确保数据变更适用于实际的数据存储、工作负载和发布环境。保留既定的迁移工具和职责边界；在验证引擎行为和仓库实践之前，不要引入通用的数据库惯例。

Establish the data contract

建立数据契约

Before changing a schema, query, or migration, determine:

datastore engine, version, topology, and relevant extensions;
authoritative schema and migration history;
entity ownership, identifiers, relationships, and tenant boundaries;
invariants that must hold at write time and read time;
expected cardinality, access patterns, ordering, and retention;
compatibility window across application versions, workers, and replicas;
data volume, traffic shape, lock sensitivity, and recovery expectations.

Inspect effective production constraints only through authorized, non-sensitive evidence. Do not assume local fixtures represent production volume, skew, nullability, or legacy states.

在修改 Schema、查询或迁移之前，确定：

数据存储引擎、版本、拓扑及相关扩展；
权威的 Schema 和迁移历史；
实体所有权、标识符、关系和租户边界；
写入时和读取时必须成立的不变量；
预期的基数、访问模式、排序方式和保留策略；
应用版本、Worker 和副本之间的兼容窗口；
数据量、流量形态、锁敏感性和恢复要求。

仅通过已授权且不含敏感信息的证据检查生产环境中的实际约束。不要假设本地测试夹具能够代表生产环境的数据规模、数据偏斜、可空性或遗留状态。

Design schema and queries together

协同设计 Schema 和查询

Read references/schema-query-and-index-design.md when adding or changing tables, collections, fields, relationships, indexes, query shapes, pagination, or retention behavior.

Encode durable invariants in the datastore when the engine and rollout permit it.
Keep application validation for user feedback, but do not rely on it as the sole protection against concurrent or alternate writers.
Select indexes from real predicates, joins, ordering, uniqueness, and cardinality rather than indexing every filtered field.
Verify query semantics for nulls, collation, timezones, ordering ties, and empty sets.
Bound result sets and write batches; avoid hidden full scans, unbounded fan-out, and per-row queries.

Do not denormalize, partition, shard, or introduce a cache without demonstrated workload pressure and a clear consistency owner.

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

在引擎和发布条件允许时，将持久性不变量编码到数据存储中。
保留应用层校验以提供用户反馈，但不要将其视为防止并发写入或其他写入来源的唯一保护机制。
根据真实的谓词、连接、排序、唯一性和基数选择索引，而不是为每个筛选字段建立索引。
验证查询在空值、排序规则、时区、排序并列和空集合情况下的语义。
限制结果集和写入批次；避免隐式全表扫描、无界扇出和逐行查询。

在没有明确的工作负载压力和清晰的一致性责任方之前，不要进行反规范化、分区、分片或引入缓存。

Preserve transactional truth

维护事务真实性

Read references/transactions-and-consistency.md when work spans related writes, concurrent actors, replicas, queues, caches, idempotency, or cross-service workflows.

Define the invariant and the exact boundary that must be atomic.
Use datastore guarantees deliberately; do not infer serialization from application request order.
Keep transactions short and avoid remote calls while holding locks unless the established architecture proves it safe.
Make retryable operations idempotent and distinguish transaction retry from business-operation replay.
Treat cache invalidation, replica lag, and event publication as explicit consistency contracts.

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

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

Plan migrations as deployments

将迁移作为部署进行规划

Read references/safe-migrations-and-backfills.md for production-facing schema changes, constraint introduction, type changes, table rewrites, backfills, data repair, or removal of old representations.

Prefer compatibility-first expand, migrate, verify, and contract phases when multiple application versions may coexist.
Identify locks, rewrites, validation cost, replication impact, and failure recovery before execution.
Make backfills bounded, observable, resumable, and idempotent where practical.
Define verification and rollback or forward-recovery behavior before destructive or irreversible steps.
Never run a production migration, destructive query, broad data correction, or shared-environment load test without explicit authorization and the intended environment.

A migration file compiling locally is not evidence that its production execution is safe.

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

当多个应用版本可能共存时，优先采用以兼容性为先的扩展、迁移、验证和收缩阶段。
执行前识别锁、表重写、验证成本、复制影响和故障恢复方式。
在切实可行的情况下，使数据回填具备边界、可观测、可恢复和幂等性。
在执行破坏性或不可逆步骤之前，明确验证方式以及回滚或前向恢复行为。
未经明确授权并确认目标环境，绝不要在生产环境运行迁移、破坏性查询、大范围数据修正或共享环境负载测试。

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

Verify the result

验证结果

Use the repository's existing database and test tooling. Verify proportionately:

migration applies from the supported previous state and reaches the intended schema;
rollback works when it is promised and semantically possible;
old and new application versions behave according to the compatibility plan;
constraints reject invalid states and preserve valid legacy data;
representative queries return correct results with stable ordering;
query plans and runtime behavior are checked against representative shape and scale when performance is in scope;
backfill counts, checkpoints, error handling, and reruns preserve invariants.

Report commands actually run, datastore/version used, data scale represented, and conditions not exercised. Never claim zero downtime without evidence for the relevant engine, topology, workload, and deployment sequence.

使用仓库现有的数据库和测试工具，并按风险与影响范围进行验证：

迁移能够从受支持的上一状态成功应用，并达到预期 Schema；
在承诺支持回滚且语义上可行时，回滚能够正常工作；
旧版和新版应用的行为符合兼容性计划；
约束能够拒绝无效状态，同时保留有效的遗留数据；
代表性查询返回正确结果，并具有稳定的排序；
当性能属于验证范围时，根据有代表性的数据形态和规模检查执行计划与运行时行为；
数据回填的数量、检查点、错误处理和重新执行能够保持不变量。

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

Combine skills narrowly

严格限定 Skill 的组合范围

Use
```
superior-logic
```
for domain behavior, API contracts, and application orchestration around persistence.
Use
```
superior-testing
```
when migration, integration, compatibility, or concurrency test design is a primary concern.
Use
```
superior-debugging
```
when a data symptom exists but its causal mechanism is uncertain.
Use
```
superior-performance
```
when representative query, capacity, resource, or latency measurement is a primary concern.
Use
```
superior-reliability
```
when replication, availability, failover, backup objectives, or recovery readiness is primary.
Use
```
superior-delivery
```
when migrations must be coordinated with artifact promotion, rollout, or rollback.
Use
```
superior-api-security
```
for tenant isolation, unsafe query construction, sensitive-data exposure, or abuse-driven resource controls.
Use
```
superior-docs
```
after verified schema, migration, recovery, or operational procedure changes.

Do not broaden a focused database change into a datastore replacement, ORM rewrite, or infrastructure migration without explicit scope.

使用
```
superior-logic
```
处理持久化相关的领域行为、API 契约和应用编排。
当迁移、集成、兼容性或并发测试设计是主要关注点时，使用
```
superior-testing
```
。
当出现数据异常，但其因果机制尚不明确时，使用
```
superior-debugging
```
。
当代表性查询、容量、资源或延迟测量是主要关注点时，使用
```
superior-performance
```
。
当复制、可用性、故障转移、备份目标或恢复准备是主要关注点时，使用
```
superior-reliability
```
。
当迁移必须与制品晋级、发布或回滚协调时，使用
```
superior-delivery
```
。
对于租户隔离、不安全的查询构建、敏感数据暴露或滥用驱动的资源控制，使用
```
superior-api-security
```
。
在经过验证的 Schema、迁移、恢复或运维流程发生变更后，使用
```
superior-docs
```
。

未经明确授权，不要将聚焦的数据库修改扩展为数据存储替换、ORM 重写或基础设施迁移。