db-migrations-schema-changes_skill

Overview

This skill provides practical workflows and commands for managing Alembic database migrations and schema changes in the letta-cloud core app. It focuses on using uv, just, and the LETTA_PG_URI environment variable to target SQLite or Postgres. Use it to create, apply, backfill, and fix migrations safely and reproducibly. It emphasizes targeting Postgres for production-like migrations and handling SQLite-specific limitations.

How this skill works

Workflows assume you run from apps/core with Alembic configured under alembic and Python commands executed via uv. Use just ready to prepare the environment and optionally export LETTA_PG_URI to point migrations at a local Postgres instance. Autogenerate revisions with uv run alembic revision --autogenerate and apply changes with uv run alembic upgrade head; for data backfills add Python logic to upgrade() using op.get_bind().

When to use it

• Adding or modifying ORM columns and generating corresponding Alembic revisions.
• Performing one-off data backfills or in-migration data transformations.
• Fixing migrations that fail on SQLite or were generated against the wrong engine.
• Switching migration target between local SQLite and Postgres for accurate diffs.
• Resetting local Postgres to a clean state before generating new migrations.

Best practices

• Prefer running autogenerate against Postgres by exporting LETTA_PG_URI to avoid SQLite ALTER limitations.
• Inspect autogen files in alembic/versions and prefer explicit operations when autogenerate is unclear.
• Create new corrective migrations instead of editing applied revisions in shared environments.
• Use just ready before generating migrations to ensure environment and imports are correct.
• Reset local Postgres when drift causes spurious diffs, then regenerate migrations against the clean DB.

Example use cases

• Add project_id to multiple tables using an existing ProjectMixin and autogenerate the migration.
• Implement a one-off backfill to populate a new column using op.get_bind() in upgrade().
• Resolve a NotImplementedError from SQLite by setting LETTA_PG_URI and rerunning alembic upgrade.
• Regenerate migrations after local schema drift by wiping local Postgres data and restarting services.
• Verify autogenerated revisions import the changed models by checking Base.metadata in Alembic env.