shaguabijia-app-server/docs/数据库迁移.md

数据库迁移指南（Alembic）

本项目用 Alembic 管理数据库表结构。所有"建表/改表"都写成 alembic/versions/ 下的迁移脚本， 数据库的真实结构 = 把这些迁移按顺序跑一遍的结果。不要手动改库结构，一律走迁移。

---

一句话

clone 项目 / 拉到新迁移后，跑一条命令即可：

alembic upgrade head

它会把数据库结构升到最新（幂等，已是最新则什么都不做）。

---

1. 首次初始化（clone 后）

# (1) 装依赖(在你的虚拟环境里)
pip install -e .

# (2) 配 .env(从模板复制,至少填 JWT_SECRET_KEY)
cp .env.example .env

# (3) SQLite 默认库需要 data/ 目录存在
mkdir -p data

# (4) 跑迁移建表 —— 关键
alembic upgrade head

# (5) 启动(run.sh 会自动重跑 3+4,所以平时直接 ./run.sh 也行)
./run.sh

也可以直接 bash scripts/migrate.sh 只做迁移、不启服务（部署/CI 用）。

2. 数据库地址从哪来

• 由 settings.DATABASE_URL 决定（app/core/config.py），可在 .env 用 DATABASE_URL= 覆盖。
• 默认 SQLite：sqlite:///./data/app.db（所以要先 mkdir -p data）。
• 切 PostgreSQL：.env 里设 DATABASE_URL=postgresql+psycopg://user:pwd@host:5432/dbname，再 alembic upgrade head 即可（迁移脚本用了 render_as_batch 兼容 SQLite，Postgres 也能跑）。
• alembic.ini 的 sqlalchemy.url 故意留空，由 alembic/env.py 从 settings 注入，别在 alembic.ini 里填库地址。

3. 常用命令

命令	作用
alembic upgrade head	升到最新（最常用）
alembic current	看当前库在哪个 revision
alembic history	看迁移链（谁接谁）
alembic heads	看有几个 head（正常只 1 个；出现多个 = 分叉了要 merge）
alembic downgrade -1	回滚一步（生产慎用，会丢数据）
alembic downgrade <revision>	回滚到指定版本

4. 改了 ORM model、要新增一次结构变更

# 1) 自动对比 models 与库,生成迁移草稿
alembic revision --autogenerate -m "add xxx index"
# 2) **务必打开生成的文件 review**(autogenerate 不完美,索引/默认值/数据迁移常需手改)
# 3) 应用
alembic upgrade head

---

5. 关于迁移文件名（重要）

• 文件名是 <描述>.py（如 welfare_tables_coin_account_coin_txn.py）。早期带的 hex 前缀已去掉，只是文件名变干净。
• 真正的版本 id 是文件内的 revision 变量（如 revision = '357520ea3015'），迁移链靠文件内的 down_revision 串起来，与文件名无关。数据库 alembic_version 表里存的也是这个内部 id。
• 因此：可以随意重命名迁移文件（Alembic 靠扫描文件、读 revision 识别），但 绝不要改文件内的 revision / down_revision——改了会和已迁移过的库（含生产）对不上，报"找不到 revision"。
• ⚠️ alembic revision --autogenerate 默认仍生成带 hex 前缀的文件名。想保持本目录"无前缀"风格，二选一：
  • 生成后手动把文件名前缀去掉（内部 id 别动）；或
  • 在 alembic.ini 配 file_template = %%(slug)s（注意 ini 里 % 要写成 %%）让以后直接生成无前缀文件名（缺点：同名 slug 会冲突，描述写具体点）。

6. 当前迁移链（9 条）

init_user_table                      ← 起点(down_revision=None)
  → welfare_tables_coin_account_coin_txn   金币账户/金币流水/签到/任务表
  → cash_transaction_table                 现金流水表
  → savings_record_table                   省钱明细表
  → withdraw_order_and_user_openid         提现单表 + user.wechat_openid
  → user_wechat_nickname_avatar            user 微信昵称/头像字段
  → unique_wechat_openid                   user.wechat_openid 唯一约束
  → savings_shop_dishes                    省钱明细 shop_name + dishes
  → ad_reward_record                       看广告发奖记录表 (head,最新)

顺序以 alembic history 输出为准（按 down_revision 链，不是文件名字母序）。

7. 踩坑

• SQLite 找不到目录：报 unable to open database file → 先 mkdir -p data。
• 多个 head：alembic heads 出现 2 个 → 有人并行各加了一条迁移分叉，需 alembic merge -m "merge" <head1> <head2> 合并。
• 生产库：不要随意 downgrade；新迁移先在本地/测试库验证过再上。生产 DATABASE_URL 由部署侧配置，不在本仓库 .env。