The Agent Skills Directory
npx skills add https://smithery.ai/skills/letta-ai/db-migrations-and-schema-changes当您需要在 letta-cloud 代码库的 apps/core 中变更数据库模式或调试 Alembic 迁移时,请使用此技能。
此技能假设:
apps/coreapps/core/alembic 的 Alembicuvjust ready 进行环境和数据库设置just readyexport LETTA_PG_URI=postgresql+pg8000://postgres:postgres@localhost:5432/letta-coreuv run alembic revision --autogenerate -m "<简短描述>"uv run alembic upgrade head具体命令和变体请参阅 references/migration-commands.md。
letta/orm/... 中更新 SQLAlchemy 模型:
ProjectMixin),而不是重复定义列。just ready。LETTA_PG_URI。uv 自动生成 Alembic 修订版本。alembic/versions/ 下生成的文件:
op.add_column / op.alter_column 符合预期。uv run alembic upgrade head 应用迁移。此模式适用于通过 ProjectMixin 添加 project_id 列等变更。
upgrade() 中添加 Python 逻辑,该逻辑:
op.get_bind() 和 SQLAlchemy Core/SQL 来回填数据。downgrade() 简单且安全(理想情况下可逆)。LETTA_PG_URI 后针对 Postgres 运行,使用 uv run alembic upgrade head。典型情况:
工作流程:
alembic/versions/ 中识别失败的修订版本。LETTA_PG_URI 并重新运行升级来针对 Postgres 运行迁移。SQLite 特有的问题请参阅 references/sqlite-vs-postgres-gotchas.md。
Alembic 根据 letta.settings.DatabaseChoice 和环境变量选择引擎。
一般规则:
just ready 处理基线迁移。LETTA_PG_URI。针对 Postgres 迁移的工作流程:
export LETTA_PG_URI=postgresql+pg8000://postgres:postgres@localhost:5432/letta-coreapps/core 目录下:
uv run alembic upgrade headuv run alembic revision --autogenerate -m "..."如果您的本地 Postgres 数据库已偏离主线(例如,应用了不再存在的迁移,或具有过时的模式),您可以重置它以生成干净的迁移。
在代码库根目录 (/Users/sarahwooders/repos/letta-cloud) 下:
# 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 "您的迁移描述"
这确保了迁移是基于与主线匹配的干净数据库状态生成的,避免了因仅本地模式变更而产生的虚假差异。
uv run alembic upgrade head(使用适当的引擎/URI)。LETTA_PG_URI 切换到 Postgres 并重新运行。Base.metadata)正确,并且更改的模型已在 Alembic 环境上下文中导入。references/migration-commands.md — uv、Alembic 和 just 的规范命令。references/sqlite-vs-postgres-gotchas.md — 引擎特有的陷阱及如何避免。每周安装次数
–
来源
首次出现
–
Use this skill whenever you need to change the database schema or debug Alembic migrations in apps/core of the letta-cloud repo.
This skill assumes:
apps/coreapps/core/alembicuvjust ready for environment + DB setupjust readyexport LETTA_PG_URI=postgresql+pg8000://postgres:postgres@localhost:5432/letta-core广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
uv run alembic revision --autogenerate -m "<short_message>"uv run alembic upgrade headSee references/migration-commands.md for exact commands and variants.
letta/orm/...:
ProjectMixin) when available instead of duplicating columns.just ready if dependencies or environment may have changed.LETTA_PG_URI is set if you want the migration to target Postgres.uv.alembic/versions/:
op.add_column / op.alter_column match expectations.uv run alembic upgrade head.Use this pattern for changes like adding project_id columns via ProjectMixin.
upgrade() that:
op.get_bind() and SQLAlchemy Core/SQL to backfill data.downgrade() simple and safe (ideally reversible).LETTA_PG_URI set, using uv run alembic upgrade head.Typical cases:
Workflow:
alembic/versions/.LETTA_PG_URI and re-running upgrade.See references/sqlite-vs-postgres-gotchas.md for SQLite-specific issues.
Alembic picks the engine based on letta.settings.DatabaseChoice and environment variables.
General rules:
just ready handles baseline migrations.LETTA_PG_URI.Workflow for Postgres-targeted migration:
export LETTA_PG_URI=postgresql+pg8000://postgres:postgres@localhost:5432/letta-coreapps/core:
uv run alembic upgrade headuv run alembic revision --autogenerate -m "..."If your local Postgres database has drifted from main (e.g., applied migrations that no longer exist, or has stale schema), you can reset it to generate a clean migration.
From the repo root (/Users/sarahwooders/repos/letta-cloud):
# 1. Remove postgres data directory
rm -rf ./data/postgres
# 2. Stop the running postgres container
docker stop $(docker ps -q --filter ancestor=ankane/pgvector)
# 3. Restart services (creates fresh postgres)
just start-services
# 4. Wait a moment for postgres to be ready, then apply all migrations
cd apps/core
export LETTA_PG_URI=postgresql+pg8000://postgres:postgres@localhost:5432/letta-core
uv run alembic upgrade head
# 5. Now generate your new migration
uv run alembic revision --autogenerate -m "your migration message"
This ensures the migration is generated against a clean database state matching main, avoiding spurious diffs from local-only schema changes.
uv run alembic upgrade head (with appropriate engine/URI).LETTA_PG_URI and rerun.Base.metadata) are correct and that the changed model is imported in Alembic env context.references/migration-commands.md — canonical commands for uv, Alembic, and just.references/sqlite-vs-postgres-gotchas.md — engine-specific pitfalls and how to avoid them.Weekly Installs
–
Source
First Seen
–