数据库迁移搞到崩溃？DB Migrations Skill让Alembic不再是噩梦🔥-Skill优仓

做过后端开发的都懂那种感觉——ORM模型改了一个字段，Alembic迁移文件生成出来一堆莫名其妙的drop操作，SQLite跑得好好的，一切换Postgres直接报错，本地数据库状态和主分支早就对不上了……这种时候真的想掀桌子。

DB migrations and schema changes这个Skill，专门为letta-cloud核心应用的Alembic数据库迁移场景而生，把那些让人头秃的工作流全部沉淀成可复用的操作规范，配合uv、just和LETTA_PG_URI，从新增字段到数据回填再到修复坏掉的迁移，一套流程全覆盖。

核心功能

这个Skill的核心价值在于把Alembic迁移的五类高频场景全部标准化：

ORM优先的字段新增与修改：先改SQLAlchemy模型，优先复用Mixin（比如ProjectMixin），再用uv run alembic revision --autogenerate自动生成迁移文件，最后uv run alembic upgrade head应用。
数据回填迁移：在upgrade()里用op.get_bind()配合SQLAlchemy Core写回填逻辑，downgrade()保持简洁可逆。
修复坏掉的迁移：遇到SQLite的ALTER约束限制，直接切Postgres重跑；逻辑有问题就新建迁移修复，绝不在已应用的revision上动手脚。
SQLite与Postgres自由切换：通过LETTA_PG_URI环境变量控制引擎选择，本地开发用just ready搞定基线迁移，生产级迁移走Postgres。
本地Postgres重置：当本地数据库状态和主分支漂移时，一套完整的重置流程确保迁移生成在干净的基线上进行，彻底消灭spurious diff。

适用平台

这个Skill完美适配主流AI编程助手，包括Cursor、GitHub Copilot、Claude Code、OpenAI Codex、Gemini Code Assist、文心快码、腾讯云CodeBuddy、华为云CodeArts等。把它加载进这些工具后，AI能精准理解你的迁移意图、项目结构和工具链约定，不再给你生成驴唇不对马嘴的迁移命令，堪称这些IDE处理数据库变更任务的最强外挂。

实操代码示例

下面是重置本地Postgres并生成干净迁移的完整流程，这也是最容易踩坑的场景：

# 1. 删除postgres数据目录
rm -rf ./data/postgres

# 2. 停止运行中的postgres容器
docker stop $(docker ps -q --filter ancestor=ankane/pgvector)

# 3. 重启服务，创建全新postgres
just start-services

# 4. 等postgres就绪后，应用所有现有迁移
cd apps/core
export LETTA_PG_URI=postgresql+pg8000://postgres:postgres@localhost:5432/letta-core
uv run alembic upgrade head

# 5. 生成新迁移
uv run alembic revision --autogenerate -m "your migration message"

日常新增字段的最简流程：

just ready
export LETTA_PG_URI=postgresql+pg8000://postgres:postgres@localhost:5432/letta-core
uv run alembic revision --autogenerate -m "add project_id to agents"
uv run alembic upgrade head

优势分析

市面上关于Alembic的文档一抓一大把，但大多数只讲命令本身，不讲为什么这么做以及踩坑之后怎么救。这个Skill的差异化在于：

明确区分SQLite和Postgres的行为差异，不让你在错误的引擎上浪费时间。
提供”修复坏迁移”的正确姿势——新建修复迁移而非篡改历史，在团队协作环境里这一点至关重要。
把uv、just、LETTA_PG_URI的组合用法固化下来，消除团队成员之间的工具链认知差异。
故障排查部分直接给出”Target database is not up to date”、”SQLite NotImplementedError”等真实报错的处理方案，不是泛泛而谈。

应用场景

新功能开发：产品要求给Agent表加一个project_id字段，走ORM优先流程，三步搞定，不用手写SQL。
历史数据迁移：上线新字段后需要给存量数据回填默认值，在Alembic的upgrade()里写一次性迁移脚本，比写独立脚本更安全，回滚也有保障。
CI/CD流水线：在部署脚本里直接调用uv run alembic upgrade head，配合LETTA_PG_URI指向目标环境，迁移和部署一体化。
新人上手：团队新成员不用再口口相传”记得先设那个环境变量”，Skill里全有，照着走就行。
紧急修复：生产环境迁移失败，按照”修复坏迁移”工作流，新建修复revision，不影响其他人的本地历史。