Welcome to Alembic’s documentation!¶

Operations.batch_alter_table()

rename_table(old_table_name, new_table_name, schema=None)¶

Emit an ALTER TABLE to rename a table.

Parameters:	old_table_name – old name. new_table_name – new name. schema – Optional schema name to operate within. To control quoting of the schema outside of the default behavior, use the SQLAlchemy construct `quoted_name`. New in version 0.7.0: ‘schema’ can now accept a `quoted_name` construct.

class alembic.operations.BatchOperations(migration_context, impl=None)¶

Modifies the interface Operations for batch mode.

This basically omits the table_name and schema parameters from associated methods, as these are a given when running under batch mode.

See also

Note that as of 0.8, most of the methods on this class are produced dynamically using the Operations.register_operation() method.

Construct a new Operations

Parameters:	migration_context – a `MigrationContext` instance.

add_column(column)¶: Issue an “add column” instruction using the current batch migration context.

See also

Operations.add_column()

alter_column(column_name, nullable=None, server_default=False, new_column_name=None, type_=None, existing_type=None, existing_server_default=False, existing_nullable=None, **kw)¶: Issue an “alter column” instruction using the current batch migration context.

See also

Operations.add_column()

create_check_constraint(constraint_name, condition, **kw)¶

Issue a “create check constraint” instruction using the current batch migration context.

The batch form of this call omits the source and schema arguments from the call.

See also

Operations.create_check_constraint()

Changed in version 0.8.0: The following positional argument names have been changed:

name -> constraint_name

create_foreign_key(constraint_name, referent_table, local_cols, remote_cols, referent_schema=None, onupdate=None, ondelete=None, deferrable=None, initially=None, match=None, **dialect_kw)¶

Issue a “create foreign key” instruction using the current batch migration context.

The batch form of this call omits the source and source_schema arguments from the call.

e.g.:

with batch_alter_table("address") as batch_op:
    batch_op.create_foreign_key(
                "fk_user_address",
                "user", ["user_id"], ["id"])

See also

Operations.create_foreign_key()

Changed in version 0.8.0: The following positional argument names have been changed:

name -> constraint_name
referent -> referent_table

create_index(index_name, columns, **kw)¶: Issue a “create index” instruction using the current batch migration context.

See also

Operations.create_index()

create_primary_key(constraint_name, columns)¶

Issue a “create primary key” instruction using the current batch migration context.

The batch form of this call omits the table_name and schema arguments from the call.

See also

Operations.create_primary_key()

create_unique_constraint(constraint_name, columns, **kw)¶

Issue a “create unique constraint” instruction using the current batch migration context.

The batch form of this call omits the source and schema arguments from the call.

See also

Operations.create_unique_constraint()

Changed in version 0.8.0: The following positional argument names have been changed:

name -> constraint_name

drop_column(column_name)¶: Issue a “drop column” instruction using the current batch migration context.

See also

Operations.drop_column()

drop_constraint(constraint_name, type_=None)¶

Issue a “drop constraint” instruction using the current batch migration context.

The batch form of this call omits the table_name and schema arguments from the call.

See also

Operations.drop_constraint()

Changed in version 0.8.0: The following positional argument names have been changed:

name -> constraint_name

drop_index(index_name, **kw)¶

Issue a “drop index” instruction using the current batch migration context.

See also

Operations.drop_index()

Changed in version 0.8.0: The following positional argument names have been changed:

name -> index_name

class alembic.operations.MigrateOperation¶

base class for migration command and organization objects.

This system is part of the operation extensibility API.

New in version 0.8.0.

See also

Built-in Operation Objects

EnvironmentContext.get_tag_argument()

info¶: A dictionary that may be used to store arbitrary information along with this MigrateOperation object.

Cookbook¶

A collection of “How-Tos”, highlighting various ways to extend Alembic.

Note

This is a new section where we hope to start cataloguing various “how-tos” we come up with based on user requests. It is often the case that users will request a feature only to learn that simple customization can provide the same thing. There’s only one recipe at the moment but we hope to get more soon!

Building an Up to Date Database from Scratch¶

There’s a theory of database migrations that says that the revisions in existence for a database should be able to go from an entirely blank schema to the finished product, and back again. Alembic can roll this way. Though we think it’s kind of overkill, considering that SQLAlchemy itself can emit the full CREATE statements for any given model using create_all(). If you check out a copy of an application, running this will give you the entire database in one shot, without the need to run through all those migration files, which are instead tailored towards applying incremental changes to an existing database.

Alembic can integrate with a create_all() script quite easily. After running the create operation, tell Alembic to create a new version table, and to stamp it with the most recent revision (i.e. head):

# inside of a "create the database" script, first create
# tables:
my_metadata.create_all(engine)

# then, load the Alembic configuration and generate the
# version table, "stamping" it with the most recent rev:
from alembic.config import Config
from alembic import command
alembic_cfg = Config("/path/to/yourapp/alembic.ini")
command.stamp(alembic_cfg, "head")

When this approach is used, the application can generate the database using normal SQLAlchemy techniques instead of iterating through hundreds of migration scripts. Now, the purpose of the migration scripts is relegated just to movement between versions on out-of-date databases, not new databases. You can now remove old migration files that are no longer represented on any existing environments.

To prune old migration files, simply delete the files. Then, in the earliest, still-remaining migration file, set down_revision to None:

# replace this:
#down_revision = '290696571ad2'

# with this:
down_revision = None

That file now becomes the “base” of the migration series.

Conditional Migration Elements¶

This example features the basic idea of a common need, that of affecting how a migration runs based on command line switches.

The technique to use here is simple; within a migration script, inspect the EnvironmentContext.get_x_argument() collection for any additional, user-defined parameters. Then take action based on the presence of those arguments.

To make it such that the logic to inspect these flags is easy to use and modify, we modify our script.py.mako template to make this feature available in all new revision files:

"""${message}

Revision ID: ${up_revision}
Revises: ${down_revision}
Create Date: ${create_date}

"""

# revision identifiers, used by Alembic.
revision = ${repr(up_revision)}
down_revision = ${repr(down_revision)}

from alembic import op
import sqlalchemy as sa
${imports if imports else ""}

from alembic import context


def upgrade():
    schema_upgrades()
    if context.get_x_argument(as_dictionary=True).get('data', None):
        data_upgrades()

def downgrade():
    if context.get_x_argument(as_dictionary=True).get('data', None):
        data_downgrades()
    schema_downgrades()

def schema_upgrades():
    """schema upgrade migrations go here."""
    ${upgrades if upgrades else "pass"}

def schema_downgrades():
    """schema downgrade migrations go here."""
    ${downgrades if downgrades else "pass"}

def data_upgrades():
    """Add any optional data upgrade migrations here!"""
    pass

def data_downgrades():
    """Add any optional data downgrade migrations here!"""
    pass

Now, when we create a new migration file, the data_upgrades() and data_downgrades() placeholders will be available, where we can add optional data migrations:

"""rev one

Revision ID: 3ba2b522d10d
Revises: None
Create Date: 2014-03-04 18:05:36.992867

"""

# revision identifiers, used by Alembic.
revision = '3ba2b522d10d'
down_revision = None

from alembic import op
import sqlalchemy as sa
from sqlalchemy import String, Column
from sqlalchemy.sql import table, column

from alembic import context

def upgrade():
    schema_upgrades()
    if context.get_x_argument(as_dictionary=True).get('data', None):
        data_upgrades()

def downgrade():
    if context.get_x_argument(as_dictionary=True).get('data', None):
        data_downgrades()
    schema_downgrades()

def schema_upgrades():
    """schema upgrade migrations go here."""
    op.create_table("my_table", Column('data', String))

def schema_downgrades():
    """schema downgrade migrations go here."""
    op.drop_table("my_table")

def data_upgrades():
    """Add any optional data upgrade migrations here!"""

    my_table = table('my_table',
        column('data', String),
    )

    op.bulk_insert(my_table,
        [
            {'data': 'data 1'},
            {'data': 'data 2'},
            {'data': 'data 3'},
        ]
    )

def data_downgrades():
    """Add any optional data downgrade migrations here!"""

    op.execute("delete from my_table")

To invoke our migrations with data included, we use the -x flag:

alembic -x data=true upgrade head

The EnvironmentContext.get_x_argument() is an easy way to support new commandline options within environment and migration scripts.

Replaceable Objects¶

This recipe proposes a hypothetical way of dealing with what we might call a replaceable schema object. A replaceable object is a schema object that needs to be created and dropped all at once. Examples of such objects include views, stored procedures, and triggers.

Replaceable objects present a problem in that in order to make incremental changes to them, we have to refer to the whole definition at once. If we need to add a new column to a view, for example, we have to drop it entirely and recreate it fresh with the extra column added, referring to the whole structure; but to make it even tougher, if we wish to support downgrade operarations in our migration scripts, we need to refer to the previous version of that construct fully, and we’d much rather not have to type out the whole definition in multiple places.

This recipe proposes that we may refer to the older version of a replaceable construct by directly naming the migration version in which it was created, and having a migration refer to that previous file as migrations run. We will also demonstrate how to integrate this logic within the Operation Plugins feature introduced in Alembic 0.8. It may be very helpful to review this section first to get an overview of this API.

The Replaceable Object Structure¶

We first need to devise a simple format that represents the “CREATE XYZ” / “DROP XYZ” aspect of what it is we’re building. We will work with an object that represents a textual definition; while a SQL view is an object that we can define using a table-metadata-like system, this is not so much the case for things like stored procedures, where we pretty much need to have a full string definition written down somewhere. We’ll use a simple value object called ReplaceableObject that can represent any named set of SQL text to send to a “CREATE” statement of some kind:

class ReplaceableObject(object):
    def __init__(self, name, sqltext):
        self.name = name
        self.sqltext = sqltext

Using this object in a migration script, assuming a Postgresql-style syntax, looks like:

customer_view = ReplaceableObject(
    "customer_view",
    "SELECT name, order_count FROM customer WHERE order_count > 0"
)

add_customer_sp = ReplaceableObject(
    "add_customer_sp(name varchar, order_count integer)",
    """
    RETURNS integer AS $$
    BEGIN
        insert into customer (name, order_count)
        VALUES (in_name, in_order_count);
    END;
    $$ LANGUAGE plpgsql;
    """
)

The ReplaceableObject class is only one very simplistic way to do this. The structure of how we represent our schema objects is not too important for the purposes of this example; we can just as well put strings inside of tuples or dictionaries, as well as that we could define any kind of series of fields and class structures we want. The only important part is that below we will illustrate how organize the code that can consume the structure we create here.

Create Operations for the Target Objects¶

We’ll use the Operations extension API to make new operations for create, drop, and replace of views and stored procedures. Using this API is also optional; we can just as well make any kind of Python function that we would invoke from our migration scripts. However, using this API gives us operations built directly into the Alembic op.* namespace very nicely.

The most intricate class is below. This is the base of our “replaceable” operation, which includes not just a base operation for emitting CREATE and DROP instructions on a ReplaceableObject, it also assumes a certain model of “reversibility” which makes use of references to other migration files in order to refer to the “previous” version of an object:

from alembic.operations import Operations, MigrateOperation

class ReversibleOp(MigrateOperation):
    def __init__(self, target):
        self.target = target

    @classmethod
    def invoke_for_target(cls, operations, target):
        op = cls(target)
        return operations.invoke(op)

    def reverse(self):
        raise NotImplementedError()

    @classmethod
    def _get_object_from_version(cls, operations, ident):
        version, objname = ident.split(".")

        module = operations.get_context().script.get_revision(version).module
        obj = getattr(module, objname)
        return obj

    @classmethod
    def replace(cls, operations, target, replaces=None, replace_with=None):

        if replaces:
            old_obj = cls._get_object_from_version(operations, replaces)
            drop_old = cls(old_obj).reverse()
            create_new = cls(target)
        elif replace_with:
            old_obj = cls._get_object_from_version(operations, replace_with)
            drop_old = cls(target).reverse()
            create_new = cls(old_obj)
        else:
            raise TypeError("replaces or replace_with is required")

        operations.invoke(drop_old)
        operations.invoke(create_new)

The workings of this class should become clear as we walk through the example. To create usable operations from this base, we will build a series of stub classes and use Operations.register_operation() to make them part of the op.* namespace:

@Operations.register_operation("create_view", "invoke_for_target")
@Operations.register_operation("replace_view", "replace")
class CreateViewOp(ReversibleOp):
    def reverse(self):
        return DropViewOp(self.target)


@Operations.register_operation("drop_view", "invoke_for_target")
class DropViewOp(ReversibleOp):
    def reverse(self):
        return CreateViewOp(self.view)


@Operations.register_operation("create_sp", "invoke_for_target")
@Operations.register_operation("replace_sp", "replace")
class CreateSPOp(ReversibleOp):
    def reverse(self):
        return DropSPOp(self.target)


@Operations.register_operation("drop_sp", "invoke_for_target")
class DropSPOp(ReversibleOp):
    def reverse(self):
        return CreateSPOp(self.target)

To actually run the SQL like “CREATE VIEW” and “DROP SEQUENCE”, we’ll provide implementations using Operations.implementation_for() that run straight into Operations.execute():

@Operations.implementation_for(CreateViewOp)
def create_view(operations, operation):
    operations.execute("CREATE VIEW %s AS %s" % (
        operation.target.name,
        operation.target.sqltext
    ))


@Operations.implementation_for(DropViewOp)
def drop_view(operations, operation):
    operations.execute("DROP VIEW %s" % operation.target.name)


@Operations.implementation_for(CreateSPOp)
def create_sp(operations, operation):
    operations.execute(
        "CREATE FUNCTION %s %s" % (
            operation.target.name, operation.target.sqltext
        )
    )


@Operations.implementation_for(DropSPOp)
def drop_sp(operations, operation):
    operations.execute("DROP FUNCTION %s" % operation.target.name)

All of the above code can be present anywhere within an application’s source tree; the only requirement is that when the env.py script is invoked, it includes imports that ultimately call upon these classes as well as the Operations.register_operation() and Operations.implementation_for() sequences.

Create Initial Migrations¶

We can now illustrate how these objects look during use. For the first step, we’ll create a new migration to create a “customer” table:

$ alembic revision -m "create table"

We build the first revision as follows:

"""create table

Revision ID: 3ab8b2dfb055
Revises:
Create Date: 2015-07-27 16:22:44.918507

"""

# revision identifiers, used by Alembic.
revision = '3ab8b2dfb055'
down_revision = None
branch_labels = None
depends_on = None

from alembic import op
import sqlalchemy as sa


def upgrade():
    op.create_table(
        "customer",
        sa.Column('id', sa.Integer, primary_key=True),
        sa.Column('name', sa.String),
        sa.Column('order_count', sa.Integer),
    )


def downgrade():
    op.drop_table('customer')

For the second migration, we will create a view and a stored procedure which act upon this table:

$ alembic revision -m "create views/sp"

This migration will use the new directives:

"""create views/sp

Revision ID: 28af9800143f
Revises: 3ab8b2dfb055
Create Date: 2015-07-27 16:24:03.589867

"""

# revision identifiers, used by Alembic.
revision = '28af9800143f'
down_revision = '3ab8b2dfb055'
branch_labels = None
depends_on = None

from alembic import op
import sqlalchemy as sa

from foo import ReplaceableObject

customer_view = ReplaceableObject(
    "customer_view",
    "SELECT name, order_count FROM customer WHERE order_count > 0"
)

add_customer_sp = ReplaceableObject(
    "add_customer_sp(name varchar, order_count integer)",
    """
    RETURNS integer AS $$
    BEGIN
        insert into customer (name, order_count)
        VALUES (in_name, in_order_count);
    END;
    $$ LANGUAGE plpgsql;
    """
)


def upgrade():
    op.create_view(customer_view)
    op.create_sp(add_customer_sp)


def downgrade():
    op.drop_view(customer_view)
    op.drop_sp(add_customer_sp)

We see the use of our new create_view(), create_sp(), drop_view(), and drop_sp() directives. Running these to “head” we get the following (this includes an edited view of SQL emitted):

$ alembic upgrade 28af9800143
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [sqlalchemy.engine.base.Engine] BEGIN (implicit)
INFO  [sqlalchemy.engine.base.Engine] select relname from pg_class c join pg_namespace n on n.oid=c.relnamespace where pg_catalog.pg_table_is_visible(c.oid) and relname=%(name)s
INFO  [sqlalchemy.engine.base.Engine] {'name': u'alembic_version'}
INFO  [sqlalchemy.engine.base.Engine] SELECT alembic_version.version_num
FROM alembic_version
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] select relname from pg_class c join pg_namespace n on n.oid=c.relnamespace where pg_catalog.pg_table_is_visible(c.oid) and relname=%(name)s
INFO  [sqlalchemy.engine.base.Engine] {'name': u'alembic_version'}
INFO  [alembic.runtime.migration] Running upgrade  -> 3ab8b2dfb055, create table
INFO  [sqlalchemy.engine.base.Engine]
CREATE TABLE customer (
    id SERIAL NOT NULL,
    name VARCHAR,
    order_count INTEGER,
    PRIMARY KEY (id)
)


INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] INSERT INTO alembic_version (version_num) VALUES ('3ab8b2dfb055')
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [alembic.runtime.migration] Running upgrade 3ab8b2dfb055 -> 28af9800143f, create views/sp
INFO  [sqlalchemy.engine.base.Engine] CREATE VIEW customer_view AS SELECT name, order_count FROM customer WHERE order_count > 0
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] CREATE FUNCTION add_customer_sp(name varchar, order_count integer)
    RETURNS integer AS $$
    BEGIN
        insert into customer (name, order_count)
        VALUES (in_name, in_order_count);
    END;
    $$ LANGUAGE plpgsql;

INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] UPDATE alembic_version SET version_num='28af9800143f' WHERE alembic_version.version_num = '3ab8b2dfb055'
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] COMMIT

We see that our CREATE TABLE proceeded as well as the CREATE VIEW and CREATE FUNCTION operations produced by our new directives.

Create Revision Migrations¶

Finally, we can illustrate how we would “revise” these objects. Let’s consider we added a new column email to our customer table:

$ alembic revision -m "add email col"

The migration is:

"""add email col

Revision ID: 191a2d20b025
Revises: 28af9800143f
Create Date: 2015-07-27 16:25:59.277326

"""

# revision identifiers, used by Alembic.
revision = '191a2d20b025'
down_revision = '28af9800143f'
branch_labels = None
depends_on = None

from alembic import op
import sqlalchemy as sa


def upgrade():
    op.add_column("customer", sa.Column("email", sa.String()))


def downgrade():
    op.drop_column("customer", "email")

We now need to recreate the customer_view view and the add_customer_sp function. To include downgrade capability, we will need to refer to the previous version of the construct; the replace_view() and replace_sp() operations we’ve created make this possible, by allowing us to refer to a specific, previous revision. the replaces and replace_with arguments accept a dot-separated string, which refers to a revision number and an object name, such as "28af9800143f.customer_view". The ReversibleOp class makes use of the Operations.get_context() method to locate the version file we refer to:

$ alembic revision -m "update views/sp"

The migration:

"""update views/sp

Revision ID: 199028bf9856
Revises: 191a2d20b025
Create Date: 2015-07-27 16:26:31.344504

"""

# revision identifiers, used by Alembic.
revision = '199028bf9856'
down_revision = '191a2d20b025'
branch_labels = None
depends_on = None

from alembic import op
import sqlalchemy as sa

from foo import ReplaceableObject

customer_view = ReplaceableObject(
    "customer_view",
    "SELECT name, order_count, email "
    "FROM customer WHERE order_count > 0"
)

add_customer_sp = ReplaceableObject(
    "add_customer_sp(name varchar, order_count integer, email varchar)",
    """
    RETURNS integer AS $$
    BEGIN
        insert into customer (name, order_count, email)
        VALUES (in_name, in_order_count, email);
    END;
    $$ LANGUAGE plpgsql;
    """
)


def upgrade():
    op.replace_view(customer_view, replaces="28af9800143f.customer_view")
    op.replace_sp(add_customer_sp, replaces="28af9800143f.add_customer_sp")


def downgrade():
    op.replace_view(customer_view, replace_with="28af9800143f.customer_view")
    op.replace_sp(add_customer_sp, replace_with="28af9800143f.add_customer_sp")

Above, instead of using create_view(), create_sp(), drop_view(), and drop_sp() methods, we now use replace_view() and replace_sp(). The replace operation we’ve built always runs a DROP and a CREATE. Running an upgrade to head we see:

$ alembic upgrade head
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [sqlalchemy.engine.base.Engine] BEGIN (implicit)
INFO  [sqlalchemy.engine.base.Engine] select relname from pg_class c join pg_namespace n on n.oid=c.relnamespace where pg_catalog.pg_table_is_visible(c.oid) and relname=%(name)s
INFO  [sqlalchemy.engine.base.Engine] {'name': u'alembic_version'}
INFO  [sqlalchemy.engine.base.Engine] SELECT alembic_version.version_num
FROM alembic_version
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [alembic.runtime.migration] Running upgrade 28af9800143f -> 191a2d20b025, add email col
INFO  [sqlalchemy.engine.base.Engine] ALTER TABLE customer ADD COLUMN email VARCHAR
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] UPDATE alembic_version SET version_num='191a2d20b025' WHERE alembic_version.version_num = '28af9800143f'
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [alembic.runtime.migration] Running upgrade 191a2d20b025 -> 199028bf9856, update views/sp
INFO  [sqlalchemy.engine.base.Engine] DROP VIEW customer_view
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] CREATE VIEW customer_view AS SELECT name, order_count, email FROM customer WHERE order_count > 0
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] DROP FUNCTION add_customer_sp(name varchar, order_count integer)
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] CREATE FUNCTION add_customer_sp(name varchar, order_count integer, email varchar)
    RETURNS integer AS $$
    BEGIN
        insert into customer (name, order_count, email)
        VALUES (in_name, in_order_count, email);
    END;
    $$ LANGUAGE plpgsql;

INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] UPDATE alembic_version SET version_num='199028bf9856' WHERE alembic_version.version_num = '191a2d20b025'
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] COMMIT

After adding our new email column, we see that both customer_view and add_customer_sp() are dropped before the new version is created. If we downgrade back to the old version, we see the old version of these recreated again within the downgrade for this migration:

$ alembic downgrade 28af9800143
INFO  [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO  [alembic.runtime.migration] Will assume transactional DDL.
INFO  [sqlalchemy.engine.base.Engine] BEGIN (implicit)
INFO  [sqlalchemy.engine.base.Engine] select relname from pg_class c join pg_namespace n on n.oid=c.relnamespace where pg_catalog.pg_table_is_visible(c.oid) and relname=%(name)s
INFO  [sqlalchemy.engine.base.Engine] {'name': u'alembic_version'}
INFO  [sqlalchemy.engine.base.Engine] SELECT alembic_version.version_num
FROM alembic_version
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [alembic.runtime.migration] Running downgrade 199028bf9856 -> 191a2d20b025, update views/sp
INFO  [sqlalchemy.engine.base.Engine] DROP VIEW customer_view
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] CREATE VIEW customer_view AS SELECT name, order_count FROM customer WHERE order_count > 0
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] DROP FUNCTION add_customer_sp(name varchar, order_count integer, email varchar)
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] CREATE FUNCTION add_customer_sp(name varchar, order_count integer)
    RETURNS integer AS $$
    BEGIN
        insert into customer (name, order_count)
        VALUES (in_name, in_order_count);
    END;
    $$ LANGUAGE plpgsql;

INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] UPDATE alembic_version SET version_num='191a2d20b025' WHERE alembic_version.version_num = '199028bf9856'
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [alembic.runtime.migration] Running downgrade 191a2d20b025 -> 28af9800143f, add email col
INFO  [sqlalchemy.engine.base.Engine] ALTER TABLE customer DROP COLUMN email
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] UPDATE alembic_version SET version_num='28af9800143f' WHERE alembic_version.version_num = '191a2d20b025'
INFO  [sqlalchemy.engine.base.Engine] {}
INFO  [sqlalchemy.engine.base.Engine] COMMIT

Don’t Generate Empty Migrations with Autogenerate¶

A common request is to have the alembic revision --autogenerate command not actually generate a revision file if no changes to the schema is detected. Using the EnvironmentContext.configure.process_revision_directives hook, this is straightforward; place a process_revision_directives hook in MigrationContext.configure() which removes the single MigrationScript directive if it is empty of any operations:

def run_migrations_online():

    # ...

    def process_revision_directives(context, revision, directives):
        if config.cmd_opts.autogenerate:
            script = directives[0]
            if script.upgrade_ops.is_empty():
                directives[:] = []


    # connectable = ...

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            process_revision_directives=process_revision_directives
        )

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

API Details¶

Alembic’s internal API has many public integration points that can be used to extend Alembic’s functionality as well as to re-use its functionality in new ways. As the project has grown, more APIs are created and exposed for this purpose.

Direct use of the vast majority of API details discussed here is not needed for rudimentary use of Alembic; the only API that is used normally by end users is the methods provided by the Operations class, which is discussed outside of this subsection, and the parameters that can be passed to the EnvironmentContext.configure() method, used when configuring one’s env.py environment. However, real-world applications will usually end up using more of the internal API, in particular being able to run commands programmatically, as discussed in the section Commands.

Overview¶

Note

this section is a technical overview of the internal API of Alembic. This section is only useful for developers who wish to extend the capabilities of Alembic; for regular users, reading this section is not necessary.

A visualization of the primary features of Alembic’s internals is presented in the following figure. The module and class boxes do not list out all the operations provided by each unit; only a small set of representative elements intended to convey the primary purpose of each system.

The script runner for Alembic is present in the Configuration module. This module produces a Config object and passes it to the appropriate function in Commands. Functions within Commands will typically instantiate an ScriptDirectory instance, which represents the collection of version files, and an EnvironmentContext, which is a configurational facade passed to the environment’s env.py script.

The EnvironmentContext object is the primary object used within the env.py script, whose main purpose is that of a facade for creating and using a MigrationContext object, which is the actual migration engine that refers to a database implementation. The primary method called on this object within an env.py script is the EnvironmentContext.configure() method, which sets up the MigrationContext with database connectivity and behavioral configuration. It also supplies methods for transaction demarcation and migration running, but these methods ultimately call upon the MigrationContext that’s been configured.

MigrationContext is the gateway to the database for other parts of the application, and produces a DefaultImpl object which does the actual database communication, and knows how to create the specific SQL text of the various DDL directives such as ALTER TABLE; DefaultImpl has subclasses that are per-database-backend. In “offline” mode (e.g. --sql), the MigrationContext will produce SQL to a file output stream instead of a database.

During an upgrade or downgrade operation, a specific series of migration scripts are invoked starting with the MigrationContext in conjunction with the ScriptDirectory; the actual scripts themselves make use of the Operations object, which provide the end-user interface to specific database operations. The Operations object is generated based on a series of “operation directive” objects that are user-extensible, and start out in the alembic.operations.ops.toplevel module.

Another prominent feature of Alembic is the “autogenerate” feature, which produces new migration scripts that contain Python code. The autogenerate feature starts in Autogeneration, and is used exclusively by the alembic.command.revision() command when the --autogenerate flag is passed. Autogenerate refers to the MigrationContext and DefaultImpl in order to access database connectivity and access per-backend rules for autogenerate comparisons. It also makes use of alembic.operations.ops.toplevel in order to represent the operations that it will render into scripts.

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:	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, 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.

See also

Operations.inline_literal()
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.

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

See also

Comparing Types

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

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

See also

Running “Batch” Migrations for SQLite and Other Databases
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.

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

See also

Affecting the Rendering of Types Themselves
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.

New in version 0.6.3: added EnvironmentContext.configure.user_module_prefix

See also

Controlling the Module Prefix
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.

See also

Customizing Revision Generation

Fine-Grained Autogenerate Generation with Rewriters

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.

See also

Config.cmd_opts

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.

Configuration¶

Note

this section discusses the internal API of Alembic as regards internal configuration constructs. This section is only useful for developers who wish to extend the capabilities of Alembic. For documentation on configuration of an Alembic environment, please see Tutorial.

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 Commands 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'>, cmd_opts=None, config_args=immutabledict({}), attributes=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")

For passing non-string values to environments, such as connections and engines, use the Config.attributes dictionary:

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

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.

New in version 0.4.
config_args –
A dictionary of keys and values that will be used for substitution in the alembic config file. The dictionary as given is copied to a new one, stored locally as the attribute .config_args. When the Config.file_config attribute is first invoked, the replacement variable here will be added to this dictionary before the dictionary is passed to SafeConfigParser() to parse the .ini file.

New in version 0.7.0.
attributes –
optional dictionary of arbitrary Python keys/values, which will be populated into the Config.attributes dictionary.

New in version 0.7.5.

See also

Sharing a Connection with a Series of Migration Commands and Environments

Construct a new Config

attributes¶

A Python dictionary for storage of additional state.

This is a utility dictionary which can include not just strings but engines, connections, schema objects, or anything else. Use this to pass objects into an env.py script, such as passing a sqlalchemy.engine.base.Connection when calling commands from alembic.command programmatically.

New in version 0.7.5.

Config.attributes

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.

See also

EnvironmentContext.get_x_argument()

config_file_name = None¶: Filesystem path to the .ini file in use.

config_ini_section = None¶: Name of the config file section to read basic configuration from. Defaults to alembic, that is the [alembic] section of the .ini file. This value is modified using the -n/--name option to the Alembic runnier.

file_config¶

Return the underlying ConfigParser object.

Direct access to the .ini file is available here, though the Config.get_section() and Config.get_main_option() methods provide a possibly simpler interface.

get_main_option(name, default=None)¶

Return an option from the ‘main’ section of the .ini file.

This defaults to being a key from the [alembic] section, unless the -n/--name flag were used to indicate a different section.

get_section(name)¶: Return all the configuration options from a given .ini file section as a dictionary.

get_section_option(section, name, default=None)¶: Return an option from the given section of the .ini file.

get_template_directory()¶

Return the directory where Alembic setup templates are found.

This method is used by the alembic init and list_templates commands.

print_stdout(text, *arg)¶: Render a message to standard out.

set_main_option(name, value)¶

Set an option programmatically within the ‘main’ section.

This overrides whatever was in the .ini file.

set_section_option(section, name, value)¶

Set an option programmatically within the given section.

The section is created if it doesn’t exist already. The value here will override whatever was in the .ini file.

alembic.config.main(argv=None, prog=None, **kwargs)¶: The console runner function for Alembic.

Commands¶

Note

this section discusses the internal API of Alembic as regards its command invocation system. This section is only useful for developers who wish to extend the capabilities of Alembic. For documentation on using Alembic commands, please see Tutorial.

Alembic commands are all represented by functions in the Commands 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")

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 Sharing a Connection with a Series of Migration Commands and Environments 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.branches(config, verbose=False)¶: Show current branch points

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

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

alembic.command.edit(config, rev)¶: Edit revision script(s) using $EDITOR

alembic.command.heads(config, verbose=False, resolve_dependencies=False)¶: Show current available heads in the script directory

alembic.command.history(config, rev_range=None, verbose=False)¶: 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.merge(config, revisions, message=None, branch_label=None, rev_id=None)¶: Merge two revisions together. Creates a new migration file.

New in version 0.7.0.

See also

branches

alembic.command.revision(config, message=None, autogenerate=False, sql=False, head='head', splice=False, branch_label=None, version_path=None, rev_id=None, depends_on=None)¶: Create a new revision file.

alembic.command.show(config, rev)¶: Show the revision(s) denoted by the given symbol.

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.

Operation Directives¶

Note

this section discusses the internal API of Alembic as regards the internal system of defining migration operation directives. This section is only useful for developers who wish to extend the capabilities of Alembic. For end-user guidance on Alembic migration operations, please see Operation Reference.

Within migration scripts, actual database migration operations are handled via an instance of Operations. The Operations class lists out available migration operations that are linked to a MigrationContext, which communicates instructions originated by the Operations object into SQL that is sent to a database or SQL output stream.

Most methods on the Operations class are generated dynamically using a “plugin” system, described in the next section Operation Plugins. Additionally, when Alembic migration scripts actually run, the methods on the current Operations object are proxied out to the alembic.op module, so that they are available using module-style access.

For an overview of how to use an Operations object directly in programs, as well as for reference to the standard operation methods as well as “batch” methods, see Operation Reference.

Operation Plugins¶

The Operations object is extensible using a plugin system. This system allows one to add new op.<some_operation> methods at runtime. The steps to use this system are to first create a subclass of MigrateOperation, register it using the Operations.register_operation() class decorator, then build a default “implementation” function which is established using the Operations.implementation_for() decorator.

New in version 0.8.0: - the Operations class is now an open namespace that is extensible via the creation of new MigrateOperation subclasses.

Below we illustrate a very simple operation CreateSequenceOp which will implement a new method op.create_sequence() for use in migration scripts:

from alembic.operations import Operations, MigrateOperation

@Operations.register_operation("create_sequence")
class CreateSequenceOp(MigrateOperation):
    """Create a SEQUENCE."""

    def __init__(self, sequence_name, schema=None):
        self.sequence_name = sequence_name
        self.schema = schema

    @classmethod
    def create_sequence(cls, operations, sequence_name, **kw):
        """Issue a "CREATE SEQUENCE" instruction."""

        op = CreateSequenceOp(sequence_name, **kw)
        return operations.invoke(op)

    def reverse(self):
        # only needed to support autogenerate
        return DropSequenceOp(self.sequence_name, schema=self.schema)

@Operations.register_operation("drop_sequence")
class DropSequenceOp(MigrateOperation):
    """Drop a SEQUENCE."""

    def __init__(self, sequence_name, schema=None):
        self.sequence_name = sequence_name
        self.schema = schema

    @classmethod
    def drop_sequence(cls, operations, sequence_name, **kw):
        """Issue a "DROP SEQUENCE" instruction."""

        op = DropSequenceOp(sequence_name, **kw)
        return operations.invoke(op)

    def reverse(self):
        # only needed to support autogenerate
        return CreateSequenceOp(self.sequence_name, schema=self.schema)

Above, the CreateSequenceOp and DropSequenceOp classes represent new operations that will be available as op.create_sequence() and op.drop_sequence(). The reason the operations are represented as stateful classes is so that an operation and a specific set of arguments can be represented generically; the state can then correspond to different kinds of operations, such as invoking the instruction against a database, or autogenerating Python code for the operation into a script.

In order to establish the migrate-script behavior of the new operations, we use the Operations.implementation_for() decorator:

@Operations.implementation_for(CreateSequenceOp)
def create_sequence(operations, operation):
    if operation.schema is not None:
        name = "%s.%s" % (operation.schema, operation.sequence_name)
    else:
        name = operation.sequence_name
    operations.execute("CREATE SEQUENCE %s" % name)


@Operations.implementation_for(DropSequenceOp)
def drop_sequence(operations, operation):
    if operation.schema is not None:
        name = "%s.%s" % (operation.schema, operation.sequence_name)
    else:
        name = operation.sequence_name
    operations.execute("DROP SEQUENCE %s" % name)

Above, we use the simplest possible technique of invoking our DDL, which is just to call Operations.execute() with literal SQL. If this is all a custom operation needs, then this is fine. However, options for more comprehensive support include building out a custom SQL construct, as documented at Custom SQL Constructs and Compilation Extension.

With the above two steps, a migration script can now use new methods op.create_sequence() and op.drop_sequence() that will proxy to our object as a classmethod:

def upgrade():
    op.create_sequence("my_sequence")

def downgrade():
    op.drop_sequence("my_sequence")

The registration of new operations only needs to occur in time for the env.py script to invoke MigrationContext.run_migrations(); within the module level of the env.py script is sufficient.

See also

Autogenerating Custom Operation Directives - how to add autogenerate support to custom operations.

New in version 0.8: - the migration operations available via the Operations class as well as the alembic.op namespace is now extensible using a plugin system.

Built-in Operation Objects¶

The migration operations present on Operations are themselves delivered via operation objects that represent an operation and its arguments. All operations descend from the MigrateOperation class, and are registered with the Operations class using the Operations.register_operation() class decorator. The MigrateOperation objects also serve as the basis for how the autogenerate system renders new migration scripts.

See also

Built-in Operation Objects

The built-in operation objects are listed below.

class alembic.operations.ops.AddColumnOp(table_name, column, schema=None)¶

Represent an add column operation.

classmethod add_column(operations, table_name, column, schema=None)¶: This method is proxied on the Operations class, via the Operations.add_column() method.

classmethod batch_add_column(operations, column)¶: This method is proxied on the BatchOperations class, via the BatchOperations.add_column() method.

class alembic.operations.ops.AddConstraintOp¶: Represent an add constraint operation.

class alembic.operations.ops.AlterColumnOp(table_name, column_name, schema=None, existing_type=None, existing_server_default=False, existing_nullable=None, modify_nullable=None, modify_server_default=False, modify_name=None, modify_type=None, **kw)¶

Represent an alter column operation.

classmethod alter_column(operations, table_name, column_name, nullable=None, server_default=False, new_column_name=None, type_=None, existing_type=None, existing_server_default=False, existing_nullable=None, schema=None, **kw)¶: This method is proxied on the Operations class, via the Operations.alter_column() method.

classmethod batch_alter_column(operations, column_name, nullable=None, server_default=False, new_column_name=None, type_=None, existing_type=None, existing_server_default=False, existing_nullable=None, **kw)¶: This method is proxied on the BatchOperations class, via the BatchOperations.alter_column() method.

class alembic.operations.ops.AlterTableOp(table_name, schema=None)¶: Represent an alter table operation.

class alembic.operations.ops.BulkInsertOp(table, rows, multiinsert=True)¶

Represent a bulk insert operation.

classmethod bulk_insert(operations, table, rows, multiinsert=True)¶: This method is proxied on the Operations class, via the Operations.bulk_insert() method.

class alembic.operations.ops.CreateCheckConstraintOp(constraint_name, table_name, condition, schema=None, _orig_constraint=None, **kw)¶

Represent a create check constraint operation.

classmethod batch_create_check_constraint(operations, constraint_name, condition, **kw)¶: This method is proxied on the BatchOperations class, via the BatchOperations.create_check_constraint() method.

classmethod create_check_constraint(operations, constraint_name, table_name, condition, schema=None, **kw)¶: This method is proxied on the Operations class, via the Operations.create_check_constraint() method.

class alembic.operations.ops.CreateForeignKeyOp(constraint_name, source_table, referent_table, local_cols, remote_cols, _orig_constraint=None, **kw)¶

Represent a create foreign key constraint operation.

classmethod batch_create_foreign_key(operations, constraint_name, referent_table, local_cols, remote_cols, referent_schema=None, onupdate=None, ondelete=None, deferrable=None, initially=None, match=None, **dialect_kw)¶: This method is proxied on the BatchOperations class, via the BatchOperations.create_foreign_key() method.

classmethod create_foreign_key(operations, constraint_name, source_table, referent_table, local_cols, remote_cols, onupdate=None, ondelete=None, deferrable=None, initially=None, match=None, source_schema=None, referent_schema=None, **dialect_kw)¶: This method is proxied on the Operations class, via the Operations.create_foreign_key() method.

class alembic.operations.ops.CreateIndexOp(index_name, table_name, columns, schema=None, unique=False, _orig_index=None, **kw)¶

Represent a create index operation.

classmethod batch_create_index(operations, index_name, columns, **kw)¶: This method is proxied on the BatchOperations class, via the BatchOperations.create_index() method.

classmethod create_index(operations, index_name, table_name, columns, schema=None, unique=False, **kw)¶: This method is proxied on the Operations class, via the Operations.create_index() method.

class alembic.operations.ops.CreatePrimaryKeyOp(constraint_name, table_name, columns, schema=None, _orig_constraint=None, **kw)¶

Represent a create primary key operation.

classmethod batch_create_primary_key(operations, constraint_name, columns)¶: This method is proxied on the BatchOperations class, via the BatchOperations.create_primary_key() method.

classmethod create_primary_key(operations, constraint_name, table_name, columns, schema=None)¶: This method is proxied on the Operations class, via the Operations.create_primary_key() method.

class alembic.operations.ops.CreateTableOp(table_name, columns, schema=None, _orig_table=None, **kw)¶

Represent a create table operation.

classmethod create_table(operations, table_name, *columns, **kw)¶: This method is proxied on the Operations class, via the Operations.create_table() method.

class alembic.operations.ops.CreateUniqueConstraintOp(constraint_name, table_name, columns, schema=None, _orig_constraint=None, **kw)¶

Represent a create unique constraint operation.

classmethod batch_create_unique_constraint(operations, constraint_name, columns, **kw)¶: This method is proxied on the BatchOperations class, via the BatchOperations.create_unique_constraint() method.

classmethod create_unique_constraint(operations, constraint_name, table_name, columns, schema=None, **kw)¶: This method is proxied on the Operations class, via the Operations.create_unique_constraint() method.

class alembic.operations.ops.DowngradeOps(ops=(), downgrade_token='downgrades')¶: contains a sequence of operations that would apply to the ‘downgrade’ stream of a script.

See also

Customizing Revision Generation

class alembic.operations.ops.DropColumnOp(table_name, column_name, schema=None, _orig_column=None, **kw)¶

Represent a drop column operation.

classmethod batch_drop_column(operations, column_name)¶: This method is proxied on the BatchOperations class, via the BatchOperations.drop_column() method.

classmethod drop_column(operations, table_name, column_name, schema=None, **kw)¶: This method is proxied on the Operations class, via the Operations.drop_column() method.

class alembic.operations.ops.DropConstraintOp(constraint_name, table_name, type_=None, schema=None, _orig_constraint=None)¶

Represent a drop constraint operation.

classmethod batch_drop_constraint(operations, constraint_name, type_=None)¶: This method is proxied on the BatchOperations class, via the BatchOperations.drop_constraint() method.

classmethod drop_constraint(operations, constraint_name, table_name, type_=None, schema=None)¶: This method is proxied on the Operations class, via the Operations.drop_constraint() method.

class alembic.operations.ops.DropIndexOp(index_name, table_name=None, schema=None, _orig_index=None)¶

Represent a drop index operation.

classmethod batch_drop_index(operations, index_name, **kw)¶: This method is proxied on the BatchOperations class, via the BatchOperations.drop_index() method.

classmethod drop_index(operations, index_name, table_name=None, schema=None)¶: This method is proxied on the Operations class, via the Operations.drop_index() method.

class alembic.operations.ops.DropTableOp(table_name, schema=None, table_kw=None, _orig_table=None)¶

Represent a drop table operation.

classmethod drop_table(operations, table_name, schema=None, **kw)¶: This method is proxied on the Operations class, via the Operations.drop_table() method.

class alembic.operations.ops.ExecuteSQLOp(sqltext, execution_options=None)¶

Represent an execute SQL operation.

classmethod execute(operations, sqltext, execution_options=None)¶: This method is proxied on the Operations class, via the Operations.execute() method.

class alembic.operations.ops.MigrateOperation¶

base class for migration command and organization objects.

This system is part of the operation extensibility API.

New in version 0.8.0.

See also

info¶: A dictionary that may be used to store arbitrary information along with this MigrateOperation object.

class alembic.operations.ops.MigrationScript(rev_id, upgrade_ops, downgrade_ops, message=None, imports=set([]), head=None, splice=None, branch_label=None, version_path=None, depends_on=None)¶

represents a migration script.

E.g. when autogenerate encounters this object, this corresponds to the production of an actual script file.

A normal MigrationScript object would contain a single UpgradeOps and a single DowngradeOps directive. These are accessible via the .upgrade_ops and .downgrade_ops attributes.

In the case of an autogenerate operation that runs multiple times, such as the multiple database example in the “multidb” template, the .upgrade_ops and .downgrade_ops attributes are disabled, and instead these objects should be accessed via the .upgrade_ops_list and .downgrade_ops_list list-based attributes. These latter attributes are always available at the very least as single-element lists.

Changed in version 0.8.1: the .upgrade_ops and .downgrade_ops attributes should be accessed via the .upgrade_ops_list and .downgrade_ops_list attributes if multiple autogenerate passes proceed on the same MigrationScript object.

See also

ScriptDirectory.get_heads()

downgrade_ops¶: An instance of DowngradeOps.

See also

MigrationScript.downgrade_ops_list

downgrade_ops_list¶

A list of DowngradeOps instances.

This is used in place of the MigrationScript.downgrade_ops attribute when dealing with a revision operation that does multiple autogenerate passes.

New in version 0.8.1.

upgrade_ops¶: An instance of UpgradeOps.

See also

MigrationScript.upgrade_ops_list

upgrade_ops_list¶

A list of UpgradeOps instances.

This is used in place of the MigrationScript.upgrade_ops attribute when dealing with a revision operation that does multiple autogenerate passes.

New in version 0.8.1.

class alembic.operations.ops.ModifyTableOps(table_name, ops, schema=None)¶: Contains a sequence of operations that all apply to a single Table.

class alembic.operations.ops.OpContainer(ops=())¶: Represent a sequence of operations operation.

class alembic.operations.ops.RenameTableOp(old_table_name, new_table_name, schema=None)¶

Represent a rename table operation.

classmethod rename_table(operations, old_table_name, new_table_name, schema=None)¶: This method is proxied on the Operations class, via the Operations.rename_table() method.

class alembic.operations.ops.UpgradeOps(ops=(), upgrade_token='upgrades')¶: contains a sequence of operations that would apply to the ‘upgrade’ stream of a script.

See also

Customizing Revision Generation

Autogeneration¶

Note

this section discusses the internal API of Alembic as regards the autogeneration feature of the alembic revision command. This section is only useful for developers who wish to extend the capabilities of Alembic. For general documentation on the autogenerate feature, please see Auto Generating Migrations.

The autogeneration system has a wide degree of public API, including the following areas:

The ability to do a “diff” of a MetaData object against a database, and receive a data structure back. This structure is available either as a rudimentary list of changes, or as a MigrateOperation structure.
The ability to alter how the alembic revision command generates revision scripts, including support for multiple revision scripts generated in one pass.
The ability to add new operation directives to autogeneration, including custom schema/model comparison functions and revision script rendering.

Getting Diffs¶

The simplest API autogenerate provides is the “schema comparison” API; these are simple functions that will run all registered “comparison” functions between a MetaData object and a database backend to produce a structure showing how they differ. The two functions provided are compare_metadata(), which is more of the “legacy” function that produces diff tuples, and produce_migrations(), which produces a structure consisting of operation directives detailed in Operation Directives.

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.

See also

produce_migrations() - produces a MigrationScript structure based on metadata comparison.

alembic.autogenerate.produce_migrations(context, metadata)¶

Produce a MigrationScript structure based on schema comparison.

This function does essentially what compare_metadata() does, but then runs the resulting list of diffs to produce the full MigrationScript object. For an example of what this looks like, see the example in Customizing Revision Generation.

New in version 0.8.0.

See also

compare_metadata() - returns more fundamental “diff” data from comparing a schema.

Customizing Revision Generation¶

New in version 0.8.0: - the alembic revision system is now customizable.

The alembic revision command, also available programmatically via command.revision(), essentially produces a single migration script after being run. Whether or not the --autogenerate option was specified basically determines if this script is a blank revision script with empty upgrade() and downgrade() functions, or was produced with alembic operation directives as the result of autogenerate.

In either case, the system creates a full plan of what is to be done in the form of a MigrateOperation structure, which is then used to produce the script.

For example, suppose we ran alembic revision --autogenerate, and the end result was that it produced a new revision 'eced083f5df' with the following contents:

"""create the organization table."""

# revision identifiers, used by Alembic.
revision = 'eced083f5df'
down_revision = 'beafc7d709f'

from alembic import op
import sqlalchemy as sa


def upgrade():
    op.create_table(
        'organization',
        sa.Column('id', sa.Integer(), primary_key=True),
        sa.Column('name', sa.String(50), nullable=False)
    )
    op.add_column(
        'user',
        sa.Column('organization_id', sa.Integer())
    )
    op.create_foreign_key(
        'org_fk', 'user', 'organization', ['organization_id'], ['id']
    )

def downgrade():
    op.drop_constraint('org_fk', 'user')
    op.drop_column('user', 'organization_id')
    op.drop_table('organization')

The above script is generated by a MigrateOperation structure that looks like this:

from alembic.operations import ops
import sqlalchemy as sa

migration_script = ops.MigrationScript(
    'eced083f5df',
    ops.UpgradeOps(
        ops=[
            ops.CreateTableOp(
                'organization',
                [
                    sa.Column('id', sa.Integer(), primary_key=True),
                    sa.Column('name', sa.String(50), nullable=False)
                ]
            ),
            ops.ModifyTableOps(
                'user',
                ops=[
                    ops.AddColumnOp(
                        'user',
                        sa.Column('organization_id', sa.Integer())
                    ),
                    ops.CreateForeignKeyOp(
                        'org_fk', 'user', 'organization',
                        ['organization_id'], ['id']
                    )
                ]
            )
        ]
    ),
    ops.DowngradeOps(
        ops=[
            ops.ModifyTableOps(
                'user',
                ops=[
                    ops.DropConstraintOp('org_fk', 'user'),
                    ops.DropColumnOp('user', 'organization_id')
                ]
            ),
            ops.DropTableOp('organization')
        ]
    ),
    message='create the organization table.'
)

When we deal with a MigrationScript structure, we can render the upgrade/downgrade sections into strings for debugging purposes using the render_python_code() helper function:

from alembic.autogenerate import render_python_code
print(render_python_code(migration_script.upgrade_ops))

Renders:

### commands auto generated by Alembic - please adjust! ###
    op.create_table('organization',
    sa.Column('id', sa.Integer(), nullable=False),
    sa.Column('name', sa.String(length=50), nullable=False),
    sa.PrimaryKeyConstraint('id')
    )
    op.add_column('user', sa.Column('organization_id', sa.Integer(), nullable=True))
    op.create_foreign_key('org_fk', 'user', 'organization', ['organization_id'], ['id'])
    ### end Alembic commands ###

Given that structures like the above are used to generate new revision files, and that we’d like to be able to alter these as they are created, we then need a system to access this structure when the command.revision() command is used. The EnvironmentContext.configure.process_revision_directives parameter gives us a way to alter this. This is a function that is passed the above structure as generated by Alembic, giving us a chance to alter it. For example, if we wanted to put all the “upgrade” operations into a certain branch, and we wanted our script to not have any “downgrade” operations at all, we could build an extension as follows, illustrated within an env.py script:

def process_revision_directives(context, revision, directives):
    script = directives[0]

    # set specific branch
    script.head = "mybranch@head"

    # erase downgrade operations
    script.downgrade_ops.ops[:] = []

# ...

def run_migrations_online():

    # ...
    with engine.connect() as connection:

        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            process_revision_directives=process_revision_directives)

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

Above, the directives argument is a Python list. We may alter the given structure within this list in-place, or replace it with a new structure consisting of zero or more MigrationScript directives. The command.revision() command will then produce scripts corresponding to whatever is in this list.

alembic.autogenerate.render_python_code(up_or_down_op, sqlalchemy_module_prefix='sa.', alembic_module_prefix='op.', render_as_batch=False, imports=(), render_item=None)¶

Render Python code given an UpgradeOps or DowngradeOps object.

This is a convenience function that can be used to test the autogenerate output of a user-defined MigrationScript structure.

Fine-Grained Autogenerate Generation with Rewriters¶

The preceding example illustrated how we can make a simple change to the structure of the operation directives to produce new autogenerate output. For the case where we want to affect very specific parts of the autogenerate stream, we can make a function for EnvironmentContext.configure.process_revision_directives which traverses through the whole MigrationScript structure, locates the elements we care about and modifies them in-place as needed. However, to reduce the boilerplate associated with this task, we can use the Rewriter object to make this easier. Rewriter gives us an object that we can pass directly to EnvironmentContext.configure.process_revision_directives which we can also attach handler functions onto, keyed to specific types of constructs.

Below is an example where we rewrite ops.AddColumnOp directives; based on whether or not the new column is “nullable”, we either return the existing directive, or we return the existing directive with the nullable flag changed, inside of a list with a second directive to alter the nullable flag in a second step:

# ... fragmented env.py script ....

from alembic.autogenerate import rewriter
from alembic.operations import ops

writer = rewriter.Rewriter()

@writer.rewrites(ops.AddColumnOp)
def add_column(context, revision, op):
    if op.column.nullable:
        return op
    else:
        op.column.nullable = True
        return [
            op,
            ops.AlterColumnOp(
                op.table_name,
                op.column.name,
                modify_nullable=False,
                existing_type=op.column.type,
            )
        ]

# ... later ...

def run_migrations_online():
    # ...

    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            process_revision_directives=writer
        )

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

Above, in a full ops.MigrationScript structure, the AddColumn directives would be present within the paths MigrationScript->UpgradeOps->ModifyTableOps and MigrationScript->DowngradeOps->ModifyTableOps. The Rewriter handles traversing into these structures as well as rewriting them as needed so that we only need to code for the specific object we care about.

class alembic.autogenerate.rewriter.Rewriter¶

A helper object that allows easy ‘rewriting’ of ops streams.

The Rewriter object is intended to be passed along to the EnvironmentContext.configure.process_revision_directives parameter in an env.py script. Once constructed, any number of “rewrites” functions can be associated with it, which will be given the opportunity to modify the structure without having to have explicit knowledge of the overall structure.

The function is passed the MigrationContext object and revision tuple that are passed to the Environment Context.configure.process_revision_directives function normally, and the third argument is an individual directive of the type noted in the decorator. The function has the choice of returning a single op directive, which normally can be the directive that was actually passed, or a new directive to replace it, or a list of zero or more directives to replace it.

New in version 0.8.

chain(other)¶

Produce a “chain” of this Rewriter to another.

This allows two rewriters to operate serially on a stream, e.g.:

writer1 = autogenerate.Rewriter()
writer2 = autogenerate.Rewriter()

@writer1.rewrites(ops.AddColumnOp)
def add_column_nullable(context, revision, op):
    op.column.nullable = True
    return op

@writer2.rewrites(ops.AddColumnOp)
def add_column_idx(context, revision, op):
    idx_op = ops.CreateIndexOp(
        'ixc', op.table_name, [op.column.name])
    return [
        op,
        idx_op
    ]

writer = writer1.chain(writer2)

Parameters:	other – a `Rewriter` instance
Returns:	a new `Rewriter` that will run the operations of this writer, then the “other” writer, in succession.

rewrites(operator)¶

Register a function as rewriter for a given type.

The function should receive three arguments, which are the MigrationContext, a revision tuple, and an op directive of the type indicated. E.g.:

@writer1.rewrites(ops.AddColumnOp)
def add_column_nullable(context, revision, op):
    op.column.nullable = True
    return op

Revision Generation with Multiple Engines / `run_migrations()` calls¶

A lesser-used technique which allows autogenerated migrations to run against multiple databse backends at once, generating changes into a single migration script, is illustrated in the provided multidb template. This template features a special env.py which iterates through multiple Engine instances and calls upon MigrationContext.run_migrations() for each:

for name, rec in engines.items():
    logger.info("Migrating database %s" % name)
    context.configure(
        connection=rec['connection'],
        upgrade_token="%s_upgrades" % name,
        downgrade_token="%s_downgrades" % name,
        target_metadata=target_metadata.get(name)
    )
    context.run_migrations(engine_name=name)

Above, MigrationContext.run_migrations() is run multiple times, once for each engine. Within the context of autogeneration, each time the method is called the upgrade_token and downgrade_token parameters are changed, so that the collection of template variables gains distinct entries for each engine, which are then referred to explicitly within script.py.mako.

In terms of the EnvironmentContext.configure.process_revision_directives hook, the behavior here is that the process_revision_directives hook is invoked multiple times, once for each call to context.run_migrations(). This means that if a multi-run_migrations() approach is to be combined with the process_revision_directives hook, care must be taken to use the hook appropriately.

The first point to note is that when a second call to run_migrations() occurs, the .upgrade_ops and .downgrade_ops attributes are converted into Python lists, and new UpgradeOps and DowngradeOps objects are appended to these lists. Each UpgradeOps and DowngradeOps object maintains an .upgrade_token and a .downgrade_token attribute respectively, which serves to render their contents into the appropriate template token.

For example, a multi-engine run that has the engine names engine1 and engine2 will generate tokens of engine1_upgrades, engine1_downgrades, engine2_upgrades and engine2_downgrades as it runs. The resulting migration structure would look like this:

from alembic.operations import ops
import sqlalchemy as sa

migration_script = ops.MigrationScript(
    'eced083f5df',
    [
        ops.UpgradeOps(
            ops=[
                # upgrade operations for "engine1"
            ],
            upgrade_token="engine1_upgrades"
        ),
        ops.UpgradeOps(
            ops=[
                # upgrade operations for "engine2"
            ],
            upgrade_token="engine2_upgrades"
        ),
    ],
    [
        ops.DowngradeOps(
            ops=[
                # downgrade operations for "engine1"
            ],
            downgrade_token="engine1_downgrades"
        ),
        ops.DowngradeOps(
            ops=[
                # downgrade operations for "engine2"
            ],
            downgrade_token="engine2_downgrades"
        )
    ],
    message='migration message'
)

Given the above, the following guidelines should be considered when the env.py script calls upon MigrationContext.run_migrations() mutiple times when running autogenerate:

If the process_revision_directives hook aims to add elements based on inspection of the current database / connection, it should do its operation on each iteration. This is so that each time the hook runs, the database is available.
Alternatively, if the process_revision_directives hook aims to modify the list of migration directives in place, this should be called only on the last iteration. This is so that the hook isn’t being given an ever-growing structure each time which it has already modified previously.
The Rewriter object, if used, should be called only on the last iteration, because it will always deliver all directives every time, so again to avoid double/triple/etc. processing of directives it should be called only when the structure is complete.
The MigrationScript.upgrade_ops_list and MigrationScript.downgrade_ops_list attributes should be consulted when referring to the collection of UpgradeOps and DowngradeOps objects.

Changed in version 0.8.1: - multiple calls to MigrationContext.run_migrations() within an autogenerate operation, such as that proposed within the multidb script template, are now accommodated by the new extensible migration system introduced in 0.8.0.

Autogenerating Custom Operation Directives¶

In the section Operation Plugins, we talked about adding new subclasses of MigrateOperation in order to add new op. directives. In the preceding section Customizing Revision Generation, we also learned that these same MigrateOperation structures are at the base of how the autogenerate system knows what Python code to render. Using this knowledge, we can create additional functions that plug into the autogenerate system so that our new operations can be generated into migration scripts when alembic revision --autogenerate is run.

The following sections will detail an example of this using the the CreateSequenceOp and DropSequenceOp directives we created in Operation Plugins, which correspond to the SQLAlchemy Sequence construct.

New in version 0.8.0: - custom operations can be added to the autogenerate system to support new kinds of database objects.

Tracking our Object with the Model¶

The basic job of an autogenerate comparison function is to inspect a series of objects in the database and compare them against a series of objects defined in our model. By “in our model”, we mean anything defined in Python code that we want to track, however most commonly we’re talking about a series of Table objects present in a MetaData collection.

Let’s propose a simple way of seeing what Sequence objects we want to ensure exist in the database when autogenerate runs. While these objects do have some integrations with Table and MetaData already, let’s assume they don’t, as the example here intends to illustrate how we would do this for most any kind of custom construct. We associate the object with the info collection of MetaData, which is a dictionary we can use for anything, which we also know will be passed to the autogenerate process:

from sqlalchemy.schema import Sequence

def add_sequence_to_model(sequence, metadata):
    metadata.info.setdefault("sequences", set()).add(
        (sequence.schema, sequence.name)
    )

my_seq = Sequence("my_sequence")
add_sequence_to_model(my_seq, model_metadata)

The info dictionary is a good place to put things that we want our autogeneration routines to be able to locate, which can include any object such as custom DDL objects representing views, triggers, special constraints, or anything else we want to support.

Registering a Comparison Function¶

We now need to register a comparison hook, which will be used to compare the database to our model and produce CreateSequenceOp and DropSequenceOp directives to be included in our migration script. Note that we are assuming a Postgresql backend:

from alembic.autogenerate import comparators

@comparators.dispatch_for("schema")
def compare_sequences(autogen_context, upgrade_ops, schemas):
    all_conn_sequences = set()

    for sch in schemas:

        all_conn_sequences.update([
            (sch, row[0]) for row in
            autogen_context.connection.execute(
                "SELECT relname FROM pg_class c join "
                "pg_namespace n on n.oid=c.relnamespace where "
                "relkind='S' and n.nspname=%(nspname)s",

                # note that we consider a schema of 'None' in our
                # model to be the "default" name in the PG database;
                # this usually is the name 'public'
                nspname=autogen_context.dialect.default_schema_name
                if sch is None else sch
            )
        ])

    # get the collection of Sequence objects we're storing with
    # our MetaData
    metadata_sequences = autogen_context.metadata.info.setdefault(
        "sequences", set())

    # for new names, produce CreateSequenceOp directives
    for sch, name in metadata_sequences.difference(all_conn_sequences):
        upgrade_ops.ops.append(
            CreateSequenceOp(name, schema=sch)
        )

    # for names that are going away, produce DropSequenceOp
    # directives
    for sch, name in all_conn_sequences.difference(metadata_sequences):
        upgrade_ops.ops.append(
            DropSequenceOp(name, schema=sch)
        )

Above, we’ve built a new function compare_sequences() and registered it as a “schema” level comparison function with autogenerate. The job that it performs is that it compares the list of sequence names present in each database schema with that of a list of sequence names that we are maintaining in our MetaData object.

When autogenerate completes, it will have a series of CreateSequenceOp and DropSequenceOp directives in the list of “upgrade” operations; the list of “downgrade” operations is generated directly from these using the CreateSequenceOp.reverse() and DropSequenceOp.reverse() methods that we’ve implemented on these objects.

The registration of our function at the scope of “schema” means our autogenerate comparison function is called outside of the context of any specific table or column. The three available scopes are “schema”, “table”, and “column”, summarized as follows:

Schema level - these hooks are passed a AutogenContext, an UpgradeOps collection, and a collection of string schema names to be operated upon. If the UpgradeOps collection contains changes after all hooks are run, it is included in the migration script:
```
@comparators.dispatch_for("schema")
def compare_schema_level(autogen_context, upgrade_ops, schemas):
    pass
```
Table level - these hooks are passed a AutogenContext, a ModifyTableOps collection, a schema name, table name, a Table reflected from the database if any or None, and a Table present in the local MetaData. If the ModifyTableOps collection contains changes after all hooks are run, it is included in the migration script:
```
@comparators.dispatch_for("table")
def compare_table_level(autogen_context, modify_ops,
    schemaname, tablename, conn_table, metadata_table):
    pass
```
Column level - these hooks are passed a AutogenContext, an AlterColumnOp object, a schema name, table name, column name, a Column reflected from the database and a Column present in the local table. If the AlterColumnOp contains changes after all hooks are run, it is included in the migration script; a “change” is considered to be present if any of the modify_ attributes are set to a non-default value, or there are any keys in the .kw collection with the prefix "modify_":
```
@comparators.dispatch_for("column")
def compare_column_level(autogen_context, alter_column_op,
    schemaname, tname, cname, conn_col, metadata_col):
    pass
```

The AutogenContext passed to these hooks is documented below.

class alembic.autogenerate.api.AutogenContext(migration_context, metadata=None, opts=None, autogenerate=True)¶

Maintains configuration and state that’s specific to an autogenerate operation.

connection = None¶

The Connection object currently connected to the database backend being compared.

This is obtained from the MigrationContext.bind and is utimately set up in the env.py script.

dialect = None¶

The Dialect object currently in use.

This is normally obtained from the dialect attribute.

imports = None¶

A set() which contains string Python import directives.

The directives are to be rendered into the ${imports} section of a script template. The set is normally empty and can be modified within hooks such as the EnvironmentContext.configure.render_item hook.

New in version 0.8.3.

metadata = None¶

The MetaData object representing the destination.

This object is the one that is passed within env.py to the EnvironmentContext.configure.target_metadata parameter. It represents the structure of Table and other objects as stated in the current database model, and represents the destination structure for the database being examined.

While the MetaData object is primarily known as a collection of Table objects, it also has an info dictionary that may be used by end-user schemes to store additional schema-level objects that are to be compared in custom autogeneration schemes.

migration_context = None¶: The MigrationContext established by the env.py script.

run_filters(object_, name, type_, reflected, compare_to)¶

Run the context’s object filters and return True if the targets should be part of the autogenerate operation.

This method should be run for every kind of object encountered within an autogenerate operation, giving the environment the chance to filter what objects should be included in the comparison. The filters here are produced directly via the EnvironmentContext.configure.include_object and EnvironmentContext.configure.include_symbol functions, if present.

Creating a Render Function¶

The second autogenerate integration hook is to provide a “render” function; since the autogenerate system renders Python code, we need to build a function that renders the correct “op” instructions for our directive:

from alembic.autogenerate import renderers

@renderers.dispatch_for(CreateSequenceOp)
def render_create_sequence(autogen_context, op):
    return "op.create_sequence(%r, **%r)" % (
        op.sequence_name,
        {"schema": op.schema}
    )


@renderers.dispatch_for(DropSequenceOp)
def render_drop_sequence(autogen_context, op):
    return "op.drop_sequence(%r, **%r)" % (
        op.sequence_name,
        {"schema": op.schema}
    )

The above functions will render Python code corresponding to the presence of CreateSequenceOp and DropSequenceOp instructions in the list that our comparison function generates.

Running It¶

All the above code can be organized however the developer sees fit; the only thing that needs to make it work is that when the Alembic environment env.py is invoked, it either imports modules which contain all the above routines, or they are locally present, or some combination thereof.

If we then have code in our model (which of course also needs to be invoked when env.py runs!) like this:

from sqlalchemy.schema import Sequence

my_seq_1 = Sequence("my_sequence_1")
add_sequence_to_model(my_seq_1, target_metadata)

When we first run alembic revision --autogenerate, we’ll see this in our migration file:

def upgrade():
    ### commands auto generated by Alembic - please adjust! ###
    op.create_sequence('my_sequence_1', **{'schema': None})
    ### end Alembic commands ###


def downgrade():
    ### commands auto generated by Alembic - please adjust! ###
    op.drop_sequence('my_sequence_1', **{'schema': None})
    ### end Alembic commands ###

These are our custom directives that will invoke when alembic upgrade or alembic downgrade is run.

Script Directory¶

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

class alembic.script.ScriptDirectory(dir, file_template='%(rev)s_%(slug)s', truncate_slug_length=40, version_locations=None, sourceless=False, output_encoding='utf-8')¶

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, head=None, refresh=False, splice=False, branch_labels=None, version_path=None, depends_on=None, **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.
head –
the head revision to generate against. Defaults to the current “head” if no branches are present, else raises an exception.

New in version 0.7.0.
splice – if True, allow the “head” version to not be an actual head; otherwise, the selected head must be a head (e.g. endpoint) revision.
refresh – deprecated.

get_base()¶

Return the “base” revision as a string.

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

If the script directory has multiple bases, an error is raised; ScriptDirectory.get_bases() should be preferred.

get_bases()¶

return all “base” revisions as strings.

This is the revision number of all scripts that have a down_revision of None.

New in version 0.7.0.

get_current_head()¶

Return the current head revision.

If the script directory has multiple heads due to branching, an error is raised; ScriptDirectory.get_heads() should be preferred.

Returns:	a string revision number.

See also

get_heads()¶

Return all “versioned head” revisions as strings.

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.

Returns:	a tuple of string revision numbers.

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

See also

ScriptDirectory.get_revisions()

get_revisions(id_)¶: Return the Script instance with the given rev identifier, symbolic name, or sequence of identifiers.

New in version 0.7.0.

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.

See also

RevisionMap.iterate_revisions()

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='heads')¶

Iterate through all revisions.

Parameters:

base – the base revision, or “base” to start from the empty revision.
head –
the head revision; defaults to “heads” to indicate all head revisions. May also be “head” to indicate a single head revision.

Changed in version 0.7.0: the “head” identifier now refers to the head of a non-branched repository only; use “heads” to refer to the set of all head branches simultaneously.

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.

longdoc¶: Return the docstring given in the script.

Revision¶

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

class alembic.script.revision.Revision(revision, down_revision, dependencies=None, branch_labels=None)¶

Base class for revisioned objects.

The Revision class is the base of the more public-facing Script object, which represents a migration script. The mechanics of revision management and traversal are encapsulated within Revision, while Script applies this logic to Python files in a version directory.

branch_labels = None¶: Optional string/tuple of symbolic names to apply to this revision’s branch

dependencies = None¶

Additional revisions which this revision is dependent on.

From a migration standpoint, these dependencies are added to the down_revision to form the full iteration. However, the separation of down_revision from “dependencies” is to assist in navigating a history that contains many branches, typically a multi-root scenario.

down_revision = None¶

The down_revision identifier(s) within the migration script.

Note that the total set of “down” revisions is down_revision + dependencies.

is_base¶: Return True if this Revision is a ‘base’ revision.

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

is_merge_point¶: Return True if this Script is a merge point.

nextrev = frozenset([])¶: following revisions, based on down_revision only.

revision = None¶: The string revision number.

class alembic.script.revision.RevisionMap(generator)¶

Maintains a map of Revision objects.

RevisionMap is used by ScriptDirectory to maintain and traverse the collection of Script objects, which are themselves instances of Revision.

Construct a new RevisionMap.

Parameters:	generator – a zero-arg callable that will generate an iterable of `Revision` instances to be used. These are typically `Script` subclasses within regular Alembic use.

add_revision(revision, _replace=False)¶

add a single revision to an existing map.

This method is for single-revision use cases, it’s not appropriate for fully populating an entire revision map.

bases¶

All “base” revisions as strings.

These are revisions that have a down_revision of None, or empty tuple.

Returns:	a tuple of string revision numbers.

get_current_head(branch_label=None)¶

Return the current head revision.

If the script directory has multiple heads due to branching, an error is raised; ScriptDirectory.get_heads() should be preferred.

Parameters:	branch_label – optional branch name which will limit the heads considered to those which include that branch_label.
Returns:	a string revision number.

See also

ScriptDirectory.get_heads()

get_revision(id_)¶

Return the Revision instance with the given rev id.

If a symbolic name such as “head” or “base” is given, resolves the identifier into the current head or base revision. If the symbolic name refers to multiples, MultipleHeads is raised.

Supports partial identifiers, where the given identifier is matched against all identifiers that start with the given characters; if there is exactly one match, that determines the full revision.

get_revisions(id_)¶

Return the Revision instances with the given rev id or identifiers.

May be given a single identifier, a sequence of identifiers, or the special symbols “head” or “base”. The result is a tuple of one or more identifiers, or an empty tuple in the case of “base”.

In the cases where ‘head’, ‘heads’ is requested and the revision map is empty, returns an empty tuple.

Supports partial identifiers, where the given identifier is matched against all identifiers that start with the given characters; if there is exactly one match, that determines the full revision.

heads¶

All “head” revisions as strings.

This is normally a tuple of length one, unless unmerged branches are present.

Returns:	a tuple of string revision numbers.

iterate_revisions(upper, lower, implicit_base=False, inclusive=False, assert_relative_length=True)¶

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 Revision objects.

DDL Internals¶

These are some of the constructs used to generate migration instructions. The APIs here build off of the sqlalchemy.schema.DDLElement and Custom SQL Constructs and Compilation Extension systems.

For programmatic usage of Alembic’s migration directives, the easiest route is to use the higher level functions given by Operation Directives.

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)¶

autogen_column_reflect(inspector, table, column_info)¶

A hook that is attached to the ‘column_reflect’ event for when a Table is reflected from the database during the autogenerate process.

Dialects can elect to modify the information gathered here.

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)¶

correct_for_autogen_foreignkeys(conn_fks, metadata_fks)¶

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)¶

prep_table_for_batch(table)¶

perform any operations needed on a table before a new one is created to replace it in batch mode.

the PG dialect uses this to drop constraints on the table before the new one uses those same names.

rename_table(old_table_name, new_table_name, schema=None)¶

requires_recreate_in_batch(batch_op)¶

Return True if the given BatchOperationsImpl would need the table to be recreated and copied in order to proceed.

Normally, only returns True on SQLite when operations other than add_column are present.

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_)¶

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)¶

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

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)¶

correct_for_autogen_foreignkeys(conn_fks, metadata_fks)¶

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)¶

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

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)¶

autogen_column_reflect(inspector, table, column_info)¶

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)¶

prep_table_for_batch(table)¶

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)¶