Runtime Objects

The “runtime” of Alembic involves the EnvironmentContext and MigrationContext objects. These are the objects that are in play once the env.py script is loaded up by a command and a migration operation proceeds.

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.runtime.environment.EnvironmentContext(config, script, **kw)

A configurational facade made available in an env.py script.

The EnvironmentContext acts as a facade to the more nuts-and-bolts objects of MigrationContext as well as certain aspects of Config, within the context of the env.py script that is invoked by most Alembic commands.

EnvironmentContext is normally instantiated when a command in alembic.command is run. It then makes itself available in the alembic.context module for the scope of the command. From within an env.py script, the current EnvironmentContext is available by importing this module.

EnvironmentContext also supports programmatic usage. At this level, it acts as 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:
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:

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, transaction_per_migration=False, output_buffer=None, starting_rev=None, tag=None, template_args=None, render_as_batch=False, target_metadata=None, include_symbol=None, include_object=None, include_schemas=False, process_revision_directives=None, compare_type=False, compare_server_default=False, render_item=None, literal_binds=False, upgrade_token='upgrades', downgrade_token='downgrades', alembic_module_prefix='op.', sqlalchemy_module_prefix='sa.', user_module_prefix=None, **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.
  • transaction_per_migration

    if True, nest each migration script in a transaction rather than the full series of migrations to run.

    New in version 0.6.5.

  • 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.
  • output_encoding – when using --sql to generate SQL scripts, apply this encoding to the string output.
  • literal_binds

    when using --sql to generate SQL scripts, pass through the literal_binds flag to the compiler so that any literal values that would ordinarily be bound parameters are converted to plain strings.

    Warning

    Dialects can typically only handle simple datatypes like strings and numbers for auto-literal generation. Datatypes like dates, intervals, and others may still require manual formatting, typically using Operations.inline_literal().

    Note

    the literal_binds flag is ignored on SQLAlchemy versions prior to 0.8 where this feature is not supported.

    New in version 0.7.6.

  • 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.
  • version_table – The name of the Alembic version table. The default is 'alembic_version'.
  • version_table_schema – Optional schema to place version table within.
  • version_table_pk

    boolean, whether the Alembic version table should use a primary key constraint for the “value” column; this only takes effect when the table is first created. Defaults to True; setting to False should not be necessary and is here for backwards compatibility reasons.

    New in version 0.8.10: Added the EnvironmentContext.configure.version_table_pk flag and additionally established that the Alembic version table has a primary key constraint by default.

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

Parameters:
  • target_metadata

    a sqlalchemy.schema.MetaData object, or a sequence of MetaData objects, that will be consulted during autogeneration. The tables present in each MetaData will be compared against what is locally available on the target Connection to produce candidate upgrade/downgrade operations.

    Changed in version 0.9.0: the EnvironmentContext.configure.target_metadata parameter may now be passed a sequence of MetaData objects to support autogeneration of multiple MetaData collections.

  • 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. See Comparing Types for an example as well as information on other type comparison options.

  • 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
        return None
    
    context.configure(
        # ...
        compare_server_default = my_compare_server_default
    )
    

    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_object

    A callable function which is given the chance to return True or False for any object, indicating if the given object should be considered in the autogenerate sweep.

    The function accepts the following positional arguments:

    • object: a SchemaItem object such as a Table, Column, Index UniqueConstraint, or ForeignKeyConstraint object
    • name: the name of the object. This is typically available via object.name.
    • type: a string describing the type of object; currently "table", "column", "index", "unique_constraint", or "foreign_key_constraint"

      New in version 0.7.0: Support for indexes and unique constraints within the include_object hook.

      New in version 0.7.1: Support for foreign keys within the include_object hook.

    • reflected: True if the given object was produced based on table reflection, False if it’s from a local MetaData object.
    • compare_to: the object being compared against, if available, else None.

    E.g.:

    def include_object(object, name, type_, reflected, compare_to):
        if (type_ == "column" and
            not reflected and
            object.info.get("skip_autogenerate", False)):
            return False
        else:
            return True
    
    context.configure(
        # ...
        include_object = include_object
    )
    

    EnvironmentContext.configure.include_object can also be used to filter on specific schemas to include or omit, when the EnvironmentContext.configure.include_schemas flag is set to True. The Table.schema attribute on each Table object reflected will indicate the name of the schema from which the Table originates.

    New in version 0.6.0.

  • 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.

    Deprecated since version 0.6.0: EnvironmentContext.configure.include_symbol is superceded by the more generic EnvironmentContext.configure.include_object parameter.

    E.g.:

    def include_symbol(tablename, schema):
        return tablename not in ("skip_table_one", "skip_table_two")
    
    context.configure(
        # ...
        include_symbol = include_symbol
    )
    
  • render_as_batch

    if True, commands which alter elements within a table will be placed under a with batch_alter_table(): directive, so that batch migrations will take place.

    New in version 0.7.0.

  • 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 EnvironmentContext.configure.include_object option to specify a callable which can filter the tables/schemas that get included.

  • render_item

    Callable that can be used to override how any schema item, i.e. column, constraint, type, etc., is rendered for autogenerate. The callable receives a string describing the type of object, the object, and the autogen context. If it returns False, the default rendering method will be used. If it returns None, the item will not be rendered in the context of a Table construct, that is, can be used to skip columns or constraints within op.create_table():

    def my_render_column(type_, col, autogen_context):
        if type_ == "column" and isinstance(col, MySpecialCol):
            return repr(col)
        else:
            return False
    
    context.configure(
        # ...
        render_item = my_render_column
    )
    

    Available values for the type string include: "column", "primary_key", "foreign_key", "unique", "check", "type", "server_default".

  • 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().
  • user_module_prefix

    When autogenerate refers to a SQLAlchemy type (e.g. TypeEngine) where the module name is not under the sqlalchemy namespace, this prefix will be used within autogenerate. If left at its default of None, the __module__ attribute of the type is used to render the import module. It’s a good practice to set this and to have all custom types be available from a fixed module space, in order to future-proof migration files against reorganizations in modules.

    Changed in version 0.7.0: EnvironmentContext.configure.user_module_prefix no longer defaults to the value of EnvironmentContext.configure.sqlalchemy_module_prefix when left at None; the __module__ attribute is now used.

  • process_revision_directives

    a callable function that will be passed a structure representing the end result of an autogenerate or plain “revision” operation, which can be manipulated to affect how the alembic revision command ultimately outputs new revision scripts. The structure of the callable is:

    def process_revision_directives(context, revision, directives):
        pass
    

    The directives parameter is a Python list containing a single MigrationScript directive, which represents the revision file to be generated. This list as well as its contents may be freely modified to produce any set of commands. The section Customizing Revision Generation shows an example of doing this. The context parameter is the MigrationContext in use, and revision is a tuple of revision identifiers representing the current revision of the database.

    The callable is invoked at all times when the --autogenerate option is passed to alembic revision. If --autogenerate is not passed, the callable is invoked only if the revision_environment variable is set to True in the Alembic configuration, in which case the given directives collection will contain empty UpgradeOps and DowngradeOps collections for .upgrade_ops and .downgrade_ops. The --autogenerate option itself can be inferred by inspecting context.config.cmd_opts.autogenerate.

    The callable function may optionally be an instance of a Rewriter object. This is a helper object that assists in the production of autogenerate-stream rewriter functions.

    New in version 0.8.0.

    Changed in version 0.8.1: - The EnvironmentContext.configure.process_revision_directives hook can append op directives into UpgradeOps and DowngradeOps which will be rendered in Python regardless of whether the --autogenerate option is in use or not; the revision_environment configuration variable should be set to “true” in the config to enable this.

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’ script revision.

If the script directory has multiple heads, this method raises a CommandError; EnvironmentContext.get_head_revisions() should be preferred.

This function does not require that the MigrationContext has been configured.

get_head_revisions()

Return the hex identifier of the ‘heads’ script revision(s).

This returns a tuple containing the version number of all heads in the script directory.

This function does not require that the MigrationContext has been configured.

New in version 0.7.0.

get_revision_argument()

Get the ‘destination’ revision argument.

This is typically the argument passed to the upgrade or downgrade command.

If it was specified as head, the actual version number is returned; if specified as base, None is returned.

This function does not require that the MigrationContext has been configured.

get_starting_revision_argument()

Return the ‘starting revision’ argument, if the revision was passed using start:end.

This is only meaningful in “offline” mode. Returns None if no value is available or was configured.

This function does not require that the MigrationContext has been configured.

get_tag_argument()

Return the value passed for the --tag argument, if any.

The --tag argument is not used directly by Alembic, but is available for custom env.py configurations that wish to use it; particularly for offline generation scripts that wish to generate tagged filenames.

This function does not require that the MigrationContext has been configured.

See also

EnvironmentContext.get_x_argument() - a newer and more open ended system of extending env.py scripts via the command line.

get_x_argument(as_dictionary=False)

Return the value(s) passed for the -x argument, if any.

The -x argument is an open ended flag that allows any user-defined value or values to be passed on the command line, then available here for consumption by a custom env.py script.

The return value is a list, returned directly from the argparse structure. If as_dictionary=True is passed, the x arguments are parsed using key=value format into a dictionary that is then returned.

For example, to support passing a database URL on the command line, the standard env.py script can be modified like this:

cmd_line_url = context.get_x_argument(
    as_dictionary=True).get('dbname')
if cmd_line_url:
    engine = create_engine(cmd_line_url)
else:
    engine = engine_from_config(
            config.get_section(config.config_ini_section),
            prefix='sqlalchemy.',
            poolclass=pool.NullPool)

This then takes effect by running the alembic script as:

alembic -x dbname=postgresql://user:pass@host/dbname upgrade head

This function does not require that the MigrationContext has been configured.

New in version 0.6.0.

is_offline_mode()

Return True if the current migrations environment is running in “offline mode”.

This is True or False depending on the the --sql flag passed.

This function does not require that the MigrationContext has been configured.

is_transactional_ddl()

Return True if the context is configured to expect a transactional DDL capable backend.

This defaults to the type of database in use, and can be overridden by the transactional_ddl argument to configure()

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

run_migrations(**kw)

Run migrations as determined by the current command line configuration as well as versioning information present (or not) in the current database connection (if one is present).

The function accepts optional **kw arguments. If these are passed, they are sent directly to the upgrade() and downgrade() functions within each target revision file. By modifying the script.py.mako file so that the upgrade() and downgrade() functions accept arguments, parameters can be passed here so that contextual information, usually information to identify a particular database in use, can be passed from a custom env.py script to the migration functions.

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

script = None

An instance of ScriptDirectory which provides programmatic access to version files within the versions/ directory.

static_output(text)

Emit text directly to the “offline” SQL stream.

Typically this is for emitting comments that start with –. The statement is not treated as a SQL execution, no ; or batch separator is added, etc.

The Migration Context

The MigrationContext handles the actual work to be performed against a database backend as migration operations proceed. It is generally not exposed to the end-user.

class alembic.runtime.migration.MigrationContext(dialect, connection, opts, environment_context=None)

Represent the database state made available to a migration script.

MigrationContext is the front end to an actual database connection, or alternatively a string output stream given a particular database dialect, from an Alembic perspective.

When inside the env.py script, the MigrationContext is available via the EnvironmentContext.get_context() method, which is available at alembic.context:

# from within env.py script
from alembic import context
migration_context = context.get_context()

For usage outside of an env.py script, such as for utility routines that want to check the current version in the database, the MigrationContext.configure() method to create new MigrationContext objects. For example, to get at the current revision in the database using MigrationContext.get_current_revision():

# in any application, outside of an env.py script
from alembic.migration import MigrationContext
from sqlalchemy import create_engine

engine = create_engine("postgresql://mydatabase")
conn = engine.connect()

context = MigrationContext.configure(conn)
current_rev = context.get_current_revision()

The above context can also be used to produce Alembic migration operations with an Operations instance:

# in any application, outside of the normal Alembic environment
from alembic.operations import Operations
op = Operations(context)
op.alter_column("mytable", "somecolumn", nullable=True)
bind

Return the current “bind”.

In online mode, this is an instance of sqlalchemy.engine.Connection, and is suitable for ad-hoc execution of any kind of usage described in SQL Expression Language Tutorial as well as for usage with the sqlalchemy.schema.Table.create() and sqlalchemy.schema.MetaData.create_all() methods of Table, MetaData.

Note that when “standard output” mode is enabled, this bind will be a “mock” connection handler that cannot return results and is only appropriate for a very limited subset of commands.

config

Return the Config used by the current environment, if any.

New in version 0.6.6.

classmethod configure(connection=None, url=None, dialect_name=None, dialect=None, environment_context=None, opts=None)

Create a new MigrationContext.

This is a factory method usually called by EnvironmentContext.configure().

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.
  • opts – dictionary of options. Most other options accepted by EnvironmentContext.configure() are passed via this dictionary.
execute(sql, execution_options=None)

Execute a SQL construct or string statement.

The underlying execution mechanics are used, that is if this is “offline mode” the SQL is written to the output buffer, otherwise the SQL is emitted on the current SQLAlchemy connection.

get_current_heads()

Return a tuple of the current ‘head versions’ that are represented in the target database.

For a migration stream without branches, this will be a single value, synonymous with that of MigrationContext.get_current_revision(). However when multiple unmerged branches exist within the target database, the returned tuple will contain a value for each head.

If this MigrationContext was configured in “offline” mode, that is with as_sql=True, the starting_rev parameter is returned in a one-length tuple.

If no version table is present, or if there are no revisions present, an empty tuple is returned.

New in version 0.7.0.

get_current_revision()

Return the current revision, usually that which is present in the alembic_version table in the database.

This method intends to be used only for a migration stream that does not contain unmerged branches in the target database; if there are multiple branches present, an exception is raised. The MigrationContext.get_current_heads() should be preferred over this method going forward in order to be compatible with branch migration support.

If this MigrationContext was configured in “offline” mode, that is with as_sql=True, the starting_rev parameter is returned instead, if any.

run_migrations(**kw)

Run the migration scripts established for this MigrationContext, if any.

The commands in alembic.command will set up a function that is ultimately passed to the MigrationContext as the fn argument. This function represents the “work” that will be done when MigrationContext.run_migrations() is called, typically from within the env.py script of the migration environment. The “work function” then provides an iterable of version callables and other version information which in the case of the upgrade or downgrade commands are the list of version scripts to invoke. Other commands yield nothing, in the case that a command wants to run some other operation against the database such as the current or stamp commands.

Parameters:**kw – keyword arguments here will be passed to each migration callable, that is the upgrade() or downgrade() method within revision scripts.
stamp(script_directory, revision)

Stamp the version table with a specific revision.

This method calculates those branches to which the given revision can apply, and updates those branches as though they were migrated towards that revision (either up or down). If no current branches include the revision, it is added as a new branch head.

New in version 0.7.0.