API Details¶
This section describes some key functions used within the migration process, particularly those referenced within
a migration environment’s env.py
file.
Overview¶
The three main objects in use are the EnvironmentContext
, MigrationContext
,
and Operations
classes, pictured below.

An Alembic command begins by instantiating an EnvironmentContext
object, then
making it available via the alembic.context
proxy module. The env.py
script, representing a user-configurable migration environment, is then
invoked. The env.py
script is then responsible for calling upon the
EnvironmentContext.configure()
, whose job it is to create
a MigrationContext
object.
Before this method is called, there’s not
yet any database connection or dialect-specific state set up. While
many methods on EnvironmentContext
are usable at this stage,
those which require database access, or at least access to the kind
of database dialect in use, are not. Once the
EnvironmentContext.configure()
method is called, the EnvironmentContext
is said to be configured with database connectivity, available via
a new MigrationContext
object. The MigrationContext
is associated with the EnvironmentContext
object
via the EnvironmentContext.get_context()
method.
Finally, env.py
calls upon the EnvironmentContext.run_migrations()
method. Within this method, a new Operations
object, which
provides an API for individual database migration operations, is established
within the alembic.op
proxy module. The Operations
object
uses the MigrationContext
object ultimately as a source of
database connectivity, though in such a way that it does not care if the
MigrationContext
is talking to a real database or just writing
out SQL to a file.
The Environment Context¶
The EnvironmentContext
class provides most of the
API used within an env.py
script. Within env.py
,
the instantated EnvironmentContext
is made available
via a special proxy module called alembic.context
. That is,
you can import alembic.context
like a regular Python module,
and each name you call upon it is ultimately routed towards the
current EnvironmentContext
in use.
In particular, the key method used within env.py
is EnvironmentContext.configure()
,
which establishes all the details about how the database will be accessed.
-
class
alembic.environment.
EnvironmentContext
(config, script, **kw)¶ Represent the state made available to an
env.py
script.EnvironmentContext
is normally instantiated by the commands present in thealembic.command
module. From within anenv.py
script, the currentEnvironmentContext
is available via thealembic.context
datamember.EnvironmentContext
is also a Python context manager, that is, is intended to be used using thewith:
statement. A typical use ofEnvironmentContext
: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 whenenv.py
callsMigrationContext.run_migrations()
, themy_function()
function above will be called by theMigrationContext
, 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
andScriptDirectory
objects can be created and used directly. TheEnvironmentContext
object is only needed when you need to actually invoke theenv.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
whenEnvironmentContext.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()
isFalse
, returns a “do nothing” context manager which otherwise produces no transactional state or directives. - If
is_offline_mode()
isTrue
, returns a context manager that will invoke theDefaultImpl.emit_begin()
andDefaultImpl.emit_commit()
methods, which will produce the string directivesBEGIN
andCOMMIT
on the output stream, as rendered by the target backend (e.g. SQL Server would emitBEGIN TRANSACTION
). - Otherwise, calls
sqlalchemy.engine.Connection.begin()
on the current online connection, which returns asqlalchemy.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 theConnection
directly to produce transactional state in “online” mode.- If
-
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, 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 thisEnvironmentContext
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 theMigrationContext
is to be used in “online” mode.If the
is_offline_mode()
function returnsTrue
, then no connection is needed here. Otherwise, theconnection
parameter should be present as an instance ofsqlalchemy.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 recentConnection
for which it was called is the one that will be operated upon by the next call torun_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 ifconnection
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
andurl
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 tosys.stdout
if not passed here and also not present on theConfig
object. The value here overrides that of theConfig
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 theliteral_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
- 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 targetConnection
to produce candidate upgrade/downgrade operations. - compare_type¶ –
Indicates type comparison behavior during an autogenerate operation. Defaults to
False
which disables type comparison. Set toTrue
to turn on default type comparison, which has varied accuracy depending on backend. See Comparing Types for an example as well as information on other type comparison options. - compare_server_default¶ –
Indicates server default comparison behavior during an autogenerate operation. Defaults to
False
which disables server default comparison. Set toTrue
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 bysqlalchemy.engine.reflection.Inspector.get_columns()
, whereasmetadata_column
is asqlalchemy.schema.Column
from the local model environment.A return value of
None
indicates to allow default server default comparison to proceed. Note that some backends such as Postgresql actually execute the two defaults on the database side to compare for equivalence. - include_object¶ –
A callable function which is given the chance to return
True
orFalse
for any object, indicating if the given object should be considered in the autogenerate sweep.The function accepts the following positional arguments:
object
: aSchemaItem
object such as aTable
,Column
,Index
UniqueConstraint
, orForeignKeyConstraint
objectname
: the name of the object. This is typically available viaobject.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 localMetaData
object.compare_to
: the object being compared against, if available, elseNone
.
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 theEnvironmentContext.configure.include_schemas
flag is set toTrue
. TheTable.schema
attribute on eachTable
object reflected will indicate the name of the schema from which theTable
originates.New in version 0.6.0.
- include_symbol¶ –
A callable function which, given a table name and schema name (may be
None
), returnsTrue
orFalse
, 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 genericEnvironmentContext.configure.include_object
parameter.E.g.:
def include_symbol(tablename, schema): return tablename not in ("skip_table_one", "skip_table_two") context.configure( # ... include_symbol = include_symbol )
- render_as_batch¶ –
if True, commands which alter elements within a table will be placed under a
with batch_alter_table():
directive, so that batch migrations will take place.New in version 0.7.0.
- include_schemas¶ –
If True, autogenerate will scan across all schemas located by the SQLAlchemy
get_schema_names()
method, and include all differences in tables found across all those schemas. When using this option, you may want to also use theEnvironmentContext.configure.include_object
option to specify a callable which can filter the tables/schemas that get included. - render_item¶ –
Callable that can be used to override how any schema item, i.e. column, constraint, type, etc., is rendered for autogenerate. The callable receives a string describing the type of object, the object, and the autogen context. If it returns False, the default rendering method will be used. If it returns None, the item will not be rendered in the context of a Table construct, that is, can be used to skip columns or constraints within op.create_table():
def my_render_column(type_, col, autogen_context): if type_ == "column" and isinstance(col, MySpecialCol): return repr(col) else: return False context.configure( # ... render_item = my_render_column )
Available values for the type string include:
"column"
,"primary_key"
,"foreign_key"
,"unique"
,"check"
,"type"
,"server_default"
. - upgrade_token¶ – When autogenerate completes, the text of the
candidate upgrade operations will be present in this template
variable when
script.py.mako
is rendered. Defaults toupgrades
. - 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 todowngrades
. - 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 beNone
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 beNone
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 thesqlalchemy
namespace, this prefix will be used within autogenerate. If left at its default ofNone
, 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 ofEnvironmentContext.configure.sqlalchemy_module_prefix
when left atNone
; the__module__
attribute is now used.New in version 0.6.3: added
EnvironmentContext.configure.user_module_prefix
See also
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.
- connection¶ – a
-
execute
(sql, execution_options=None)¶ Execute the given SQL using the current change context.
The behavior of
execute()
is the same as that ofOperations.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 viaconfigure()
.
-
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 viaconfigure()
.
-
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
ordowngrade
command.If it was specified as
head
, the actual version number is returned; if specified asbase
,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 customenv.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 extendingenv.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 customenv.py
script.The return value is a list, returned directly from the
argparse
structure. Ifas_dictionary=True
is passed, thex
arguments are parsed usingkey=value
format into a dictionary that is then returned.For example, to support passing a database URL on the command line, the standard
env.py
script can be modified like this:cmd_line_url = context.get_x_argument( as_dictionary=True).get('dbname') if cmd_line_url: engine = create_engine(cmd_line_url) else: engine = engine_from_config( config.get_section(config.config_ini_section), prefix='sqlalchemy.', poolclass=pool.NullPool)
This then takes effect by running the
alembic
script as:alembic -x dbname=postgresql://user:pass@host/dbname upgrade head
This function does not require that the
MigrationContext
has been configured.New in version 0.6.0.
-
is_offline_mode
()¶ Return True if the current migrations environment is running in “offline mode”.
This is
True
orFalse
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 toconfigure()
This function requires that a
MigrationContext
has first been made available viaconfigure()
.
-
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 theupgrade()
anddowngrade()
functions within each target revision file. By modifying thescript.py.mako
file so that theupgrade()
anddowngrade()
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 customenv.py
script to the migration functions.This function requires that a
MigrationContext
has first been made available viaconfigure()
.
-
script
= None¶ An instance of
ScriptDirectory
which provides programmatic access to version files within theversions/
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.
- config¶ – a
The Migration Context¶
-
class
alembic.migration.
MigrationContext
(dialect, connection, opts, environment_context=None)¶ Represent the database state made available to a migration script.
MigrationContext
is the front end to an actual database connection, or alternatively a string output stream given a particular database dialect, from an Alembic perspective.When inside the
env.py
script, theMigrationContext
is available via theEnvironmentContext.get_context()
method, which is available atalembic.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, theMigrationContext.configure()
method to create newMigrationContext
objects. For example, to get at the current revision in the database usingMigrationContext.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 thesqlalchemy.schema.Table.create()
andsqlalchemy.schema.MetaData.create_all()
methods ofTable
,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.
-
classmethod
configure
(connection=None, url=None, dialect_name=None, environment_context=None, opts=None)¶ Create a new
MigrationContext
.This is a factory method usually called by
EnvironmentContext.configure()
.Parameters: - connection¶ – a
Connection
to use for SQL execution in “online” mode. When present, is also used to determine the type of dialect in use. - url¶ – a string database url, or a
sqlalchemy.engine.url.URL
object. The type of dialect to be used will be derived from this ifconnection
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
andurl
are not passed. - opts¶ – dictionary of options. Most other options
accepted by
EnvironmentContext.configure()
are passed via this dictionary.
- connection¶ – a
-
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 withas_sql=True
, thestarting_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 withas_sql=True
, thestarting_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 theMigrationContext
as thefn
argument. This function represents the “work” that will be done whenMigrationContext.run_migrations()
is called, typically from within theenv.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 theupgrade
ordowngrade
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 thecurrent
orstamp
commands.Parameters: **kw¶ – keyword arguments here will be passed to each migration callable, that is the upgrade()
ordowngrade()
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.
-
The Operations Object¶
Within migration scripts, actual database migration operations are handled
via an instance of Operations
. See Operation Reference for an overview
of this object.
Commands¶
Alembic commands are all represented by functions in the alembic.command
package. They all accept the same style of usage, being sent
the Config
object as the first argument.
Commands can be run programmatically, by first constructing a Config
object, as in:
from alembic.config import Config
from alembic import command
alembic_cfg = Config("/path/to/yourapp/alembic.ini")
command.upgrade(alembic_cfg, "head")
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.
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
-
alembic.command.
revision
(config, message=None, autogenerate=False, sql=False, head='head', splice=False, branch_label=None, version_path=None, rev_id=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.
Configuration¶
The Config
object represents the configuration
passed to the Alembic environment. From an API usage perspective,
it is needed for the following use cases:
- to create a
ScriptDirectory
, which allows you to work with the actual script files in a migration environment - to create an
EnvironmentContext
, which allows you to actually run theenv.py
module within the migration environment - to programatically run any of the commands in the
alembic.command
module.
The Config
is not needed for these cases:
- to instantiate a
MigrationContext
directly - this object only needs a SQLAlchemy connection or dialect name. - to instantiate a
Operations
object - this object only needs aMigrationContext
.
-
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 theEnvironmentContext.config
attribute, which in turn is available atalembic.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 inalembic.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 theConfig.file_config
attribute is first invoked, the replacement variablehere
will be added to this dictionary before the dictionary is passed toSafeConfigParser()
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.
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
Connection
when calling commands fromalembic.command
programmatically.New in version 0.7.5.
-
cmd_opts
= None¶ The command-line options passed to the
alembic
script.Within an
env.py
script this can be accessed via theEnvironmentContext.config
attribute.New in version 0.6.0.
See also
-
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()
andConfig.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
andlist_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.
Script Directory¶
The ScriptDirectory
object provides programmatic access
to the Alembic version files present in the filesystem.
-
class
alembic.script.
Script
(module, rev_id, path)¶ Represent a single revision file in a
versions/
directory.The
Script
instance is returned by methods such asScriptDirectory.iterate_revisions()
.-
doc
¶ Return the docstring given in the script.
-
longdoc
¶ Return the docstring given in the script.
-
module
= None¶ The Python module representing the actual script itself.
-
path
= None¶ Filesystem path of the script.
-
-
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 aConfig
instance.The
Config
need only have thescript_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.
- revid¶ – String revision id. Typically this
comes from
-
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_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
-
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 inalembic.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.
-
Revision¶
The RevisionMap
object serves as the basis for revision
management, used exclusively by ScriptDirectory
.
-
class
alembic.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-facingScript
object, which represents a migration script. The mechanics of revision management and traversal are encapsulated withinRevision
, whileScript
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_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 succeedingScript
, that is more than oneScript
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 theScriptDirectory
refers to thisScript
. Multiple heads can be present.
-
nextrev
= frozenset([])¶ following revisions, based on down_revision only.
-
revision
= None¶ The string revision number.
-
-
class
alembic.revision.
RevisionMap
(generator)¶ Maintains a map of
Revision
objects.RevisionMap
is used byScriptDirectory
to maintain and traverse the collection ofScript
objects, which are themselves instances ofRevision
.Construct a new
RevisionMap
.Parameters: generator¶ – a zero-arg callable that will generate an iterable of Revision
instances to be used. These are typicallyScript
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
-
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.
-
Autogeneration¶
Alembic 0.3 introduces a small portion of the autogeneration system as a public API.
-
alembic.autogenerate.
compare_metadata
(context, metadata)¶ Compare a database schema to that given in a
MetaData
instance.The database connection is presented in the context of a
MigrationContext
object, which provides database connectivity as well as optional comparison functions to use for datatypes and server defaults - see the “autogenerate” arguments atEnvironmentContext.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.
- context¶ – a
DDL Internals¶
These are some of the constructs used to generate migration
instructions. The APIs here build off of the sqlalchemy.schema.DDLElement
and sqlalchemy.ext.compiler
systems.
For programmatic usage of Alembic’s migration directives, the easiest
route is to use the higher level functions given by alembic.operations
.
-
class
alembic.ddl.base.
AddColumn
(name, column, schema=None)¶
-
class
alembic.ddl.base.
AlterColumn
(name, column_name, schema=None, existing_type=None, existing_nullable=None, existing_server_default=None)¶
-
class
alembic.ddl.base.
AlterTable
(table_name, schema=None)¶ Represent an ALTER TABLE statement.
Only the string name and optional schema name of the table is required, not a full Table object.
-
class
alembic.ddl.base.
ColumnDefault
(name, column_name, default, **kw)¶
-
class
alembic.ddl.base.
ColumnName
(name, column_name, newname, **kw)¶
-
class
alembic.ddl.base.
ColumnNullable
(name, column_name, nullable, **kw)¶
-
class
alembic.ddl.base.
ColumnType
(name, column_name, type_, **kw)¶
-
class
alembic.ddl.base.
DropColumn
(name, column, schema=None)¶
-
class
alembic.ddl.base.
RenameTable
(old_table_name, new_table_name, schema=None)¶
-
alembic.ddl.base.
add_column
(compiler, column, **kw)¶
-
alembic.ddl.base.
alter_column
(compiler, name)¶
-
alembic.ddl.base.
alter_table
(compiler, name, schema)¶
-
alembic.ddl.base.
drop_column
(compiler, name)¶
-
alembic.ddl.base.
format_column_name
(compiler, name)¶
-
alembic.ddl.base.
format_server_default
(compiler, default)¶
-
alembic.ddl.base.
format_table_name
(compiler, name, schema)¶
-
alembic.ddl.base.
format_type
(compiler, type_)¶
-
alembic.ddl.base.
quote_dotted
(name, quote)¶ quote the elements of a dotted name
-
alembic.ddl.base.
visit_add_column
(element, compiler, **kw)¶
-
alembic.ddl.base.
visit_column_default
(element, compiler, **kw)¶
-
alembic.ddl.base.
visit_column_name
(element, compiler, **kw)¶
-
alembic.ddl.base.
visit_column_nullable
(element, compiler, **kw)¶
-
alembic.ddl.base.
visit_column_type
(element, compiler, **kw)¶
-
alembic.ddl.base.
visit_drop_column
(element, compiler, **kw)¶
-
alembic.ddl.base.
visit_rename_table
(element, compiler, **kw)¶
-
class
alembic.ddl.impl.
DefaultImpl
(dialect, connection, as_sql, transactional_ddl, output_buffer, context_opts)¶ Provide the entrypoint for major migration operations, including database-specific behavioral variances.
While individual SQL/DDL constructs already provide for database-specific implementations, variances here allow for entirely different sequences of operations to take place for a particular migration, such as SQL Server’s special ‘IDENTITY INSERT’ step for bulk inserts.
-
add_column
(table_name, column, schema=None)¶
-
add_constraint
(const)¶
-
alter_column
(table_name, column_name, nullable=None, server_default=False, name=None, type_=None, schema=None, autoincrement=None, existing_type=None, existing_server_default=None, existing_nullable=None, existing_autoincrement=None)¶
-
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)¶
-
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)¶ Bases:
alembic.ddl.impl.DefaultImpl
-
alter_column
(table_name, column_name, nullable=None, server_default=False, name=None, type_=None, schema=None, autoincrement=None, existing_type=None, existing_server_default=None, existing_nullable=None, existing_autoincrement=None)¶
-
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)¶
-
transactional_ddl
= False¶
-
-
class
alembic.ddl.mysql.
MySQLModifyColumn
(name, column_name, schema=None, newname=None, type_=None, nullable=None, default=False, autoincrement=None)¶
MS-SQL¶
-
class
alembic.ddl.mssql.
MSSQLImpl
(*arg, **kw)¶ Bases:
alembic.ddl.impl.DefaultImpl
-
alter_column
(table_name, column_name, nullable=None, server_default=False, name=None, type_=None, schema=None, autoincrement=None, existing_type=None, existing_server_default=None, existing_nullable=None, existing_autoincrement=None)¶
-
batch_separator
= 'GO'¶
-
bulk_insert
(table, rows, **kw)¶
-
drop_column
(table_name, column, **kw)¶
-
emit_begin
()¶
-
emit_commit
()¶
-
transactional_ddl
= True¶
-
-
alembic.ddl.mssql.
mssql_add_column
(compiler, column, **kw)¶
-
alembic.ddl.mssql.
visit_add_column
(element, compiler, **kw)¶
-
alembic.ddl.mssql.
visit_column_default
(element, compiler, **kw)¶
-
alembic.ddl.mssql.
visit_column_nullable
(element, compiler, **kw)¶
-
alembic.ddl.mssql.
visit_column_type
(element, compiler, **kw)¶
-
alembic.ddl.mssql.
visit_rename_column
(element, compiler, **kw)¶
-
alembic.ddl.mssql.
visit_rename_table
(element, compiler, **kw)¶
Postgresql¶
-
class
alembic.ddl.postgresql.
PostgresqlImpl
(dialect, connection, as_sql, transactional_ddl, output_buffer, context_opts)¶ Bases:
alembic.ddl.impl.DefaultImpl
-
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)¶ Bases:
alembic.ddl.impl.DefaultImpl
-
add_constraint
(const)¶
-
compare_server_default
(inspector_column, metadata_column, rendered_metadata_default, rendered_inspector_default)¶
-
correct_for_autogen_constraints
(conn_unique_constraints, conn_indexes, metadata_unique_constraints, metadata_indexes)¶
-
drop_constraint
(const)¶
-
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.
-
transactional_ddl
= False¶ SQLite supports transactional DDL, but pysqlite does not: see: http://bugs.python.org/issue10740
-