codex-console 数据库迁移教程引入 Alembic 实现版本平滑升级与字段自动补齐的完整指南【免费下载链接】codex-consolecodex-console 是一个集成化控制台项目支持任务管理、批量处理、数据导出、自动上传、日志查看与打包支持。项目地址: https://gitcode.com/gh_mirrors/co/codex-consolecodex-console是一个集成化控制台项目支持任务管理、批量处理、数据导出、自动上传、日志查看与打包支持。随着功能迭代SQLite 数据库的表结构也会不断变化——这篇文章带你完整掌握codex-console 数据库迁移的做法通过引入Alembic实现版本平滑升级、可回滚再配合启动时的字段自动补齐让老用户在升级时零数据丢失。为什么需要数据库迁移新手常有一个误区在 SQLAlchemy 里写好模型调用create_all()建表就一劳永逸了。但实际上✅create_all()只会创建缺失的表❌ 它不会给已存在的表添加新列、改列类型或加索引也就是说当你在 src/database/models.py 里给accounts表新增了pool_state、priority等字段后老用户的数据库里这些列并不存在程序一跑就报错。以本项目为例accounts表随版本演进新增了账号标签、池状态、优先级、订阅类型等大量字段bind_card_tasks表则把account_id改成了可空并补充了account_email快照字段。这些变更都需要一套靠谱的迁移机制来保障。项目中的双保险迁移机制 ️codex-console 采用了两套互补的机制这也是本教程的核心知识点第一层启动时字段自动补齐兜底应用每次启动时DatabaseSessionManager.migrate_tables()会自动检查老表是否缺少新列用ALTER TABLE ... ADD COLUMN逐列补齐。实现位于 src/database/session.py流程是通过pragma_table_info查询表结构中是否已存在目标列缺失则执行ALTER TABLE 表名 ADD COLUMN 列名 类型顺带做数据回填如账号标签role_tag与account_label的互相同步、pool_state默认值补齐并创建缺失的索引这一层保证了普通用户升级后直接启动即可用无需手动执行任何命令。第二层Alembic 版本化迁移主力自动补齐只能加列无法处理改类型、加外键、复杂数据迁移等场景。因此项目引入了AlembicSQLAlchemy 官方推荐的迁移框架把每次结构变更沉淀为带版本号的迁移脚本可前进、可回滚详见 alembic/README.md。认识 Alembic 目录结构 alembic/ ├── versions/ # 迁移脚本存放目录每个版本一个文件 ├── env.py # 迁移环境配置连接、元数据、事务 └── script.py.mako # 生成迁移脚本时使用的模板 alembic.ini # 全局配置脚本位置、数据库 URL、日志关键文件说明文件作用alembic.ini指定script_location alembic默认数据库为sqlite:///data/database.dbalembic/env.py把模型元数据Base.metadata交给 Alembic并启用compare_typeTrue做类型对比alembic/versions/autogenerate 生成的迁移脚本按版本链依次执行alembic/script.py.mako新迁移文件的模板含upgrade()/downgrade()两个钩子三步实操完成一次数据库迁移 以下命令均在项目根目录执行完整说明见 alembic/README.md。步骤 1初始化基线版本baseline首次为已存在数据的旧库建立迁移起点时先生成基线版本再升级alembic revision --autogenerate -m baseline alembic upgrade head步骤 2模型改动后自动生成新迁移修改 src/database/models.py 中的模型后autogenerate 会自动对比Base.metadata与当前数据库结构生成差异脚本alembic revision --autogenerate -m add_xxx 得益于env.py中开启的compare_typeTrue列类型变更也能被自动检测出来生成后建议人工检查一遍versions/下的脚本再执行。步骤 3升级与回滚alembic upgrade head # 升级到最新版本 alembic downgrade -1 # 回滚最近一次迁移upgrade/downgrade成对可逆这是相对纯 ALTER TABLE 脚本最大的优势——升级出问题可以退回去真正做到版本平滑升级。数据库连接地址从哪里读alembic/env.py中的_resolve_database_url()采用三级优先策略见 src/database/session.py 中类似的 URL 处理逻辑优先读取 alembic.ini 中的sqlalchemy.url未配置时回退到 src/config/settings.py 的get_database_url()支持APP_DATABASE_URL环境变量最终兜底为sqlite:///data/database.db如果你使用 PostgreSQL 等其他数据库只需在alembic.ini里改成对应连接串即可迁移脚本无需任何改动。常见问题 FAQ ❓Q1老库升级一定要手动跑 Alembic 吗不一定要。字段级的新增列已由启动时的自动补齐兜底但涉及类型变更、数据改写等复杂迁移时仍建议走alembic upgrade head的正式流程。Q2自动补齐对非 SQLite 数据库生效吗不生效。migrate_tables()检测到非 SQLite 连接时会跳过见 src/database/session.py这类场景请完全依赖 Alembic。Q3迁移前需要备份吗强烈建议。执行任何upgrade/downgrade前先复制一份data/database.db是成本最低的保护手段。小结codex-console 用启动自动补齐 Alembic 版本化迁移双保险保障数据库平滑升级日常只需记住三条命令alembic revision --autogenerate、alembic upgrade head、alembic downgrade -1相关源码alembic/env.py、src/database/session.py、src/database/models.py升级前备份数据库文件是养成好习惯的开始 ✅【免费下载链接】codex-consolecodex-console 是一个集成化控制台项目支持任务管理、批量处理、数据导出、自动上传、日志查看与打包支持。项目地址: https://gitcode.com/gh_mirrors/co/codex-console创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考