migrationimages/alembic-asyncpg-python3.12 repository overview

⁠Run alembic database migrations in a docker image.

This image comes with alembic (by extension SQLAlchemy), asyncpg driver and pydantic-settings pre-installed.

Note that this image only supports running migrations for Postgresql database.

It doesn't matter if your migrations are "sync", e.g. using the Psycopg database driver, the migrations would run just fine.

⁠Mounting migration code

Bind mount (or copy) your alembic folder, database models (so alembic finds them) and alembic.ini file to /migrations.

Then run alembic upgrade head.

⁠How to configure it

Since migrations are application specific, this image doesn't define a way to configure it. Use your own configuration method for your application. For example, if you read config from a file, pass it to the container. If you use environment variables (the "better" way), you can use standard docker methods.

⁠What problem does it solve

Running migrations as part of the server startup is a common practice, but it comes with a set of problems.

Alembic (and database migrations) in general aren't safe to run in parallel (unless you use specific locking mechanism whose behaviour varies by database).

Suppose you want to run multiple instances of your application, which is typical for production, or have an autoscaling policy, this will create problems when migrations are coupled to server startup.

For default deployments of alembic (e.g. you didn't add specific code for handling concurrent invocations of alembic upgrade head either using database exclusive locks or a distributed lock using Redis for example), this would cause some migrations to fail, but it could very well corrupt your database.

⁠Example

This image is best used with docker compose or K8s (using an InitContainer). Here's an example of running migrations after the database is healthy but before the application runs, making sure that the database is already migrated and freeing the application from any checks.

services:
  postgres:
    image: postgres
    restart: always
    environment:
      - POSTGRES_USER=${POSTGRES_USER:?error}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?error}
      - POSTGRES_DB=${POSTGRES_DATABASE:?error}    
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready", "-U", "${POSTGRES_USER}", "-d", "${POSTGRES_DATABASE}" ]
      interval: 10s
      timeout: 5s
      retries: 3

  migrations:
    image: migrationimages/alembic-asyncpg-python3.12
    command: [ "alembic", "upgrade", "head" ]
    env_file:
      # Or however you configure alembic normally.
      - .env
    environment:
      # Or however you configure alembic normally.
      - POSTGRES_USER=${POSTGRES_USER:?error}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?error}
      - POSTGRES_HOST=postgres
    volumes:
      # Keep the same folder structure of your repository.
      # Instead of mounting specific folders, you can mount your whole project directory.
      - project_dir/alembic:/migrations
      - project_dir/alembic.ini:/migrations/alembic.ini
      - project_dir/database/models/migrations/database/models
    depends_on:
      postgres:
        condition: service_healthy

  backend:
    restart: always
    build:
      context: .
    deploy:
      # We can scale the backend independently however we like.
      replicas: 3
    depends_on:
      migrations:
        # The key part: backend runs only if the migrations where successful.
        condition: service_completed_successfully