Local Migration Runner (Alembic)

This document provides an example run_local_migrations.py wrapper script. While our default local workflow is schema sync (sync_local_schema.py), some teams prefer running Alembic locally to validate the same migration history that will run in shared environments.

Usage

PYTHONPATH=. python migrations/run_local_migrations.py current
PYTHONPATH=. python migrations/run_local_migrations.py upgrade head
PYTHONPATH=. python migrations/run_local_migrations.py revision --autogenerate -m "Add new table"

Script Implementation

Save this file as migrations/run_local_migrations.py.

import os
import subprocess
import sys
import logging
from dotenv import load_dotenv

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("migrations.run_local_migrations")

load_dotenv(override=True)

APP_ENV = "local"
os.environ["ENVIRONMENT"] = APP_ENV

local_url = os.getenv("DATABASE_URL_LOCAL")
if not local_url:
    logger.error("DATABASE_URL_LOCAL is not set. Cannot continue.")
    sys.exit(1)

os.environ["DATABASE_URL"] = local_url

if len(sys.argv) < 2:
    logger.info("Usage: python migrations/run_local_migrations.py <alembic-args...>")
    logger.info("Examples:")
    logger.info("  python migrations/run_local_migrations.py current")
    logger.info("  python migrations/run_local_migrations.py upgrade head")
    sys.exit(1)

logger.info("Running Alembic in %s: alembic %s", APP_ENV, " ".join(sys.argv[1:]))
subprocess.run(["alembic", *sys.argv[1:]], check=True)