Bun Protocol

Migrations and schema change

Routed from skills/SKILL.md. The authoritative operation list is api-reference.md.

There is no migration operation family

NOT-SERVED-FAMILY: bun.migration.* bun.schema.*

Bun Protocol serves no bun.migration.* and no bun.schema.* operation. If you are looking for one, stop looking — it does not exist and must not be invented. Migration is tooling (bunprotocol/migrations/, and Alembic for the backend), and the closest operation-layer surface is the deploy family:

These require the deploy:read / deploy:write permission and do not require tenant context.

The trap that has cost this repository five real defects

The backend is Alembic-managed. SQLModel.metadata.create_all never alters an existing table, so changing a model does not reach the database. A model-only change looks correct in tests that build a fresh schema and silently drifts in any environment that already has the table.

If you add or change a model, write a migration. A drift check exists specifically to catch this omission; run it rather than assuming.

A second, related trap: row-level security policies are DDL, not ORM metadata. Creating tenant-scoped tables through the ORM produces relforcerowsecurity = FALSE unless RLS is applied explicitly afterwards. A table created that way is unprotected while every ORM-level test still passes.

What is proven

PostgreSQL to PostgreSQL migration: proven live with zero data loss, and rollback restores.

Cross-engine migration is NOT proven. Do not describe the protocol as engine-portable.

Reproducing

Ordinary lane, from bunprotocol/:

python -m pytest migrations -p no:logfire -p no:deepeval

The live PostgreSQL-to-PostgreSQL lane requires Docker infrastructure (bash postgres/up.sh) and runs as npm run test:migrations-pg. A skipped live lane is not a pass — if the dependency is missing, the correct outcome is a loud BLOCKED.

Same content for machines: migrations.md · llms.txt