Overview

Note: 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 env.py script.

The EnvironmentContext object is the primary object used within the env.py script, whose main purpose is that of a facade for creating and using a 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 DefaultImpl object which does the actual database communication, and knows how to create the specific SQL text of the various DDL directives such as ALTER TABLE; DefaultImpl has subclasses that are per-database-backend. In “offline” mode (e.g. --sql), the MigrationContext will 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 with the ScriptDirectory; the actual scripts themselves make use of the 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 Built-in Operation Objects 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 by the alembic.command.revision() command when the --autogenerate flag is passed. Autogenerate refers to the MigrationContext and DefaultImpl in order to access database connectivity and access per-backend rules for autogenerate comparisons. It also makes use of Built-in Operation Objects in order to represent the operations that it will render into scripts.