Imported from jyatesdotdev/nexus (nexus-mcp/alembic/AGENTS.md). Install upstream with npx skills add jyatesdotdev/nexus --skill alembic. Copyright stays with the author.

alembic/ — database migration environment for nexus-mcp

This directory is the Alembic migration environment for the nexus-mcp HR Directory MCP server (the parent directory). The application's data model is the single User SQLModel in ../database.py (table users), stored in SQLite (../hr.db by default) or whatever DATABASE_URL points at. Alembic commands must be run from the REPO ROOT (one level up), because ../alembic.ini sets prepend_sys_path = . so that env.py can import database.

Fixed and verified 2026-07: the migration chain builds the schema from scratch. The sole revision (668e2bd0edd6) is a proper baseline that CREATEs the users table, alembic upgrade head succeeds on a fresh, empty database, the resulting schema is byte-identical to what SQLModel.metadata.create_all() produces, and alembic check reports no model/migration drift. env.py enables render_as_batch=True so future ALTER COLUMN migrations work on SQLite.

How Alembic and the import-time create_all coexist

Importing server.py runs database.init_db(), which calls SQLModel.metadata.create_all(engine) and seeds 4 mock users. create_all only creates tables that are missing, so the two schema paths compose safely in either order:

• Fresh DB via Alembic: alembic upgrade head creates users and records the version; the server's later create_all is a no-op and init_db() seeds.
• Fresh DB via server startup: create_all makes the schema but Alembic does not know that. Before ever running alembic upgrade against such a database, mark it as already at the baseline with alembic stamp head (writes the head revision id into alembic_version without executing migrations). The local ../hr.db has been stamped this way.
• Future schema changes: add a new revision AND update the User model; on existing DBs run alembic upgrade head BEFORE starting the server. Note create_all never alters existing tables, so migrations are the only path that upgrades an existing database — and Alembic migrations never seed data, which is why the init_db() call in server.py must stay.

Files at this level

• env.py — the migration runtime. It imports DATABASE_URL and SQLModel.metadata from database.py at the repo root and overrides the sqlalchemy.url placeholder in alembic.ini, so the target database always follows the application's DATABASE_URL env var (default sqlite:///hr.db). target_metadata = SQLModel.metadata enables --autogenerate. It passes render_as_batch=True to context.configure() in both the offline and online paths, so ALTER-style migrations are emitted as SQLite-compatible batch (table-rebuild) operations; keep that flag.
• script.py.mako — template used by alembic revision to generate new revision files. New revisions import sqlmodel types when autogenerated from SQLModel models; leave the template alone unless you know Alembic templating.
• README — stock one-line Alembic placeholder; no content of value.
• versions/ — the revision scripts themselves. See versions/AGENTS.md.

Commands (run from the repo root, not from this directory)

# create a new revision after changing the User model in database.py
uv run alembic revision --autogenerate -m "describe change"

# apply migrations to a specific database
DATABASE_URL="sqlite:///hr.db" uv run alembic upgrade head

# mark an existing create_all-made database as already at head
DATABASE_URL="sqlite:///hr.db" uv run alembic stamp head

(uv run resolves alembic from the shared workspace .venv at the repo root; run uv sync there first if the environment is missing.)

Caution / do not modify

• Never rewrite a revision that is already part of history; create a new revision instead.
• Every new revision must chain correctly: its down_revision must be the current head.
• A schema change is two edits: the User model in ../database.py AND a new revision here. Changing only one leaves the model and migration history out of sync.
• Do not run alembic upgrade against an existing database whose schema was created by create_all without stamping it first (see the coexistence section above).