pytest-sqlalchemy-alembic

A pytest plugin to manage test databases for SQLAlchemy-based projects.

It automatically provisions a dedicated test database per worker and runs Alembic migrations before your test session. Inspired by pytest-django.

How it works

1. The plugin creates an SQLAlchemy test engine for each worker process.
2. Test database is created or reused for each test engine. If --createdb is given, the test database is dropped beforehand.
3. Database schema is populated via Alembic or directly from SQLAlchemy metadata (if --nomigrations is given).
4. If configured, the sessionmaker instance is rebound to the test engine for the duration of the test session.

Requirements

• sqlalchemy >= 2.0
• alembic >= 1.16
• pytest >= 8.4

• pytest-xdist >= 3.0 (Optional)
• pytest-asyncio >= 1.3.0 (Optional)

Supported dialects

Installation

pip install pytest-sqlalchemy-alembic

or

pip install pytest-sqlalchemy-alembic[xdist]  # with pytest-xdist
pip install pytest-sqlalchemy-alembic[async]  # with pytest-asyncio

Minimal configuration

Configuration could be done in pyproject.toml, pytest.ini or via pytest fixture. At least session_maker, engine or engine_url should be specified.

pyproject.toml

[tool.pytest.ini_options]
sqlalchemy_alembic_configs = [
  {session_maker = "example_project_async.db:AsyncSessionLocal"},
]

In TOML, array of tables should be used to provide config values

pytest.ini

[pytest]
sqlalchemy_alembic_configs =
  {"session_maker": "example_project.db:SessionLocal"}

In INI each line should be a valid JSON object

conftest.py

import pytest
from pytest_sqlalchemy_alembic.config import PluginConfig
from example_project.db import SessionLocal

@pytest.fixture(scope='session')
def sqlalchemy_alembic_plugin_configs(pytestconfig: pytest.Config) -> list[PluginConfig]:
    return [
        PluginConfig.build(
            session_maker=SessionLocal,
            create_db=pytestconfig.getoption('create_db'),
            no_migrations=pytestconfig.getoption('no_migrations'),
        )
    ]

Full list of configuration options

Config file options

Fixture override options

Arguments of PluginConfig.build class method to use in the sqlalchemy_alembic_plugin_configs fixture.

Usage

When configured, the plugin binds your sessionmaker to the test database automatically.

# services.py
from example_project.db import SessionLocal

def my_service():
    with SessionLocal() as db:
        return db.scalar(...)

# test_services.py
from example_project.services import my_service

def test_my_service():
    my_service()  # <-- test database will be used

Pytest run flags

Fixtures