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, transaction_per_migration=False, output_buffer=None, starting_rev=None, tag=None, template_args=None, target_metadata=None, include_symbol=None, include_object=None, include_schemas=False, compare_type=False, compare_server_default=False, render_item=None, 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.

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

New in version 0.5.0.

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
    return None

context.configure(
    # ...
    compare_type = my_compare_type
)
```
inspected_column is a sqlalchemy.schema.Column as returned by sqlalchemy.engine.reflection.Inspector.reflecttable(), 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.

See also

EnvironmentContext.configure.compare_server_default
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.

See also

EnvironmentContext.configure.compare_type
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 or Column object
- name: the name of the object. This is typically available via object.name.
- type: a string describing the type of object; currently "table" or "column"
- 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.

See also

EnvironmentContext.configure.include_schemas
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
)
```
See also

EnvironmentContext.configure.include_schemas

EnvironmentContext.configure.include_object
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.

New in version 0.4.0.

See also

EnvironmentContext.configure.include_object
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".

New in version 0.5.0.

See also

Rendering Custom Types in Autogenerate
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 non-None; if left at its default of None, the EnvironmentContext.configure.sqlalchemy_module_prefix is used instead.

New in version 0.6.3: added EnvironmentContext.configure.user_module_prefix

See also

Controlling the Module Prefix

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.

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

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.

The Migration Context¶

class alembic.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, 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_revision()¶

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

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.

The Operations Object¶

Within migration scripts, actual database migration operations are handled via an instance of Operations. See Operation Reference 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 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")

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.branches(config)¶: Show current un-spliced branch points

alembic.command.current(config, head_only=False)¶: Display the current revision for each database.

alembic.command.downgrade(config, revision, sql=False, tag=None)¶: Revert to a previous version.

alembic.command.history(config, rev_range=None)¶: List changeset scripts in chronological order.

alembic.command.init(config, directory, template='generic')¶: Initialize a new scripts directory.

alembic.command.list_templates(config)¶: List available templates

alembic.command.revision(config, message=None, autogenerate=False, sql=False)¶: Create a new revision file.

alembic.command.splice(config, parent, child)¶

‘splice’ two branches, creating a new revision file.

this command isn’t implemented right now.

alembic.command.stamp(config, revision, sql=False, tag=None)¶: ‘stamp’ the revision table with the given revision; don’t run any migrations.

alembic.command.upgrade(config, revision, sql=False, tag=None)¶: Upgrade to a later version.

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.

class alembic.config.Config(file_=None, ini_section='alembic', output_buffer=None, stdout=<open file '<stdout>', mode 'w' at 0x100254150>, cmd_opts=None)¶

Represent an Alembic configuration.

Within an env.py script, this is available via the EnvironmentContext.config attribute, which in turn is available at alembic.context:

from alembic import context

some_param = context.config.get_main_option("my option")

When invoking Alembic programatically, a new Config can be created by passing the name of an .ini file to the constructor:

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

With a Config object, you can then run Alembic commands programmatically using the directives in alembic.command.

The Config object can also be constructed without a filename. Values can be set programmatically, and new sections will be created as needed:

from alembic.config import Config
alembic_cfg = Config()
alembic_cfg.set_main_option("script_location", "myapp:migrations")
alembic_cfg.set_main_option("url", "postgresql://foo/bar")
alembic_cfg.set_section_option("mysection", "foo", "bar")

Parameters:

file_¶ – name of the .ini file to open.
ini_section¶ – name of the main Alembic section within the .ini file
output_buffer¶ – optional file-like input buffer which will be passed to the MigrationContext - used to redirect the output of “offline generation” when using Alembic programmatically.
stdout¶ –
buffer where the “print” output of commands will be sent. Defaults to sys.stdout.

..versionadded:: 0.4

Construct a new Config

cmd_opts = None¶

The command-line options passed to the alembic script.

Within an env.py script this can be accessed via the EnvironmentContext.config attribute.

New in version 0.6.0.

Script Directory¶

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

class alembic.script.Script(module, rev_id, path)¶

Represent a single revision file in a versions/ directory.

The Script instance is returned by methods such as ScriptDirectory.iterate_revisions().

doc¶: Return the docstring given in the script.

down_revision = None¶: The down_revision identifier within the migration script.

is_branch_point¶

Return True if this Script is a branch point.

A branchpoint is defined as a Script which is referred to by more than one succeeding Script, that is more than one Script has a down_revision identifier pointing here.

is_head¶

Return True if this Script is a ‘head’ revision.

This is determined based on whether any other Script within the ScriptDirectory refers to this Script. Multiple heads can be present.

longdoc¶: Return the docstring given in the script.

module = None¶: The Python module representing the actual script itself.

path = None¶: Filesystem path of the script.

revision = None¶: The string revision number for this Script instance.

class alembic.script.ScriptDirectory(dir, file_template='%(rev)s_%(slug)s', truncate_slug_length=40, sourceless=False)¶

Provides operations upon an Alembic script directory.

This object is useful to get information as to current revisions, most notably being able to get at the “head” revision, for schemes that want to test if the current revision in the database is the most recent:

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

head_revision = script.get_current_head()

as_revision_number(id_)¶: Convert a symbolic revision, i.e. ‘head’ or ‘base’, into an actual revision number.

classmethod from_config(config)¶

Produce a new ScriptDirectory given a Config instance.

The Config need only have the script_location key present.

generate_revision(revid, message, refresh=False, **kw)¶

Generate a new revision file.

This runs the script.py.mako template, given template arguments, and creates a new file.

Parameters:

revid¶ – String revision id. Typically this comes from alembic.util.rev_id().
message¶ – the revision message, the one passed by the -m argument to the revision command.
refresh¶ – when True, the in-memory state of this ScriptDirectory will be updated with a new Script instance representing the new revision; the Script instance is returned. If False, the file is created but the state of the ScriptDirectory is unmodified; None is returned.

get_base()¶

Return the “base” revision as a string.

This is the revision number of the script that has a down_revision of None.

Behavior is not defined if more than one script has a down_revision of None.

get_current_head()¶

Return the current head revision.

If the script directory has multiple heads due to branching, an error is raised.

Returns a string revision number.

get_heads()¶

Return all “head” revisions as strings.

Returns a list of string revision numbers.

This is normally a list of length one, unless branches are present. The ScriptDirectory.get_current_head() method can be used normally when a script directory has only one head.

get_revision(id_)¶: Return the Script instance with the given rev id.

iterate_revisions(upper, lower)¶

Iterate through script revisions, starting at the given upper revision identifier and ending at the lower.

The traversal uses strictly the down_revision marker inside each migration script, so it is a requirement that upper >= lower, else you’ll get nothing back.

The iterator yields Script objects.

run_env()¶

Run the script environment.

This basically runs the env.py script present in the migration environment. It is called exclusively by the command functions in alembic.command.

walk_revisions(base='base', head='head')¶

Iterate through all revisions.

This is actually a breadth-first tree traversal, with leaf nodes being heads.

Autogeneration¶

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

alembic.autogenerate.compare_metadata(context, metadata)¶

Compare a database schema to that given in a MetaData instance.

The database connection is presented in the context of a MigrationContext object, which provides database connectivity as well as optional comparison functions to use for datatypes and server defaults - see the “autogenerate” arguments at EnvironmentContext.configure() for details on these.

The return format is a list of “diff” directives, each representing individual differences:

from alembic.migration import MigrationContext
from alembic.autogenerate import compare_metadata
from sqlalchemy.schema import SchemaItem
from sqlalchemy.types import TypeEngine
from sqlalchemy import (create_engine, MetaData, Column,
        Integer, String, Table)
import pprint

engine = create_engine("sqlite://")

engine.execute('''
    create table foo (
        id integer not null primary key,
        old_data varchar,
        x integer
    )''')

engine.execute('''
    create table bar (
        data varchar
    )''')

metadata = MetaData()
Table('foo', metadata,
    Column('id', Integer, primary_key=True),
    Column('data', Integer),
    Column('x', Integer, nullable=False)
)
Table('bat', metadata,
    Column('info', String)
)

mc = MigrationContext.configure(engine.connect())

diff = compare_metadata(mc, metadata)
pprint.pprint(diff, indent=2, width=20)

Output:

[ ( 'add_table',
    Table('bat', MetaData(bind=None),
        Column('info', String(), table=<bat>), schema=None)),
  ( 'remove_table',
    Table(u'bar', MetaData(bind=None),
        Column(u'data', VARCHAR(), table=<bar>), schema=None)),
  ( 'add_column',
    None,
    'foo',
    Column('data', Integer(), table=<foo>)),
  ( 'remove_column',
    None,
    'foo',
    Column(u'old_data', VARCHAR(), table=None)),
  [ ( 'modify_nullable',
      None,
      'foo',
      u'x',
      { 'existing_server_default': None,
        'existing_type': INTEGER()},
      True,
      False)]]

Parameters:	context¶ – a `MigrationContext` instance. metadata¶ – a `MetaData` instance.

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.

class alembic.ddl.base.AddColumn(name, column, schema=None)¶

class alembic.ddl.base.AlterColumn(name, column_name, schema=None, existing_type=None, existing_nullable=None, existing_server_default=None)¶

class alembic.ddl.base.AlterTable(table_name, schema=None)¶

Represent an ALTER TABLE statement.

Only the string name and optional schema name of the table is required, not a full Table object.

class alembic.ddl.base.ColumnDefault(name, column_name, default, **kw)¶

class alembic.ddl.base.ColumnName(name, column_name, newname, **kw)¶

class alembic.ddl.base.ColumnNullable(name, column_name, nullable, **kw)¶

class alembic.ddl.base.ColumnType(name, column_name, type_, **kw)¶

class alembic.ddl.base.DropColumn(name, column, schema=None)¶

class alembic.ddl.base.RenameTable(old_table_name, new_table_name, schema=None)¶

alembic.ddl.base.add_column(compiler, column, **kw)¶

alembic.ddl.base.alter_column(compiler, name)¶

alembic.ddl.base.alter_table(compiler, name, schema)¶

alembic.ddl.base.drop_column(compiler, name)¶

alembic.ddl.base.format_column_name(compiler, name)¶

alembic.ddl.base.format_server_default(compiler, default)¶

alembic.ddl.base.format_table_name(compiler, name, schema)¶

alembic.ddl.base.format_type(compiler, type_)¶

alembic.ddl.base.quote_dotted(name, quote)¶: quote the elements of a dotted name

alembic.ddl.base.visit_add_column(element, compiler, **kw)¶

alembic.ddl.base.visit_column_default(element, compiler, **kw)¶

alembic.ddl.base.visit_column_name(element, compiler, **kw)¶

alembic.ddl.base.visit_column_nullable(element, compiler, **kw)¶

alembic.ddl.base.visit_column_type(element, compiler, **kw)¶

alembic.ddl.base.visit_drop_column(element, compiler, **kw)¶

alembic.ddl.base.visit_rename_table(element, compiler, **kw)¶

class alembic.ddl.impl.DefaultImpl(dialect, connection, as_sql, transactional_ddl, output_buffer, context_opts)¶

Provide the entrypoint for major migration operations, including database-specific behavioral variances.

While individual SQL/DDL constructs already provide for database-specific implementations, variances here allow for entirely different sequences of operations to take place for a particular migration, such as SQL Server’s special ‘IDENTITY INSERT’ step for bulk inserts.

add_column(table_name, column, schema=None)¶

add_constraint(const)¶

alter_column(table_name, column_name, nullable=None, server_default=False, name=None, type_=None, schema=None, autoincrement=None, existing_type=None, existing_server_default=None, existing_nullable=None, existing_autoincrement=None)¶

bind¶

bulk_insert(table, rows, multiinsert=True)¶

command_terminator = ';'¶

compare_server_default(inspector_column, metadata_column, rendered_metadata_default, rendered_inspector_default)¶

compare_type(inspector_column, metadata_column)¶

correct_for_autogen_constraints(conn_uniques, conn_indexes, metadata_unique_constraints, metadata_indexes)¶

create_index(index)¶

create_table(table)¶

drop_column(table_name, column, schema=None, **kw)¶

drop_constraint(const)¶

drop_index(index)¶

drop_table(table)¶

emit_begin()¶

Emit the string BEGIN, or the backend-specific equivalent, on the current connection context.

This is used in offline mode and typically via EnvironmentContext.begin_transaction().

emit_commit()¶

Emit the string COMMIT, or the backend-specific equivalent, on the current connection context.

This is used in offline mode and typically via EnvironmentContext.begin_transaction().

execute(sql, execution_options=None)¶

classmethod get_by_dialect(dialect)¶

rename_table(old_table_name, new_table_name, schema=None)¶

start_migrations()¶

A hook called when EnvironmentContext.run_migrations() is called.

Implementations can set up per-migration-run state here.

static_output(text)¶

transactional_ddl = False¶

class alembic.ddl.impl.ImplMeta(classname, bases, dict_)¶

alembic.ddl.impl.text(text, bind=None, bindparams=None, typemap=None, autocommit=None)¶

Construct a new TextClause clause, representing a textual SQL string directly.

E.g.:

fom sqlalchemy import text

t = text("SELECT * FROM users")
result = connection.execute(t)

The advantages text() provides over a plain string are backend-neutral support for bind parameters, per-statement execution options, as well as bind parameter and result-column typing behavior, allowing SQLAlchemy type constructs to play a role when executing a statement that is specified literally. The construct can also be provided with a .c collection of column elements, allowing it to be embedded in other SQL expression constructs as a subquery.

Bind parameters are specified by name, using the format :name. E.g.:

t = text("SELECT * FROM users WHERE id=:user_id")
result = connection.execute(t, user_id=12)

For SQL statements where a colon is required verbatim, as within an inline string, use a backslash to escape:

t = text("SELECT * FROM users WHERE name='\:username'")

The TextClause construct includes methods which can provide information about the bound parameters as well as the column values which would be returned from the textual statement, assuming it’s an executable SELECT type of statement. The TextClause.bindparams() method is used to provide bound parameter detail, and TextClause.columns() method allows specification of return columns including names and types:

t = text("SELECT * FROM users WHERE id=:user_id").\
        bindparams(user_id=7).\
        columns(id=Integer, name=String)

for id, name in connection.execute(t):
    print(id, name)

The text() construct is used internally in cases when a literal string is specified for part of a larger query, such as when a string is specified to the Select.where() method of Select. In those cases, the same bind parameter syntax is applied:

s = select([users.c.id, users.c.name]).where("id=:user_id")
result = connection.execute(s, user_id=12)

Using text() explicitly usually implies the construction of a full, standalone statement. As such, SQLAlchemy refers to it as an Executable object, and it supports the Executable.execution_options() method. For example, a text() construct that should be subject to “autocommit” can be set explicitly so using the Connection.execution_options.autocommit option:

t = text("EXEC my_procedural_thing()").\
        execution_options(autocommit=True)

Note that SQLAlchemy’s usual “autocommit” behavior applies to text() constructs implicitly - that is, statements which begin with a phrase such as INSERT, UPDATE, DELETE, or a variety of other phrases specific to certain backends, will be eligible for autocommit if no transaction is in progress.

Parameters:

text¶ – the text of the SQL statement to be created. use :<param> to specify bind parameters; they will be compiled to their engine-specific format.
autocommit¶ – Deprecated. Use .execution_options(autocommit=<True|False>) to set the autocommit option.
bind¶ – an optional connection or engine to be used for this text query.
bindparams¶ –
Deprecated. A list of bindparam() instances used to provide information about parameters embedded in the statement. This argument now invokes the TextClause.bindparams() method on the construct before returning it. E.g.:
```
stmt = text("SELECT * FROM table WHERE id=:id",
          bindparams=[bindparam('id', value=5, type_=Integer)])
```
Is equivalent to:
```
stmt = text("SELECT * FROM table WHERE id=:id").\
          bindparams(bindparam('id', value=5, type_=Integer))
```
Deprecated since version 0.9.0: the TextClause.bindparams() method supersedes the bindparams argument to text().

typemap¶ –

Deprecated. A dictionary mapping the names of columns represented in the columns clause of a SELECT statement to type objects, which will be used to perform post-processing on columns within the result set. This parameter now invokes the TextClause.columns() method, which returns a TextAsFrom construct that gains a .c collection and can be embedded in other expressions. E.g.:

stmt = text("SELECT * FROM table",
              typemap={'id': Integer, 'name': String},
          )

Is equivalent to:

stmt = text("SELECT * FROM table").columns(id=Integer,
                                           name=String)

Or alternatively:

from sqlalchemy.sql import column
stmt = text("SELECT * FROM table").columns(
                      column('id', Integer),
                      column('name', String)
                  )

Deprecated since version 0.9.0: the TextClause.columns() method supersedes the typemap argument to text().

MySQL¶

class alembic.ddl.mysql.MySQLAlterDefault(name, column_name, default, schema=None)¶: Bases: alembic.ddl.base.AlterColumn

class alembic.ddl.mysql.MySQLChangeColumn(name, column_name, schema=None, newname=None, type_=None, nullable=None, default=False, autoincrement=None)¶: Bases: alembic.ddl.base.AlterColumn

class alembic.ddl.mysql.MySQLImpl(dialect, connection, as_sql, transactional_ddl, output_buffer, context_opts)¶

Bases: alembic.ddl.impl.DefaultImpl

alter_column(table_name, column_name, nullable=None, server_default=False, name=None, type_=None, schema=None, autoincrement=None, existing_type=None, existing_server_default=None, existing_nullable=None, existing_autoincrement=None)¶

correct_for_autogen_constraints(conn_unique_constraints, conn_indexes, metadata_unique_constraints, metadata_indexes)¶

transactional_ddl = False¶

class alembic.ddl.mysql.MySQLModifyColumn(name, column_name, schema=None, newname=None, type_=None, nullable=None, default=False, autoincrement=None)¶: Bases: alembic.ddl.mysql.MySQLChangeColumn

MS-SQL¶

class alembic.ddl.mssql.MSSQLImpl(*arg, **kw)¶

Bases: alembic.ddl.impl.DefaultImpl

alter_column(table_name, column_name, nullable=None, server_default=False, name=None, type_=None, schema=None, autoincrement=None, existing_type=None, existing_server_default=None, existing_nullable=None, existing_autoincrement=None)¶

batch_separator = 'GO'¶

bulk_insert(table, rows, **kw)¶

drop_column(table_name, column, **kw)¶

emit_begin()¶

emit_commit()¶

transactional_ddl = True¶

alembic.ddl.mssql.mssql_add_column(compiler, column, **kw)¶

alembic.ddl.mssql.visit_add_column(element, compiler, **kw)¶

alembic.ddl.mssql.visit_column_default(element, compiler, **kw)¶

alembic.ddl.mssql.visit_column_nullable(element, compiler, **kw)¶

alembic.ddl.mssql.visit_column_type(element, compiler, **kw)¶

alembic.ddl.mssql.visit_rename_column(element, compiler, **kw)¶

alembic.ddl.mssql.visit_rename_table(element, compiler, **kw)¶

Postgresql¶

class alembic.ddl.postgresql.PostgresqlImpl(dialect, connection, as_sql, transactional_ddl, output_buffer, context_opts)¶

Bases: alembic.ddl.impl.DefaultImpl

compare_server_default(inspector_column, metadata_column, rendered_metadata_default, rendered_inspector_default)¶

transactional_ddl = True¶

alembic.ddl.postgresql.visit_rename_table(element, compiler, **kw)¶

SQLite¶

class alembic.ddl.sqlite.SQLiteImpl(dialect, connection, as_sql, transactional_ddl, output_buffer, context_opts)¶

Bases: alembic.ddl.impl.DefaultImpl

add_constraint(const)¶

compare_server_default(inspector_column, metadata_column, rendered_metadata_default, rendered_inspector_default)¶

correct_for_autogen_constraints(conn_unique_constraints, conn_indexes, metadata_unique_constraints, metadata_indexes)¶

drop_constraint(const)¶

transactional_ddl = False¶: SQLite supports transactional DDL, but pysqlite does not: see: http://bugs.python.org/issue10740

API Details¶

Overview¶

The Environment Context¶

The Migration Context¶

The Operations Object¶

Commands¶

Configuration¶

Script Directory¶

Autogeneration¶

DDL Internals¶

MySQL¶

MS-SQL¶

Postgresql¶

SQLite¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

API Details¶

Overview¶

The Environment Context¶

The Migration Context¶

The Operations Object¶

Commands¶

Configuration¶

Script Directory¶

Autogeneration¶

DDL Internals¶

MySQL¶

MS-SQL¶

Postgresql¶

SQLite¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation