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.

class alembic.environment.EnvironmentContext(config, script, **kw)¶

Represent the state made available to an env.py script.

EnvironmentContext is normally instantiated by the commands present in the alembic.command module. From within an env.py script, the current EnvironmentContext is available via the alembic.context datamember.

EnvironmentContext is also a Python context manager, that is, is intended to be used using the with: statement. A typical use of EnvironmentContext:

from alembic.config import Config
from alembic.script import ScriptDirectory

config = Config()
config.set_main_option("script_location", "myapp:migrations")
script = ScriptDirectory.from_config(config)

def my_function(rev, context):
    '''do something with revision "rev", which
    will be the current database revision,
    and "context", which is the MigrationContext
    that the env.py will create'''

with EnvironmentContext(
    config,
    script,
    fn = my_function,
    as_sql = False,
    starting_rev = 'base',
    destination_rev = 'head',
    tag = "sometag"
):
    script.run_env()

The above script will invoke the env.py script within the migration environment. If and when env.py calls MigrationContext.run_migrations(), the my_function() function above will be called by the MigrationContext, given the context itself as well as the current revision in the database.

Note

For most API usages other than full blown invocation of migration scripts, the MigrationContext and ScriptDirectory objects can be created and used directly. The EnvironmentContext object is only needed when you need to actually invoke the env.py module present in the migration environment.

Construct a new EnvironmentContext.

Parameters:	config – a `Config` instance. script – a `ScriptDirectory` instance. **kw – keyword options that will be ultimately passed along to the `MigrationContext` when `EnvironmentContext.configure()` is called.

begin_transaction()¶

Return a context manager that will enclose an operation within a “transaction”, as defined by the environment’s offline and transactional DDL settings.

e.g.:

with context.begin_transaction():
    context.run_migrations()

begin_transaction() is intended to “do the right thing” regardless of calling context:

If is_transactional_ddl() is False, returns a “do nothing” context manager which otherwise produces no transactional state or directives.
If is_offline_mode() is True, returns a context manager that will invoke the DefaultImpl.emit_begin() and DefaultImpl.emit_commit() methods, which will produce the string directives BEGIN and COMMIT on the output stream, as rendered by the target backend (e.g. SQL Server would emit BEGIN TRANSACTION).
Otherwise, calls sqlalchemy.engine.Connection.begin() on the current online connection, which returns a sqlalchemy.engine.Transaction object. This object demarcates a real transaction and is itself a context manager, which will roll back if an exception is raised.

Note that a custom env.py script which has more specific transactional needs can of course manipulate the Connection directly to produce transactional state in “online” mode.

config = None¶: An instance of Config representing the configuration file contents as well as other variables set programmatically within it.

configure(connection=None, url=None, dialect_name=None, transactional_ddl=None, output_buffer=None, starting_rev=None, tag=None, template_args=None, target_metadata=None, include_symbol=None, include_schemas=False, compare_type=False, compare_server_default=False, upgrade_token='upgrades', downgrade_token='downgrades', alembic_module_prefix='op.', sqlalchemy_module_prefix='sa.', **kw)¶

Configure a MigrationContext within this EnvironmentContext which will provide database connectivity and other configuration to a series of migration scripts.

Many methods on EnvironmentContext require that this method has been called in order to function, as they ultimately need to have database access or at least access to the dialect in use. Those which do are documented as such.

The important thing needed by configure() is a means to determine what kind of database dialect is in use. An actual connection to that database is needed only if the MigrationContext is to be used in “online” mode.

If the is_offline_mode() function returns True, then no connection is needed here. Otherwise, the connection parameter should be present as an instance of sqlalchemy.engine.Connection.

This function is typically called from the env.py script within a migration environment. It can be called multiple times for an invocation. The most recent Connection for which it was called is the one that will be operated upon by the next call to run_migrations().

General parameters:

Parameters:

connection – a Connection to use for SQL execution in “online” mode. When present, is also used to determine the type of dialect in use.
url – a string database url, or a sqlalchemy.engine.url.URL object. The type of dialect to be used will be derived from this if connection is not passed.
dialect_name – string name of a dialect, such as “postgresql”, “mssql”, etc. The type of dialect to be used will be derived from this if connection and url are not passed.
transactional_ddl – Force the usage of “transactional” DDL on or off; this otherwise defaults to whether or not the dialect in use supports it.
output_buffer – a file-like object that will be used for textual output when the --sql option is used to generate SQL scripts. Defaults to sys.stdout if not passed here and also not present on the Config object. The value here overrides that of the Config object.
starting_rev – Override the “starting revision” argument when using --sql mode.
tag – a string tag for usage by custom env.py scripts. Set via the --tag option, can be overridden here.
template_args – dictionary of template arguments which will be added to the template argument environment when running the “revision” command. Note that the script environment is only run within the “revision” command if the –autogenerate option is used, or if the option “revision_environment=true” is present in the alembic.ini file. New in 0.3.3.
version_table – The name of the Alembic version table. The default is 'alembic_version'.

Parameters specific to the autogenerate feature, when alembic revision is run with the --autogenerate feature:

Parameters:

target_metadata – a sqlalchemy.schema.MetaData object that will be consulted during autogeneration. The tables present will be compared against what is locally available on the target Connection to produce candidate upgrade/downgrade operations.
compare_type –
Indicates type comparison behavior during an autogenerate operation. Defaults to False which disables type comparison. Set to True to turn on default type comparison, which has varied accuracy depending on backend.

To customize type comparison behavior, a callable may be specified which can filter type comparisons during an autogenerate operation. The format of this callable is:
```
def my_compare_type(context, inspected_column,
            metadata_column, inspected_type, metadata_type):
    # return True if the types are different,
    # False if not, or None to allow the default implementation
    # to compare these types
    pass
```
inspected_column is a dictionary structure as returned by sqlalchemy.engine.reflection.Inspector.get_columns(), whereas metadata_column is a sqlalchemy.schema.Column from the local model environment.

A return value of None indicates to allow default type comparison to proceed.
compare_server_default –
Indicates server default comparison behavior during an autogenerate operation. Defaults to False which disables server default comparison. Set to True to turn on server default comparison, which has varied accuracy depending on backend.

To customize server default comparison behavior, a callable may be specified which can filter server default comparisons during an autogenerate operation. defaults during an autogenerate operation. The format of this callable is:
```
def my_compare_server_default(context, inspected_column,
            metadata_column, inspected_default, metadata_default,
            rendered_metadata_default):
    # return True if the defaults are different,
    # False if not, or None to allow the default implementation
    # to compare these defaults
    pass
```
inspected_column is a dictionary structure as returned by sqlalchemy.engine.reflection.Inspector.get_columns(), whereas metadata_column is a sqlalchemy.schema.Column from the local model environment.

A return value of None indicates to allow default server default comparison to proceed. Note that some backends such as Postgresql actually execute the two defaults on the database side to compare for equivalence.

include_symbol –

A callable function which, given a table name and schema name (may be None), returns True or False, indicating if the given table should be considered in the autogenerate sweep. E.g.:

def include_symbol(tablename, schema):
    return tablename not in ("skip_table_one", "skip_table_two")

context.configure(
    # ...
    include_symbol = include_symbol
)

To limit autogenerate to a certain set of schemas when using the include_schemas option:

def include_symbol(tablename, schema):
    return schema in (None, "schema1", "schema2")

context.configure(
    # ...
    include_schemas = True,
    include_symbol = include_symbol
)

New in version 0.3.6.

Changed in version 0.4.0: the include_symbol callable must now also accept a “schema” argument, which may be None.

upgrade_token – When autogenerate completes, the text of the candidate upgrade operations will be present in this template variable when script.py.mako is rendered. Defaults to upgrades.
downgrade_token – When autogenerate completes, the text of the candidate downgrade operations will be present in this template variable when script.py.mako is rendered. Defaults to downgrades.
alembic_module_prefix – When autogenerate refers to Alembic alembic.operations constructs, this prefix will be used (i.e. op.create_table) Defaults to “op.”. Can be None to indicate no prefix.
sqlalchemy_module_prefix – When autogenerate refers to SQLAlchemy Column or type classes, this prefix will be used (i.e. sa.Column("somename", sa.Integer)) Defaults to “sa.”. Can be None to indicate no prefix. Note that when dialect-specific types are rendered, autogenerate will render them using the dialect module name, i.e. mssql.BIT(), postgresql.UUID().
include_schemas –
If True, autogenerate will scan across all schemas located by the SQLAlchemy get_schema_names() method, and include all differences in tables found across all those schemas. When using this option, you may want to also use the include_symbol option to specify a callable which can filter the tables/schemas that get included.

New in version 0.4.0.

Parameters specific to individual backends:

Parameters:

mssql_batch_separator – The “batch separator” which will be placed between each statement when generating offline SQL Server migrations. Defaults to GO. Note this is in addition to the customary semicolon ; at the end of each statement; SQL Server considers the “batch separator” to denote the end of an individual statement execution, and cannot group certain dependent operations in one step.
oracle_batch_separator – The “batch separator” which will be placed between each statement when generating offline Oracle migrations. Defaults to /. Oracle doesn’t add a semicolon between statements like most other backends.

execute(sql, execution_options=None)¶

Execute the given SQL using the current change context.

The behavior of execute() is the same as that of Operations.execute(). Please see that function’s documentation for full detail including caveats and limitations.

This function requires that a MigrationContext has first been made available via configure().

get_bind()¶

Return the current ‘bind’.

In “online” mode, this is the sqlalchemy.engine.Connection currently being used to emit SQL to the database.

This function requires that a MigrationContext has first been made available via configure().

get_context()¶

Return the current MigrationContext object.

If EnvironmentContext.configure() has not been called yet, raises an exception.

get_head_revision()¶

Return the hex identifier of the ‘head’ revision.