:class:`.MigrationScript` object. For an example of what this looks like,
see the example in :ref:`customizing_revision`.
- .. versionadded:: 0.8.0
-
.. seealso::
:func:`.compare_metadata` - returns more fundamental "diff"
within hooks such as the
:paramref:`.EnvironmentContext.configure.render_item` hook.
- .. versionadded:: 0.8.3
-
.. seealso::
:ref:`autogen_render_types`
for each individual :class:`.MetaData` in the order of the
sequence. It does **not** collate the sorted tables collections.
- .. versionadded:: 0.9.0
-
"""
result = []
for m in util.to_list(self.metadata):
Duplicate table keys are **not** supported; if two :class:`.MetaData`
objects contain the same table key, an exception is raised.
- .. versionadded:: 0.9.0
-
"""
result = {}
for m in util.to_list(self.metadata):
:ref:`autogen_rewriter` - usage example
- .. versionadded:: 0.8
-
"""
_traverse = util.Dispatcher()
the other parameters, this option is only available via programmatic
use of :func:`.command.revision`
- .. versionadded:: 0.9.0
-
"""
script_directory = ScriptDirectory.from_config(config)
def merge(config, revisions, message=None, branch_label=None, rev_id=None):
"""Merge two revisions together. Creates a new migration file.
- .. versionadded:: 0.7.0
-
:param config: a :class:`.Config` instance
:param message: string message to apply to the revision
:param indicate_current: indicate current revision.
- ..versionadded:: 0.9.9
-
"""
script = ScriptDirectory.from_config(config)
:param stdout: buffer where the "print" output of commands will be sent.
Defaults to ``sys.stdout``.
- .. versionadded:: 0.4
-
:param 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
dictionary before the dictionary is passed to ``SafeConfigParser()``
to parse the .ini file.
- .. versionadded:: 0.7.0
-
:param attributes: optional dictionary of arbitrary Python keys/values,
which will be populated into the :attr:`.Config.attributes` dictionary.
- .. versionadded:: 0.7.5
-
.. seealso::
:ref:`connection_sharing`
Within an ``env.py`` script this can be accessed via the
:attr:`.EnvironmentContext.config` attribute.
- .. versionadded:: 0.6.0
-
.. seealso::
:meth:`.EnvironmentContext.get_x_argument`
a :class:`sqlalchemy.engine.base.Connection` when calling
commands from :mod:`alembic.command` programmatically.
- .. versionadded:: 0.7.5
-
.. seealso::
:ref:`connection_sharing`
when issuing DDL for this constraint.
:param schema: Optional schema name to operate within.
- .. versionadded:: 0.9.0
-
"""
op = cls(constraint_name, table_name, elements, **kw)
return operations.invoke(op)
.. note:: This method is Postgresql specific, and additionally
requires at least SQLAlchemy 1.0.
- .. versionadded:: 0.9.0
-
.. seealso::
:meth:`.Operations.create_exclude_constraint`
is also available as a public API to facilitate adding custom
operations.
- .. versionadded:: 0.8.0
-
.. seealso::
:ref:`operation_plugins`
that will act as the structure of the table being copied. If omitted,
table reflection is used to retrieve the structure of the table.
- .. versionadded:: 0.7.6 Fully implemented the
- :paramref:`~.Operations.batch_alter_table.copy_from`
- parameter.
-
.. seealso::
:ref:`batch_offline_mode`
table that will be reflected, in lieu of passing the whole
:class:`~sqlalchemy.schema.Table` using
:paramref:`~.Operations.batch_alter_table.copy_from`.
-
- .. versionadded:: 0.7.1
-
:param reflect_kwargs: a dictionary of additional keyword arguments
that will be applied to the table structure being copied; this may be
used to pass additional table and reflection options to the table that
will be reflected, in lieu of passing the whole
:class:`~sqlalchemy.schema.Table` using
:paramref:`~.Operations.batch_alter_table.copy_from`.
-
- .. versionadded:: 0.7.1
-
:param table_args: a sequence of additional positional arguments that
will be applied to the new :class:`~sqlalchemy.schema.Table` when
created, in addition to those copied from the source table.
when created, in addition to those copied from the source table.
This may be used to provide for additional table options that may
not be reflected.
-
- .. versionadded:: 0.7.0
-
:param naming_convention: a naming convention dictionary of the form
described at :ref:`autogen_naming_conventions` which will be applied
to the :class:`~sqlalchemy.schema.MetaData` during the reflection
:ref:`dropping_sqlite_foreign_keys`
- .. versionadded:: 0.7.1
-
:param partial_reordering: a list of tuples, each suggesting a desired
ordering of two or more columns in the newly created table. Requires
that :paramref:`.batch_alter_table.recreate` is set to ``"always"``.
"""Given a :class:`.MigrateOperation`, invoke it in terms of
this :class:`.Operations` instance.
- .. versionadded:: 0.8.0
-
"""
fn = self._to_impl.dispatch(
operation, self.migration_context.impl.__dialect__
was introduced in 0.9.2, the string disambiguation service is new
as of 0.9.4.
- .. versionadded:: 0.6.4
-
"""
if conv:
return conv(name)
This system is part of the operation extensibility API.
- .. versionadded:: 0.8.0
-
.. seealso::
:ref:`operation_objects`
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> constraint_name
- * type -> type_
-
"""
op = cls(constraint_name, table_name, type_=type_, schema=schema)
:meth:`.Operations.drop_constraint`
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> constraint_name
- * type -> type_
-
"""
op = cls(
constraint_name,
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> constraint_name
- * cols -> columns
-
"""
op = cls(constraint_name, table_name, columns, schema)
return operations.invoke(op)
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> constraint_name
- * source -> table_name
- * local_cols -> columns
-
"""
op = cls(constraint_name, table_name, columns, schema=schema, **kw)
:meth:`.Operations.create_unique_constraint`
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> constraint_name
-
"""
kw["schema"] = operations.impl.schema
op = cls(constraint_name, operations.impl.table_name, columns, **kw)
:param source_schema: Optional schema name of the source table.
:param referent_schema: Optional schema name of the destination table.
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> constraint_name
- * source -> source_table
- * referent -> referent_table
-
"""
op = cls(
:meth:`.Operations.create_foreign_key`
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> constraint_name
- * referent -> referent_table
-
"""
op = cls(
constraint_name,
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> constraint_name
- * source -> table_name
-
"""
op = cls(constraint_name, table_name, condition, schema=schema, **kw)
return operations.invoke(op)
:meth:`.Operations.create_check_constraint`
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> constraint_name
-
"""
op = cls(
constraint_name,
from sqlalchemy import text
op.create_index('ik_test', 't1', [text('lower(foo)')])
- .. versionadded:: 0.6.7 support for making use of the
- :func:`~sqlalchemy.sql.expression.text` construct in
- conjunction with
- :meth:`.Operations.create_index` in
- order to produce functional expressions within CREATE INDEX.
-
:param index_name: name of the index.
:param table_name: name of the owning table.
:param columns: a list consisting of string column names and/or
quoting of the schema outside of the default behavior, use
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
-
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
:param unique: If True, create a unique index.
:param quote:
See the documentation regarding an individual dialect at
:ref:`dialect_toplevel` for detail on documented arguments.
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> index_name
-
"""
op = cls(
index_name, table_name, columns, schema=schema, unique=unique, **kw
quoting of the schema outside of the default behavior, use
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
-
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
:param \**kw: Additional keyword arguments not mentioned above are
dialect specific, and passed in the form
``<dialectname>_<argname>``.
See the documentation regarding an individual dialect at
:ref:`dialect_toplevel` for detail on documented arguments.
- .. versionadded:: 0.9.5 Support for dialect-specific keyword
- arguments for DROP INDEX
-
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> index_name
- * tablename -> table_name
-
"""
op = cls(index_name, table_name=table_name, schema=schema, **kw)
return operations.invoke(op)
:meth:`.Operations.drop_index`
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> index_name
-
"""
op = cls(
]
)
- .. versionadded:: 0.7.0
-
:param table_name: Name of the table
:param \*columns: collection of :class:`~sqlalchemy.schema.Column`
objects within
quoting of the schema outside of the default behavior, use
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
-
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
:param \**kw: Other keyword arguments are passed to the underlying
:class:`sqlalchemy.schema.Table` object created for the command.
:return: the :class:`~sqlalchemy.schema.Table` object corresponding
to the parameters given.
- .. versionadded:: 0.7.0 - the :class:`~sqlalchemy.schema.Table`
- object is returned.
-
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> table_name
-
"""
op = cls(table_name, columns, **kw)
return operations.invoke(op)
quoting of the schema outside of the default behavior, use
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
-
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
:param \**kw: Other keyword arguments are passed to the underlying
:class:`sqlalchemy.schema.Table` object created for the command.
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> table_name
-
"""
op = cls(table_name, schema=schema, table_kw=kw)
operations.invoke(op)
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
"""
op = cls(old_table_name, new_table_name, schema=schema)
return operations.invoke(op)
quoting of the schema outside of the default behavior, use
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
-
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
:param postgresql_using: String argument which will indicate a
SQL expression to render within the Postgresql-specific USING clause
within ALTER COLUMN. This string is taken directly as raw SQL which
must explicitly include any necessary quoting or escaping of tokens
within the expression.
- .. versionadded:: 0.8.8
-
- .. versionchanged:: 0.8.0 The following positional argument names
- have been changed:
-
- * name -> new_column_name
-
"""
alt = cls(
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
-
"""
op = cls(table_name, column, schema=schema)
quoting of the schema outside of the default behavior, use
the SQLAlchemy construct
:class:`~sqlalchemy.sql.elements.quoted_name`.
-
- .. versionadded:: 0.7.0 'schema' can now accept a
- :class:`~sqlalchemy.sql.elements.quoted_name` construct.
-
:param mssql_drop_check: Optional boolean. When ``True``, on
Microsoft SQL Server only, first
drop the CHECK constraint on the column using a
works if the column has exactly one FK constraint which refers to
it, at the moment.
- .. versionadded:: 0.6.2
-
"""
op = cls(table_name, column_name, schema=schema, **kw)
still be rendered, rather than attempting to pass the values
as bound parameters.
- .. versionadded:: 0.6.4 :meth:`.Operations.inline_literal` can now
- be used with :meth:`.Operations.bulk_insert`, and the
- :paramref:`~.Operations.bulk_insert.multiinsert` flag has
- been added to assist in this usage when running in "online"
- mode.
-
:param table: a table object which represents the target of the INSERT.
:param rows: a list of dictionaries indicating rows.
in those cases where non-literal values are present in the
parameter sets.
- .. versionadded:: 0.6.4
-
"""
op = cls(table, rows, multiinsert=multiinsert)
and ``.downgrade_ops_list`` list-based attributes. These latter
attributes are always available at the very least as single-element lists.
- .. versionchanged:: 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 :class:`.MigrationScript` object.
-
.. seealso::
:ref:`customizing_revision`
attribute when dealing with a revision operation that does
multiple autogenerate passes.
- .. versionadded:: 0.8.1
-
"""
return self._upgrade_ops
attribute when dealing with a revision operation that does
multiple autogenerate passes.
- .. versionadded:: 0.8.1
-
"""
return self._downgrade_ops
This function does not require that the :class:`.MigrationContext`
has been configured.
- .. versionadded:: 0.7.0
-
"""
return self.script.as_revision_number("heads")
This function does not require that the :class:`.MigrationContext`
has been configured.
- .. versionadded:: 0.6.0
-
.. seealso::
:meth:`.EnvironmentContext.get_tag_argument`
:param transaction_per_migration: if True, nest each migration script
in a transaction rather than the full series of migrations to
run.
-
- .. versionadded:: 0.6.5
-
:param output_buffer: a file-like object that will be used
for textual output
when the ``--sql`` option is used to generate SQL scripts.
.. note:: the ``literal_binds`` flag is ignored on SQLAlchemy
versions prior to 0.8 where this feature is not supported.
- .. versionadded:: 0.7.6
-
.. seealso::
:meth:`.Operations.inline_literal`
only takes effect when the table is first created.
Defaults to True; setting to False should not be necessary and is
here for backwards compatibility reasons.
-
- .. versionadded:: 0.8.10 Added the
- :paramref:`.EnvironmentContext.configure.version_table_pk`
- flag and additionally established that the Alembic version table
- has a primary key constraint by default.
-
:param on_version_apply: a callable or collection of callables to be
run for each migration step.
The callables will be run in the order they are given, once for
current heads,
* ``run_args``: the ``**kwargs`` passed to :meth:`.run_migrations`.
- .. versionadded:: 0.9.3
-
-
Parameters specific to the autogenerate feature, when
``alembic revision`` is run with the ``--autogenerate`` feature:
what is locally available on the target
:class:`~sqlalchemy.engine.Connection`
to produce candidate upgrade/downgrade operations.
-
- .. versionchanged:: 0.9.0 the
- :paramref:`.EnvironmentContext.configure.target_metadata`
- parameter may now be passed a sequence of
- :class:`~sqlalchemy.schema.MetaData` objects to support
- autogeneration of multiple :class:`~sqlalchemy.schema.MetaData`
- collections.
-
:param compare_type: Indicates type comparison behavior during
an autogenerate
operation. Defaults to ``False`` which disables type
using the :paramref:`.EnvironmentContext.configure.include_name`
hook.
- .. versionadded:: 0.6.0
-
.. seealso::
:ref:`autogenerate_include_hooks`
within a table will be placed under a ``with batch_alter_table():``
directive, so that batch migrations will take place.
- .. versionadded:: 0.7.0
-
.. seealso::
:ref:`batch_migrations`
in order to future-proof migration files against reorganizations
in modules.
- .. versionchanged:: 0.7.0
- :paramref:`.EnvironmentContext.configure.user_module_prefix`
- no longer defaults to the value of
- :paramref:`.EnvironmentContext.configure.sqlalchemy_module_prefix`
- when left at ``None``; the ``__module__`` attribute is now used.
-
- .. versionadded:: 0.6.3 added
- :paramref:`.EnvironmentContext.configure.user_module_prefix`
-
.. seealso::
:ref:`autogen_module_prefix`
a :class:`.Rewriter` object. This is a helper object that
assists in the production of autogenerate-stream rewriter functions.
-
- .. versionadded:: 0.8.0
-
- .. versionchanged:: 0.8.1 - The
- :paramref:`.EnvironmentContext.configure.process_revision_directives`
- hook can append op directives into :class:`.UpgradeOps` and
- :class:`.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.
-
-
.. seealso::
:ref:`customizing_revision`
If no version table is present, or if there are no revisions
present, an empty tuple is returned.
- .. versionadded:: 0.7.0
-
"""
if self.as_sql:
start_from_rev = self._start_from_rev
towards that revision (either up or down). If no current branches
include the revision, it is added as a new branch head.
- .. versionadded:: 0.7.0
-
"""
heads = self.get_current_heads()
if not self.as_sql and not heads:
@property
def config(self):
- """Return the :class:`.Config` used by the current environment, if any.
-
- .. versionadded:: 0.6.6
+ """Return the :class:`.Config` used by the current environment,
+ if any."""
- """
if self.environment_context:
return self.environment_context.config
else:
benefit of the :paramref:`.EnvironmentContext.on_version_apply`
callback hook.
- .. versionadded:: 0.9.3
-
"""
is_upgrade = None
``alembic stamp`` operation which is moving downwards from multiple
branches down to their common branch point.
- .. versionadded:: 0.9.4
-
"""
down_revision_ids = None
@property
def up_revisions(self):
- """Get :attr:`~.MigrationInfo.up_revision_ids` as a :class:`.Revision`.
-
- .. versionadded:: 0.9.4
-
- """
+ """Get :attr:`~.MigrationInfo.up_revision_ids` as a
+ :class:`.Revision`."""
return self.revision_map.get_revisions(self.up_revision_ids)
@property
all head revisions. May also be "head" to indicate a single
head revision.
- .. versionchanged:: 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.
-
"""
with self._catch_revision_errors(start=base, end=head):
for rev in self.revision_map.iterate_revisions(
"""Return the :class:`.Script` instance with the given rev identifier,
symbolic name, or sequence of identifiers.
- .. versionadded:: 0.7.0
-
"""
with self._catch_revision_errors():
return self.revision_map.get_revisions(id_)
This is the revision number of all scripts that
have a ``down_revision`` of None.
- .. versionadded:: 0.7.0
-
"""
return list(self.revision_map.bases)
:param head: the head revision to generate against. Defaults
to the current "head" if no branches are present, else raises
an exception.
-
- .. versionadded:: 0.7.0
-
:param 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.
Customizing Revision Generation
==========================================
-.. versionadded:: 0.8.0 - the ``alembic revision`` system is now customizable.
-
The ``alembic revision`` command, also available programmatically
via :func:`.command.revision`, essentially produces a single migration
script after being run. Whether or not the ``--autogenerate`` option
when referring to the collection of :class:`.UpgradeOps` and
:class:`.DowngradeOps` objects.
-.. versionchanged:: 0.8.1 - multiple calls to
- :meth:`.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.
-
-
.. _autogen_custom_ops:
Autogenerating Custom Operation Directives
we created in :ref:`operation_plugins`, which correspond to the
SQLAlchemy :class:`~sqlalchemy.schema.Sequence` construct.
-.. versionadded:: 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
----------------------------------
class decorator, then build a default "implementation" function which is
established using the :meth:`.Operations.implementation_for` decorator.
-.. versionadded:: 0.8.0 - the :class:`.Operations` class is now an
- open namespace that is extensible via the creation of new
- :class:`.MigrateOperation` subclasses.
-
Below we illustrate a very simple operation ``CreateSequenceOp`` which
will implement a new method ``op.create_sequence()`` for use in
migration scripts::
:ref:`autogen_custom_ops` - how to add autogenerate support to
custom operations.
-.. versionadded:: 0.8 - the migration operations available via the
- :class:`.Operations` class as well as the ``alembic.op`` namespace
- is now extensible using a plugin system.
-
-
.. _operation_objects:
.. _alembic.operations.ops.toplevel:
* Column additions, removals.
* Change of nullable status on columns.
* Basic changes in indexes and explicitly-named unique constraints
-
-.. versionadded:: 0.6.1 Support for autogenerate of indexes and unique constraints.
-
* Basic changes in foreign key constraints
-.. versionadded:: 0.7.1 Support for autogenerate of foreign key constraints.
-
Autogenerate can **optionally detect**:
* Change of column type. This will occur if you set
if two :class:`~sqlalchemy.schema.MetaData` objects contain a table
with the same schema/name combination, an error is raised.
-.. versionchanged:: 0.9.0 the
- :paramref:`.EnvironmentContext.configure.target_metadata`
- parameter may now be passed a sequence of
- :class:`~sqlalchemy.schema.MetaData` objects to support
- autogeneration of multiple :class:`~sqlalchemy.schema.MetaData`
- collections.
-
.. _autogenerate_include_hooks:
Controlling What to be Autogenerated
The imports for the above type again must be made present within the migration,
either manually, or by adding it to ``script.py.mako``.
-.. versionchanged:: 0.7.0
- The default module prefix rendering for a user-defined type now makes use
- of the type's ``__module__`` attribute to retrieve the prefix, rather than
- using the value of
- :paramref:`~.EnvironmentContext.configure.sqlalchemy_module_prefix`.
-
-
The above custom type has a long and cumbersome name based on the use
of ``__module__`` directly, which also implies that lots of imports would
be needed in order to accomodate lots of types. For this reason, it is
somewhere else, we only need modify the ``myapp.migration_types`` module,
instead of searching and replacing all instances within our migration scripts.
-.. versionadded:: 0.6.3 Added :paramref:`.EnvironmentContext.configure.user_module_prefix`.
-
.. _autogen_render_types:
Affecting the Rendering of Types Themselves
# default rendering for other objects
return False
-.. versionchanged:: 0.8 The ``autogen_context`` data member passed to
- the ``render_item`` callable is now an instance of :class:`.AutogenContext`.
-
-.. versionchanged:: 0.8.3 The "imports" data member of the autogen context
- is restored to the new :class:`.AutogenContext` object as
- :attr:`.AutogenContext.imports`.
-
The finished migration script will include our imports where the
``${imports}`` expression is used, producing output such as::
will be used, if present on the metadata type. If that returns ``None``,
then a basic check for type equivalence is run.
-.. versionadded:: 0.7.6 - added support for the ``compare_against_backend()``
- method.
-
.. versionadded:: 1.4.0 - added column keyword comparisons and the
``type_synonyms`` property.
Running "Batch" Migrations for SQLite and Other Databases
=========================================================
-.. note:: "Batch mode" for SQLite and other databases is a new and intricate
- feature within the 0.7.0 series of Alembic, and should be
- considered as "beta" for the next several releases.
-
-.. versionadded:: 0.7.0
-
The SQLite database presents a challenge to migration tools
in that it has almost no support for the ALTER statement upon which
relational schema migrations rely upon. The rationale for this stems from
pre-fabricated :class:`~sqlalchemy.schema.Table` object; see
:ref:`batch_offline_mode` for an example.
-.. versionadded:: 0.7.1
- added :paramref:`.Operations.batch_alter_table.reflect_args`
- and :paramref:`.Operations.batch_alter_table.reflect_kwargs` options.
-
.. _sqlite_batch_constraints:
Dealing with Constraints
Note that the naming convention feature requires at least
**SQLAlchemy 0.9.4** for support.
-.. versionadded:: 0.7.1
- added :paramref:`~.Operations.batch_alter_table.naming_convention` to
- :meth:`.Operations.batch_alter_table`.
-
Including unnamed UNIQUE constraints
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
referential integrity is disabled, consistent with the same requirement
for referring foreign keys from other tables.
-.. versionchanged:: 0.8.4 Self-referring foreign keys are created with the
- target table name in batch mode, even though this table will temporarily
- not exist when dropped. This requires that the target database is not
- enforcing referential integrity.
-
When SQLite's ``PRAGMA FOREIGN KEYS`` mode is turned on, it does provide
the service that foreign key constraints, including self-referential, will
automatically be modified to point to their table across table renames,
"move and copy" migrations and need them to generate flat SQL files in
"offline" mode, there's not much alternative.
-.. versionadded:: 0.7.6 Fully implemented the
- :paramref:`~.Operations.batch_alter_table.copy_from`
- parameter.
-
Batch mode with Autogenerate
----------------------------
Working with Branches
=====================
-.. note:: Alembic 0.7.0 features an all-new versioning model that fully
- supports branch points, merge points, and long-lived, labeled branches,
- including independent branches originating from multiple bases.
- A great emphasis has been placed on there being almost no impact on the
- existing Alembic workflow, including that all commands work pretty much
- the same as they did before, the format of migration files doesn't require
- any change (though there are some changes that are recommended),
- and even the structure of the ``alembic_version``
- table does not change at all. However, most alembic commands now offer
- new features which will break out an Alembic environment into
- "branch mode", where things become a lot more intricate. Working in
- "branch mode" should be considered as a "beta" feature, with many new
- paradigms and use cases still to be stress tested in the wild.
- Please tread lightly!
-
-.. versionadded:: 0.7.0
-
A **branch** describes a point in a migration stream when two or more
versions refer to the same parent migration as their anscestor. Branches
occur naturally when two divergent source trees, both containing Alembic
We also can of course add or alter this value within the file manually after
it is generated, rather than using the ``--depends-on`` argument.
-.. versionadded:: 0.8 The ``depends_on`` attribute may be set directly
- from the ``alembic revision`` command, rather than editing the file
- directly. ``depends_on`` identifiers may also be specified as
- branch names at the command line or directly within the migration file.
- The values may be specified as partial revision numbers from the command
- line which will be resolved to full revision numbers in the output file.
-
We can see the effect this directive has when we view the history
of the ``networking`` branch in terms of "heads", e.g., all the revisions that
are descendants::
connection doesn't actually close the outer connection, which stays
active for continued use.
-.. versionadded:: 0.7.5 Added :attr:`.Config.attributes`.
-
.. _replaceable_objects:
Replaceable Objects
dateutil.tz.gettz(<timezone>)
)
- .. versionadded:: 0.9.2
-
* ``truncate_slug_length`` - defaults to 40, the max number of characters
to include in the "slug" field.
- .. versionadded:: 0.6.1 - added ``truncate_slug_length`` configuration
-
* ``sqlalchemy.url`` - A URL to connect to the database via SQLAlchemy. This
configuration value is only used if the ``env.py`` file calls upon them;
in the "generic" template, the call to
generating new revision files, as well as when running the ``alembic history``
command.
- .. versionchanged:: 0.9.6 the ``alembic history`` command uses the environment
- unconditionally when ``revision_environment`` is set to true.
-
* ``sourceless`` - when set to 'true', revision files that only exist as .pyc
or .pyo files in the versions directory will be used as versions, allowing
"sourceless" versioning folders. When left at the default of 'false',
only .py files are consumed as version files.
- .. versionadded:: 0.6.4
-
* ``version_locations`` - an optional list of revision file locations, to
allow revisions to exist in multiple directories simultaneously.
See :ref:`multiple_bases` for examples.
- .. versionadded:: 0.7.0
-
* ``output_encoding`` - the encoding to use when Alembic writes the
``script.py.mako`` file into a new migration file. Defaults to ``'utf-8'``.
- .. versionadded:: 0.7.0
-
* ``[loggers]``, ``[handlers]``, ``[formatters]``, ``[logger_*]``, ``[handler_*]``,
``[formatter_*]`` - these sections are all part of Python's standard logging configuration,
the mechanics of which are documented at `Configuration File Format <http://docs.python.org/library/logging.config.html#configuration-file-format>`_.
$ alembic upgrade ae10+2
-.. versionadded:: 0.7.0 Support for relative migrations in terms of a specific
- revision.
-
Getting Information
===================
$ alembic history -r1975ea:
-.. versionadded:: 0.6.0 ``alembic revision`` now accepts the ``-r`` argument to
- specify specific ranges based on version numbers, symbols, or relative deltas.
-
-
Downgrading
===========
projects / thirdparty / sqlalchemy / alembic.git / commitdiff
