this section is a technical overview of the internal API of Alembic. This section is only useful for developers who wish to extend the capabilities of Alembic; for regular users, reading this section is not necessary.
A visualization of the primary features of Alembic’s internals is presented in the following figure. The module and class boxes do not list out all the operations provided by each unit; only a small set of representative elements intended to convey the primary purpose of each system.
The script runner for Alembic is present in the Configuration module.
This module produces a
Config object and passes it to the
appropriate function in Commands. Functions within
Commands will typically instantiate an
ScriptDirectory instance, which represents the collection of
version files, and an
EnvironmentContext, which is a configurational
facade passed to the environment’s
EnvironmentContext object is the primary object used within
env.py script, whose main purpose is that of a facade for creating and using
MigrationContext object, which is the actual migration engine
that refers to a database implementation. The primary method called
on this object within an
env.py script is the
EnvironmentContext.configure() method, which sets up the
MigrationContext with database connectivity and behavioral
configuration. It also supplies methods for transaction demarcation and
migration running, but these methods ultimately call upon the
MigrationContext that’s been configured.
MigrationContext is the gateway to the database
for other parts of the application, and produces a
object which does the actual database communication, and knows how to
create the specific SQL text of the various DDL directives such as
DefaultImpl has subclasses that are per-database-backend.
In “offline” mode (e.g.
produce SQL to a file output stream instead of a database.
During an upgrade or downgrade operation, a specific series of migration
scripts are invoked starting with the
MigrationContext in conjunction
ScriptDirectory; the actual scripts themselves make use
Operations object, which provide the end-user interface to
specific database operations. The
Operations object is generated
based on a series of “operation directive” objects that are user-extensible,
and start out in the alembic.operations.ops.toplevel module.
Another prominent feature of Alembic is the “autogenerate” feature, which
produces new migration scripts that contain Python code. The autogenerate
feature starts in Autogeneration, and is used exclusively
alembic.command.revision() command when the
flag is passed. Autogenerate refers to the
DefaultImpl in order to access database connectivity and
access per-backend rules for autogenerate comparisons. It also makes use
of alembic.operations.ops.toplevel in order to represent the operations that
it will render into scripts.