litellm/litellm-proxy-extras/migration_runbook.md

Database Migration Runbook

This is a runbook for creating and running database migrations for the LiteLLM proxy. For use for litellm engineers only.

Quick Start

# Install deps (one time)
pip install testing.postgresql
brew install postgresql@14  # macOS

# Add to PATH
export PATH="/opt/homebrew/opt/postgresql@14/bin:$PATH"

# Run migration
python ci_cd/run_migration.py "your_migration_name"

What It Does

1. Creates temp PostgreSQL DB
2. Applies existing migrations
3. Compares with schema.prisma
4. Generates new migration if changes found

Common Fixes

Missing testing module:

pip install testing.postgresql

initdb not found:

brew install postgresql@14
export PATH="/opt/homebrew/opt/postgresql@14/bin:$PATH"

Empty migration directory error:

rm -rf litellm-proxy-extras/litellm_proxy_extras/migrations/[empty_dir]

Rules

• Update schema.prisma first
• Review generated SQL before committing
• Use descriptive migration names
• Never edit existing migration files
• Commit schema + migration together