DDL Internals — Alembic 0.8.9 documentation

# DDL Internals

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

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

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

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

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

  Represent an ALTER TABLE statement.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`alembic.ddl.base.` `quote_dotted`(name, quote)

  quote the elements of a dotted name

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

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

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

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

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

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

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

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

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

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

  `add_column`(table_name, column, schema=None)
  `add_constraint`(const)
  `alter_column`(table_name, column_name, nullable=None, server_default=False, name=None, type_=None, schema=None, autoincrement=None, existing_type=None, existing_server_default=None, existing_nullable=None, existing_autoincrement=None)
  `autogen_column_reflect`(inspector, table, column_info)

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

    Dialects can elect to modify the information gathered here.

  `bind`
  `bulk_insert`(table, rows, multiinsert=True)
  `command_terminator` = ';'
  `compare_server_default`(inspector_column, metadata_column, rendered_metadata_default, rendered_inspector_default)
  `compare_type`(inspector_column, metadata_column)
  `correct_for_autogen_constraints`(conn_uniques, conn_indexes, metadata_unique_constraints, metadata_indexes)
  `correct_for_autogen_foreignkeys`(conn_fks, metadata_fks)
  `create_index`(index)
  `create_table`(table)
  `drop_column`(table_name, column, schema=None, **kw)
  `drop_constraint`(const)
  `drop_index`(index)
  `drop_table`(table)
  `emit_begin`()

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

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

  `emit_commit`()

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

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

  `execute`(sql, execution_options=None)
  classmethod `get_by_dialect`(dialect)
  `prep_table_for_batch`(table)

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

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

  `rename_table`(old_table_name, new_table_name, schema=None)
  `requires_recreate_in_batch`(batch_op)

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

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

  `start_migrations`()

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

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

  `static_output`(text)
  `transactional_ddl` = False

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

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

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

  E.g.:

      from sqlalchemy import text

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

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

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

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

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

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

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

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

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

  The `text()` construct is used in cases when a literal string SQL fragment is specified as part of a larger query, such as for the WHERE clause of a SELECT statement:

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

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

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

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

  - Parameters: | text – the text of the SQL statement to be created. use `:<param>` to specify bind parameters; they will be compiled to their engine-specific format. autocommit – Deprecated. Use .execution_options(autocommit=<True|False>) to set the autocommit option. bind – an optional connection or engine to be used for this text query. bindparams – Deprecated. A list of `bindparam()` instances used to provide information about parameters embedded in the statement. This argument now invokes the `TextClause.bindparams()` method on the construct before returning it. E.g.:
        stmt = text("SELECT * FROM table WHERE id=:id",
                  bindparams=[bindparam('id', value=5, type_=Integer)])
    Is equivalent to:
        stmt = text("SELECT * FROM table WHERE id=:id").\
                  bindparams(bindparam('id', value=5, type_=Integer))
  - Deprecated since version 0.9.0: the `TextClause.bindparams()` method supersedes the `bindparams` argument to `text()`. typemap – Deprecated. A dictionary mapping the names of columns represented in the columns clause of a `SELECT` statement to type objects, which will be used to perform post-processing on columns within the result set. This parameter now invokes the `TextClause.columns()` method, which returns a `TextAsFrom` construct that gains a `.c` collection and can be embedded in other expressions. E.g.:
        stmt = text("SELECT * FROM table",
                      typemap={'id': Integer, 'name': String},
                  )
    Is equivalent to:
        stmt = text("SELECT * FROM table").columns(id=Integer,
                                                   name=String)
    Or alternatively:
        from sqlalchemy.sql import column
        stmt = text("SELECT * FROM table").columns(
                              column('id', Integer),
                              column('name', String)
                          )
  Deprecated since version 0.9.0: the `TextClause.columns()` method supersedes the `typemap` argument to `text()`.

## MySQL

class `alembic.ddl.mysql.` `MySQLAlterDefault`(name, column_name, default, schema=None)

  Bases: `alembic.ddl.base.AlterColumn`

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

  Bases: `alembic.ddl.base.AlterColumn`

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

  Bases: `alembic.ddl.impl.DefaultImpl`

  `alter_column`(table_name, column_name, nullable=None, server_default=False, name=None, type_=None, schema=None, existing_type=None, existing_server_default=None, existing_nullable=None, autoincrement=None, existing_autoincrement=None, **kw)
  `compare_server_default`(inspector_column, metadata_column, rendered_metadata_default, rendered_inspector_default)
  `correct_for_autogen_constraints`(conn_unique_constraints, conn_indexes, metadata_unique_constraints, metadata_indexes)
  `correct_for_autogen_foreignkeys`(conn_fks, metadata_fks)
  `drop_constraint`(const)
  `transactional_ddl` = False

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

  Bases: `alembic.ddl.mysql.MySQLChangeColumn`

## MS-SQL

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

  Bases: `alembic.ddl.impl.DefaultImpl`

  `alter_column`(table_name, column_name, nullable=None, server_default=False, name=None, type_=None, schema=None, existing_type=None, existing_server_default=None, existing_nullable=None, **kw)
  `batch_separator` = 'GO'
  `bulk_insert`(table, rows, **kw)
  `drop_column`(table_name, column, **kw)
  `emit_begin`()
  `emit_commit`()
  `transactional_ddl` = True

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

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

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

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

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

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

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

## Postgresql

class `alembic.ddl.postgresql.` `PostgresqlColumnType`(name, column_name, type_, **kw)

  Bases: `alembic.ddl.base.AlterColumn`

class `alembic.ddl.postgresql.` `PostgresqlImpl`(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, **kw)
  `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.` `text`(text, bind=None, bindparams=None, typemap=None, autocommit=None)

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

  E.g.:

      from sqlalchemy import text

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

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

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

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

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

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

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

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

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

  The `text()` construct is used in cases when a literal string SQL fragment is specified as part of a larger query, such as for the WHERE clause of a SELECT statement:

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

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

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

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

  - Parameters: | text – the text of the SQL statement to be created. use `:<param>` to specify bind parameters; they will be compiled to their engine-specific format. autocommit – Deprecated. Use .execution_options(autocommit=<True|False>) to set the autocommit option. bind – an optional connection or engine to be used for this text query. bindparams – Deprecated. A list of `bindparam()` instances used to provide information about parameters embedded in the statement. This argument now invokes the `TextClause.bindparams()` method on the construct before returning it. E.g.:
        stmt = text("SELECT * FROM table WHERE id=:id",
                  bindparams=[bindparam('id', value=5, type_=Integer)])
    Is equivalent to:
        stmt = text("SELECT * FROM table WHERE id=:id").\
                  bindparams(bindparam('id', value=5, type_=Integer))
  - Deprecated since version 0.9.0: the `TextClause.bindparams()` method supersedes the `bindparams` argument to `text()`. typemap – Deprecated. A dictionary mapping the names of columns represented in the columns clause of a `SELECT` statement to type objects, which will be used to perform post-processing on columns within the result set. This parameter now invokes the `TextClause.columns()` method, which returns a `TextAsFrom` construct that gains a `.c` collection and can be embedded in other expressions. E.g.:
        stmt = text("SELECT * FROM table",
                      typemap={'id': Integer, 'name': String},
                  )
    Is equivalent to:
        stmt = text("SELECT * FROM table").columns(id=Integer,
                                                   name=String)
    Or alternatively:
        from sqlalchemy.sql import column
        stmt = text("SELECT * FROM table").columns(
                              column('id', Integer),
                              column('name', String)
                          )
  Deprecated since version 0.9.0: the `TextClause.columns()` method supersedes the `typemap` argument to `text()`.

`alembic.ddl.postgresql.` `visit_column_type`(element, compiler, **kw)

`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