:param package: when True, write ``__init__.py`` files into the
environment location as well as the versions/ location.
- .. versionadded:: 1.2
-
-
"""
if os.access(directory, os.F_OK) and os.listdir(directory):
.. note:: this parameter is called "revisions" in the command line
interface.
- .. versionchanged:: 1.2 The revision may be a single revision or
- list of revisions when stamping multiple branch heads.
-
:param sql: use ``--sql`` mode
:param tag: an arbitrary "tag" that can be intercepted by custom
:param purge: delete all entries in the version table before stamping.
- .. versionadded:: 1.2
-
"""
script = ScriptDirectory.from_config(config)
``connection`` and ``url`` are not passed.
:param dialect_opts: dictionary of options to be passed to dialect
constructor.
-
- .. versionadded:: 1.0.12
-
:param transactional_ddl: Force the usage of "transactional"
DDL on or off;
this otherwise defaults to whether or not the dialect in
include_name = include_name
)
- .. versionadded:: 1.5
-
.. seealso::
:ref:`autogenerate_include_hooks`
"""Render a SQL expression that is typically a server default,
index expression, etc.
- .. versionadded:: 1.0.11
-
"""
compile_kw = {
Set to ``None`` to have the default removed.
:param comment: optional string text of a new comment to add to the
column.
-
- .. versionadded:: 1.0.6
-
:param new_column_name: Optional; specify a string name here to
indicate the new name within a column rename operation.
:param type\_: Optional; a :class:`~sqlalchemy.types.TypeEngine`
:param existing_comment: string text of the existing comment on the
column to be maintained. Required on MySQL if the existing comment
on the column is not being changed.
-
- .. versionadded:: 1.0.6
-
:param schema: Optional schema name to operate within. To control
quoting of the schema outside of the default behavior, use
the SQLAlchemy construct
set is undefined. Therefore it is best to specify the complete
ordering of all columns for best results.
- .. versionadded:: 1.4.0
-
.. note:: batch mode requires SQLAlchemy 0.8 or above.
.. seealso::
) -> None:
"""Emit a COMMENT ON operation to set the comment for a table.
- .. versionadded:: 1.0.6
-
:param table_name: string name of the target table.
:param comment: string value of the comment being registered against
the specified table.
"""Issue a "drop table comment" operation to
remove an existing comment set on a table.
- .. versionadded:: 1.0.6
-
:param table_name: string name of the target table.
:param existing_comment: An optional string value of a comment already
registered on the specified table.
set is undefined. Therefore it is best to specify the complete
ordering of all columns for best results.
- .. versionadded:: 1.4.0
-
.. note:: batch mode requires SQLAlchemy 0.8 or above.
.. seealso::
Set to ``None`` to have the default removed.
:param comment: optional string text of a new comment to add to the
column.
-
- .. versionadded:: 1.0.6
-
:param new_column_name: Optional; specify a string name here to
indicate the new name within a column rename operation.
:param type\_: Optional; a :class:`~sqlalchemy.types.TypeEngine`
:param existing_comment: string text of the existing comment on the
column to be maintained. Required on MySQL if the existing comment
on the column is not being changed.
-
- .. versionadded:: 1.0.6
-
:param schema: Optional schema name to operate within. To control
quoting of the schema outside of the default behavior, use
the SQLAlchemy construct
) -> None:
"""Emit a COMMENT ON operation to set the comment for a table.
- .. versionadded:: 1.0.6
-
:param table_name: string name of the target table.
:param comment: string value of the comment being registered against
the specified table.
"""Issue a "drop table comment" operation to
remove an existing comment set on a table.
- .. versionadded:: 1.0.6
-
:param table_name: string name of the target table.
:param existing_comment: An optional string value of a comment already
registered on the specified table.
:param insert_before: String name of an existing column which this
column should be placed before, when creating the new table.
- .. versionadded:: 1.4.0
-
:param insert_after: String name of an existing column which this
column should be placed after, when creating the new table. If
both :paramref:`.BatchOperations.alter_column.insert_before`
omitted, the column is inserted after the last existing column
in the table.
- .. versionadded:: 1.4.0
-
.. seealso::
:meth:`.Operations.alter_column`
"""Emit a COMMENT ON operation to set the comment for a table
using the current batch migration context.
- .. versionadded:: 1.6.0
-
:param comment: string value of the comment being registered against
the specified table.
:param existing_comment: String value of a comment
remove an existing comment set on a table using the current
batch operations context.
- .. versionadded:: 1.6.0
-
:param existing_comment: An optional string value of a comment already
registered on the specified table.
) -> None:
"""Emit a COMMENT ON operation to set the comment for a table.
- .. versionadded:: 1.0.6
-
:param table_name: string name of the target table.
:param comment: string value of the comment being registered against
the specified table.
"""Emit a COMMENT ON operation to set the comment for a table
using the current batch migration context.
- .. versionadded:: 1.6.0
-
:param comment: string value of the comment being registered against
the specified table.
:param existing_comment: String value of a comment
"""Issue a "drop table comment" operation to
remove an existing comment set on a table.
- .. versionadded:: 1.0.6
-
:param table_name: string name of the target table.
:param existing_comment: An optional string value of a comment already
registered on the specified table.
remove an existing comment set on a table using the current
batch operations context.
- .. versionadded:: 1.6.0
-
:param existing_comment: An optional string value of a comment already
registered on the specified table.
Set to ``None`` to have the default removed.
:param comment: optional string text of a new comment to add to the
column.
-
- .. versionadded:: 1.0.6
-
:param new_column_name: Optional; specify a string name here to
indicate the new name within a column rename operation.
:param type\_: Optional; a :class:`~sqlalchemy.types.TypeEngine`
:param existing_comment: string text of the existing comment on the
column to be maintained. Required on MySQL if the existing comment
on the column is not being changed.
-
- .. versionadded:: 1.0.6
-
:param schema: Optional schema name to operate within. To control
quoting of the schema outside of the default behavior, use
the SQLAlchemy construct
:param insert_before: String name of an existing column which this
column should be placed before, when creating the new table.
- .. versionadded:: 1.4.0
-
:param insert_after: String name of an existing column which this
column should be placed after, when creating the new table. If
both :paramref:`.BatchOperations.alter_column.insert_before`
omitted, the column is inserted after the last existing column
in the table.
- .. versionadded:: 1.4.0
-
.. seealso::
:meth:`.Operations.alter_column`
``connection`` and ``url`` are not passed.
:param dialect_opts: dictionary of options to be passed to dialect
constructor.
-
- .. versionadded:: 1.0.12
-
:param transactional_ddl: Force the usage of "transactional"
DDL on or off;
this otherwise defaults to whether or not the dialect in
include_name = include_name
)
- .. versionadded:: 1.5
-
.. seealso::
:ref:`autogenerate_include_hooks`
migrations whether or not one of them has an autocommit block.
- .. versionadded:: 1.2.0
-
"""
_in_connection_transaction = self._in_connection_transaction()
See the documentation linked below for an example.
- .. versionadded:: 1.2.0
-
.. seealso::
:ref:`post_write_hooks_custom`
The type comparison logic is fully extensible as well; see
:ref:`compare_types` for details.
- .. versionchanged:: 1.4 type comparison code has been reworked such that
- column types are compared based on their rendered DDL, which should allow
- the functionality enabled by
- :paramref:`.EnvironmentContext.configure.compare_type`
- to be much more accurate, correctly accounting for the behavior of
- SQLAlchemy "generic" types as well as major arguments specified within
- types.
-
* Change of server default. This will occur if you set
the :paramref:`.EnvironmentContext.configure.compare_server_default`
parameter to ``True``, or to a custom callable function.
object, the :paramref:`.EnvironmentContext.configure.include_object` hook
discussed in the next section is more appropriate.
-.. versionadded:: 1.5 added the :paramref:`.EnvironmentContext.configure.include_name`
- hook.
-
Omitting Based on Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
database backend sets as a default value without generating false
positives.
-.. versionchanged:: 1.4.0 Added the text and keyword comparison for column types
-
Alternatively, the :paramref:`.EnvironmentContext.configure.compare_type`
parameter accepts a callable function which may be used to implement custom type
comparison logic, for cases such as where special user defined types
will be used, if present on the metadata type. If that returns ``None``,
then a basic check for type equivalence is run.
-.. versionadded:: 1.4.0 - added column keyword comparisons and the
- ``type_synonyms`` property.
-
-
.. _post_write_hooks:
Applying Post Processing and Python Code Formatters to Generated Revisions
The post write hooks, when configured, run against generated revision files
regardless of whether or not the autogenerate feature was used.
-.. versionadded:: 1.2
-
.. note::
Alembic's post write system is partially inspired by the `pre-commit
target database will always generate some kind of name, if one is not
given.
-The first challenge this represents is that an unnamed constraint can't
+The challenge this represents is that an unnamed constraint can't
by itself be targeted by the :meth:`.BatchOperations.drop_constraint` method.
An unnamed FOREIGN KEY constraint is implicit whenever the
:class:`~sqlalchemy.schema.ForeignKey`
unnamed when they are created on the target database; an automatically generated
name will be assigned in the case of all other database backends.
-A second issue is that SQLAlchemy itself has inconsistent behavior in
-dealing with SQLite constraints as far as names. Prior to version 1.0,
-SQLAlchemy omits the name of foreign key constraints when reflecting them
-against the SQLite backend. So even if the target application has gone through
-the steps to apply names to the constraints as stated in the database,
-they still aren't targetable within the batch reflection process prior
-to SQLAlchemy 1.0.
-
Within the scope of batch mode, this presents the issue that the
:meth:`.BatchOperations.drop_constraint` method requires a constraint name
in order to target the correct constraint.
In order to overcome this, the :meth:`.Operations.batch_alter_table` method supports a
:paramref:`~.Operations.batch_alter_table.naming_convention` argument, so that
-all reflected constraints, including foreign keys that are unnamed, or
-were named but SQLAlchemy isn't loading this name, may be given a name,
-as described in :ref:`autogen_naming_conventions`. Usage is as follows::
+all reflected constraints, including foreign keys that are unnamed may be
+given a name, as described in :ref:`autogen_naming_conventions`.
+Usage is as follows::
naming_convention = {
"fk":
Note that the naming convention feature requires at least
**SQLAlchemy 0.9.4** for support.
-Including unnamed UNIQUE constraints
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A similar, but frustratingly slightly different, issue is that in the
-case of UNIQUE constraints, we again have the issue that SQLite allows
-unnamed UNIQUE constraints to exist on the database, however in this case,
-SQLAlchemy prior to version 1.0 doesn't reflect these constraints at all.
-It does properly reflect named unique constraints with their names, however.
-
-So in this case, the workaround for foreign key names is still not sufficient
-prior to SQLAlchemy 1.0. If our table includes unnamed unique constraints,
-and we'd like them to be re-created along with the table, we need to include
-them directly, which can be via the
-:paramref:`~.Operations.batch_alter_table.table_args` argument::
-
- with self.op.batch_alter_table(
- "bar", table_args=(UniqueConstraint('username'),)
- ):
- batch_op.add_column(Column('foo', Integer))
-
.. _batch_schematype_constraints:
Changing the Type of Boolean, Enum and other implicit CHECK datatypes
elem.table_name, schema=elem.schema
) as batch_ops:
for table_elem in elem.ops:
- # work around Alembic issue #753 (fixed in 1.5.0)
- if hasattr(table_elem, "column"):
- table_elem.column = table_elem.column.copy()
batch_ops.invoke(table_elem)
elif hasattr(elem, "ops"):
stack.extend(elem.ops)
else:
- # work around Alembic issue #753 (fixed in 1.5.0)
- if hasattr(elem, "column"):
- elem.column = elem.column.copy()
operations.invoke(elem)
Above, we detect elements that have a collection of operations by looking
for the ``.ops`` attribute. A check for :class:`.ModifyTableOps` allows
-us to use a batch context if we are supporting that. Finally there's a
-workaround for an Alembic issue that exists for SQLAlchemy 1.3.20 and greater
-combined with Alembic older than 1.5.
+us to use a batch context if we are supporting that.
A full example follows. The overall setup here is copied from the example
at :func:`.autogenerate.compare_metadata`::
elem.table_name, schema=elem.schema
) as batch_ops:
for table_elem in elem.ops:
- # work around Alembic issue #753 (fixed in 1.5.0)
- if hasattr(table_elem, "column"):
- table_elem.column = table_elem.column.copy()
batch_ops.invoke(table_elem)
elif hasattr(elem, "ops"):
stack.extend(elem.ops)
else:
- # work around Alembic issue #753 (fixed in 1.5.0)
- if hasattr(elem, "column"):
- elem.column = elem.column.copy()
operations.invoke(elem)
command line tool from this directory without our project being "installed" in
that environment.
-.. versionchanged:: 1.5.5 Fixed a long-standing issue where the ``alembic``
- command-line tool would not preserve the default ``sys.path`` of ``.``
- by implementing ``prepend_sys_path`` option.
-
As a final step, the `virtualenv activate <https://virtualenv.pypa.io/en/latest/userguide/#activate-script>`_
tool can be used so that the ``alembic`` command is available without any
path information, within the context of the current shell::
# sys.path path, will be prepended to sys.path if present.
# defaults to the current working directory.
- # (new in 1.5.5)
prepend_sys_path = .
# timezone to use when rendering the date within the migration file
projects / thirdparty / sqlalchemy / alembic.git / commitdiff
