letta-server/.skills/db-migrations-schema-changes/references/sqlite-vs-postgres-gotchas.md

SQLite vs Postgres gotchas (letta-cloud core)

SQLite limitations

SQLite has limited support for ALTER TABLE, especially around constraints and foreign keys. In Alembic this often shows up as:

• NotImplementedError: No support for ALTER of constraints in SQLite dialect...

In apps/core, you may hit this when running migrations against SQLite that drop or change foreign keys or constraints.

How to handle

• Prefer running schema-changing migrations against Postgres by setting LETTA_PG_URI and using:

  uv run alembic upgrade head
  

• If you must support SQLite, use Alembic batch mode patterns, but for this project most complex migrations should target Postgres.

Autogenerate differences

Running alembic revision --autogenerate against SQLite vs Postgres can produce different diffs (especially around indexes and constraints).

Recommendations:

• For production/real migrations, always autogenerate against Postgres.
• If you see lots of unexpected index drops/adds, confirm which engine the migration is inspecting and rerun with Postgres.

Engine selection reminder

• Engine is controlled by letta.settings.DatabaseChoice and environment (notably LETTA_PG_URI).
• just ready will also run migrations; ensure your desired engine is set before relying on its database steps.