Files
codex-proxy-rs/backend/migrations
..

数据库迁移

服务监听请求前,sqlx 按编号执行本目录的 SQL,并将文件校验和写入 _sqlx_migrations。已应用文件的校验和不匹配时,服务拒绝启动

状态所有权 · 离线恢复

命名约定

  • 表名使用小写 snake_case,实体集合使用复数,配置与单例状态使用自然语义,如 runtime_settings、request_analytics_build_state
  • 业务归属使用领域前缀,同一实体统一使用 client_api_key、account_group、provider 等术语,不添加 tbl_ 等对象类型前缀
  • 统计时间粒度使用 15m、1h、1d;只保存计数的表保留 _counts 后缀
  • 表名调整时同步查询、函数体及所属索引和约束名称,已冻结迁移仍保持原样

冻结规则

  • 同一大版本内,合入 main 的迁移文件按字节永久冻结,包括注释和空白。修改 schema 或修正错误须追加编号迁移,使用 alter 或数据回填
  • 跨大版本不支持在线升级,目标版本必须使用全新数据目录部署;此时可将已完成升级的 schema 折叠为新的初始化基线
  • 支持连续升级的预发行线从首次发布起同样冻结迁移。alpha、beta、rc 到对应正式版必须保留 已发布迁移的编号与字节;同一轮 exp 的后续发行也只能追加迁移。发布前以该发行线已发布版本 的数据库验证升级路径,不能只与上一正式版比较。不同 exp 实验线之间、exp 与正式版之间 不保证迁移历史兼容
  • .frozen-sha256 使用 sha256sum 格式。新增迁移时在同一提交执行 sha256sum 000N_xxx.sql >> .frozen-sha256 入册;CI 校验文件字节、SQL 登记完整性及 PR 中清单只增不改

从迁移目录检查已登记文件:

cd backend/migrations
sha256sum --check --strict .frozen-sha256

校验和不一致时无法自动恢复。核对运行版本与文件来源,不要改写数据库中的校验和

本地测试库

gateway-store 的 PostgreSQL/Redis 集成测试使用以下环境变量;所需测试服务未配置时,本地相关测试跳过,CI 直接失败:

export CPR_TEST_DATABASE_URL='postgres://<user>:<password>@127.0.0.1:5432/<db>'
export CPR_TEST_REDIS_URL='redis://:<password>@127.0.0.1:6379'

插件 Runtime 的真实子进程与持久化测试可使用专用的 CPR_PLUGIN_TEST_DATABASE_URL,此时须同时设置 CPR_PLUGIN_TEST_REDIS_URL。省略插件数据库 URL 时使用上面的测试服务

使用专用开发或测试实例,测试通过随机 schema 和 Redis key 前缀隔离数据。凭据取自部署配置或 CI Secret,不要分享未脱敏的 docker inspect 输出

PostgreSQL 的临时 schema 测试连接使用异步提交,保留事务可见性、回滚和完整迁移检查 需要验证数据库崩溃后的持久性时,使用独立数据库与生产连接配置,不复用这类 fixture

运行包含 StoreBundle 初始化的完整集成测试时,两条测试 URL 都须包含密码,原始密码须满足 Store 密码要求,在测试 URL 中按 URL 规则编码。 在测试进程中清除 CPR_DATABASE_URL、CPR_REDIS_URL、CPR_DATABASE_PASSWORD 和 CPR_REDIS_PASSWORD,避免部署环境覆盖测试配置