Alembic integration
Using Alembic with SQLAlchemy bind manager
Alembic is a database migration tool widely used with SQLAlchemy.
While the installation and configuration of Alembic is not
in the scope of this package, SQLAlchemyBindManager class
provides the method get_bind_mappers_metadata() for an easier
integration with Alembic when using multiple binds. It will
return each bind metadata organised in a dictionary, using
the bind names as keys.
Alembic provides templates for synchronous engines and for asynchronous engines, but there is no template supporting both at the same time.
You can find an example Alembic configuration that works
with synchronous and asynchronous engines at the same time,
using the SQLAlchemyBindManager helper method, based on
the following directory structure:
├── alembic
│ ├── env.py
│ ├── script.py.mako
│ └── versions
└── alembic.ini
alembic.ini
alembic.ini
# a multi-database configuration.
[alembic]
# path to migration scripts
script_location = alembic
# template used to generate migration file names; The default value is %%(rev)s_%%(slug)s
# Uncomment the line below if you want the files to be prepended with date and time
# see https://alembic.sqlalchemy.org/en/latest/tutorial.html#editing-the-ini-file
# for all available tokens
file_template = %%(year)d-%%(month).2d-%%(day).2d-%%(hour).2d%%(minute).2d%%(second).2d-%%(rev)s_%%(slug)s
# sys.path path, will be prepended to sys.path if present.
# defaults to the current working directory.
prepend_sys_path = .
# timezone to use when rendering the date within the migration file
# as well as the filename.
# If specified, requires the python-dateutil library that can be
# installed by adding `alembic[tz]` to the pip requirements
# string value is passed to dateutil.tz.gettz()
# leave blank for localtime
# timezone =
# max length of characters to apply to the
# "slug" field
# truncate_slug_length = 40
# set to 'true' to run the environment during
# the 'revision' command, regardless of autogenerate
# revision_environment = false
# set to 'true' to allow .pyc and .pyo files without
# a source .py file to be detected as revisions in the
# versions/ directory
# sourceless = false
# version location specification; This defaults
# to alembic/versions. When using multiple version
# directories, initial revisions must be specified with --version-path.
# The path separator used here should be the separator specified by "version_path_separator" below.
# version_locations = %(here)s/bar:%(here)s/bat:alembic/versions
# version path separator; As mentioned above, this is the character used to split
# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
# Valid values for version_path_separator are:
#
# version_path_separator = :
# version_path_separator = ;
# version_path_separator = space
version_path_separator = os # Use os.pathsep. Default configuration used for new projects.
# the output encoding used when revision files
# are written from script.py.mako
# output_encoding = utf-8
# We inject db names and config using env.py in alembic directory
#databases = engine1, engine2
#[engine1]
#sqlalchemy.url = driver://user:pass@localhost/dbname
#[engine2]
#sqlalchemy.url = driver://user:pass@localhost/dbname2
[post_write_hooks]
# post_write_hooks defines scripts or Python functions that are run
# on newly generated revision scripts. See the documentation for further
# detail and examples
# format using "black" - use the console_scripts runner, against the "black" entrypoint
# hooks = black
# black.type = console_scripts
# black.entrypoint = black
# black.options = -l 79 REVISION_SCRIPT_FILENAME
env.py
env.py
import logging
import os
from asyncio import get_event_loop
from alembic import context
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.asyncio import AsyncEngine
from sqlalchemy_bind_manager import SQLAlchemyConfig, SQLAlchemyBindManager
################################################################
## Note: The bind_config, sa_manager and models are normally ##
## implemented in an application. This is only an example! ##
################################################################
bind_config = {
"default": SQLAlchemyConfig(
engine_url=f"sqlite+aiosqlite:///{os.path.dirname(os.path.abspath(__file__))}/sqlite.db",
engine_options=dict(
connect_args={
"check_same_thread": False,
},
echo=False,
future=True,
),
async_engine=True,
),
}
sa_manager = SQLAlchemyBindManager(config=bind_config)
class BookModel(sa_manager.get_bind().declarative_base):
id = Column(Integer)
title = Column(String)
################################################################
## Note: The bind_config, sa_manager and models are normally ##
## implemented in an application. This is only an example! ##
################################################################
USE_TWOPHASE = False
# this is the Alembic Config object, which provides
# access to the values within the .ini file in use.
config = context.config
logger = logging.getLogger("alembic.env")
target_metadata = sa_manager.get_bind_mappers_metadata()
db_names = target_metadata.keys()
config.set_main_option("databases", ",".join(db_names))
def run_migrations_offline() -> None:
"""Run migrations in 'offline' mode.
This configures the context with just a URL
and not an Engine, though an Engine is acceptable
here as well. By skipping the Engine creation
we don't even need a DBAPI to be available.
Calls to context.execute() here emit the given string to the
script output.
"""
# for the --sql use case, run migrations for each URL into
# individual files.
engines = {}
for name in db_names:
engines[name] = {}
engines[name]["url"] = sa_manager.get_bind(name).engine.url
for name, rec in engines.items():
logger.info(f"Migrating database {name}")
file_ = f"{name}.sql"
logger.info(f"Writing output to {file_}")
with open(file_, "w") as buffer:
context.configure(
url=rec["url"],
output_buffer=buffer,
target_metadata=target_metadata.get(name),
literal_binds=True,
dialect_opts={"paramstyle": "named"},
)
with context.begin_transaction():
context.run_migrations(engine_name=name)
def do_run_migration(conn, name):
context.configure(
connection=conn,
upgrade_token=f"{name}_upgrades",
downgrade_token=f"{name}_downgrades",
target_metadata=target_metadata.get(name),
)
context.run_migrations(engine_name=name)
async def run_migrations_online() -> None:
"""Run migrations in 'online' mode.
In this scenario we need to create an Engine
and associate a connection with the context.
"""
# for the direct-to-DB use case, start a transaction on all
# engines, then run all migrations, then commit all transactions.
engines = {}
for name in db_names:
engines[name] = {}
engines[name]["engine"] = sa_manager.get_bind(name).engine
for name, rec in engines.items():
engine = rec["engine"]
if isinstance(engine, AsyncEngine):
rec["connection"] = conn = await engine.connect()
if USE_TWOPHASE:
rec["transaction"] = await conn.begin_twophase()
else:
rec["transaction"] = await conn.begin()
else:
rec["connection"] = conn = engine.connect()
if USE_TWOPHASE:
rec["transaction"] = conn.begin_twophase()
else:
rec["transaction"] = conn.begin()
try:
for name, rec in engines.items():
logger.info(f"Migrating database {name}")
if isinstance(rec["engine"], AsyncEngine):
def migration_callable(*args, **kwargs):
return do_run_migration(*args, name=name, **kwargs)
await rec["connection"].run_sync(migration_callable)
else:
do_run_migration(name, rec)
if USE_TWOPHASE:
for rec in engines.values():
if isinstance(rec["engine"], AsyncEngine):
await rec["transaction"].prepare()
else:
rec["transaction"].prepare()
for rec in engines.values():
if isinstance(rec["engine"], AsyncEngine):
await rec["transaction"].commit()
else:
rec["transaction"].commit()
except:
for rec in engines.values():
if isinstance(rec["engine"], AsyncEngine):
await rec["transaction"].rollback()
else:
rec["transaction"].rollback()
raise
finally:
for rec in engines.values():
if isinstance(rec["engine"], AsyncEngine):
await rec["connection"].close()
else:
rec["connection"].close()
if context.is_offline_mode():
run_migrations_offline()
else:
loop = get_event_loop()
if loop.is_running():
loop.create_task(run_migrations_online())
else:
loop.run_until_complete(run_migrations_online())
script.py.mako
script.py.mako
<%!
import re
%>"""${message}
Revision ID: ${up_revision}
Revises: ${down_revision | comma,n}
Create Date: ${create_date}
"""
from alembic import op
import sqlalchemy as sa
${imports if imports else ""}
# revision identifiers, used by Alembic.
revision = ${repr(up_revision)}
down_revision = ${repr(down_revision)}
branch_labels = ${repr(branch_labels)}
depends_on = ${repr(depends_on)}
def upgrade(engine_name: str) -> None:
globals()[f"upgrade_{engine_name}"]()
def downgrade(engine_name: str) -> None:
globals()[f"downgrade_{engine_name}"]()
<%
db_names = config.get_main_option("databases")
%>
## generate an "upgrade_<xyz>() / downgrade_<xyz>()" function
## for each database name in the ini file.
% for db_name in re.split(r',\s*', db_names):
def upgrade_${db_name}() -> None:
${context.get(f"{db_name}_upgrades", "pass")}
def downgrade_${db_name}() -> None:
${context.get(f"{db_name}_downgrades", "pass")}
% endfor