# Legacy migrations (DEPRECATED — do not add new files here)

This directory holds the **legacy 3.x database migration system**
(`DBMigration` subclasses in `dbmXXX_*.py`, registered via
`@migration.migration_class(N)` and run from `pkg/persistence/mgr.py`).

**This system is frozen. Do not add new `dbmXXX_*.py` migrations.**

The chain is capped at version 25 (`required_database_version = 25` in
`pkg/utils/constants.py`). These files exist only to upgrade pre-existing
3.x databases up to the Alembic baseline (`0001_baseline`). Removing them
would break in-place upgrades from old installations, so they are kept
read-only.

## All new schema changes use Alembic

Migrations now live in `pkg/persistence/alembic/versions/`. To create one:

```bash
uv run python -m langbot.pkg.persistence.alembic_runner autogenerate "description of your change"
```

(requires `data/config.yaml` to exist). Review and edit the generated
script before committing — Alembic migrations run automatically on startup
and must be idempotent and guard against missing tables (the test suite
runs them against empty databases).

### Rules for Alembic revision ids

- Keep the revision id **≤ 32 characters** — PostgreSQL stores
  `alembic_version.version_num` as `varchar(32)` and will raise
  `StringDataRightTruncationError` on overflow.
- Guard every `op` call against a missing table / missing column
  (`inspector.get_table_names()` / `inspector.get_columns()`); fresh
  installs create the schema via `create_all()` and stamp the baseline,
  so migrations may run against tables that already match or do not exist.