6.8 KiB

Raw Blame History

API Details

This section describes some key functions used within the migration process, particularly those referenced within a migration environment's env.py file.

Overview

The three main objects in use are the .EnvironmentContext, .MigrationContext, and .Operations classes, pictured below.

An Alembic command begins by instantiating an .EnvironmentContext object, then making it available via the alembic.context proxy module. The env.py script, representing a user-configurable migration environment, is then invoked. The env.py script is then responsible for calling upon the .EnvironmentContext.configure, whose job it is to create a .MigrationContext object.

Before this method is called, there's not yet any database connection or dialect-specific state set up. While many methods on .EnvironmentContext are usable at this stage, those which require database access, or at least access to the kind of database dialect in use, are not. Once the .EnvironmentContext.configure method is called, the .EnvironmentContext is said to be configured with database connectivity, available via a new .MigrationContext object. The .MigrationContext is associated with the .EnvironmentContext object via the .EnvironmentContext.get_context method.

Finally, env.py calls upon the .EnvironmentContext.run_migrations method. Within this method, a new .Operations object, which provides an API for individual database migration operations, is established within the alembic.op proxy module. The .Operations object uses the .MigrationContext object ultimately as a source of database connectivity, though in such a way that it does not care if the .MigrationContext is talking to a real database or just writing out SQL to a file.

The Environment Context

The .EnvironmentContext class provides most of the API used within an env.py script. Within env.py, the instantated .EnvironmentContext is made available via a special proxy module called alembic.context. That is, you can import alembic.context like a regular Python module, and each name you call upon it is ultimately routed towards the current .EnvironmentContext in use.

In particular, the key method used within env.py is .EnvironmentContext.configure, which establishes all the details about how the database will be accessed.

alembic.environment

The Migration Context

alembic.migration

The Operations Object

Within migration scripts, actual database migration operations are handled via an instance of .Operations. See ops for an overview of this object.

Commands

Alembic commands are all represented by functions in the alembic.command package. They all accept the same style of usage, being sent the ~.alembic.config.Config object as the first argument.

Commands can be run programmatically, by first constructing a .Config object, as in:

from alembic.config import Config
from alembic import command
alembic_cfg = Config("/path/to/yourapp/alembic.ini")
command.upgrade(alembic_cfg, "head")

In many cases, and perhaps more often than not, an application will wish to call upon a series of Alembic commands and/or other features. It is usually a good idea to link multiple commands along a single connection and transaction, if feasible. This can be achieved using the .Config.attributes dictionary in order to share a connection:

with engine.begin() as connection:
    alembic_cfg.attributes['connection'] = connection
    command.upgrade(alembic_cfg, "head")

This recipe requires that env.py consumes this connection argument; see the example in connection_sharing for details.

To write small API functions that make direct use of database and script directory information, rather than just running one of the built-in commands, use the .ScriptDirectory and .MigrationContext classes directly.

alembic.command

Configuration

The .Config object represents the configuration passed to the Alembic environment. From an API usage perspective, it is needed for the following use cases:

to create a .ScriptDirectory, which allows you to work with the actual script files in a migration environment
to create an .EnvironmentContext, which allows you to actually run the env.py module within the migration environment
to programatically run any of the commands in the alembic.command module.

The .Config is not needed for these cases:

to instantiate a .MigrationContext directly - this object only needs a SQLAlchemy connection or dialect name.
to instantiate a .Operations object - this object only needs a .MigrationContext.

alembic.config

Script Directory

The .ScriptDirectory object provides programmatic access to the Alembic version files present in the filesystem.

alembic.script

Revision

The .RevisionMap object serves as the basis for revision management, used exclusively by .ScriptDirectory.

alembic.revision

Autogeneration

Alembic 0.3 introduces a small portion of the autogeneration system as a public API.

alembic.autogenerate.compare_metadata

DDL Internals

These are some of the constructs used to generate migration instructions. The APIs here build off of the sqlalchemy.schema.DDLElement and sqlalchemy.ext.compiler systems.

For programmatic usage of Alembic's migration directives, the easiest route is to use the higher level functions given by alembic.operations.

alembic.ddl

alembic.ddl.base

alembic.ddl.impl

MySQL

alembic.ddl.mysql

MS-SQL

alembic.ddl.mssql

Postgresql

alembic.ddl.postgresql

SQLite

alembic.ddl.sqlite

6.8 KiB Raw Blame History