API Details — Alembic v0.1.0 documentation

### Navigation

- index
- modules |
- previous |
- Alembic v0.1.0 documentation »

# API Details

This section describes some key functions used within the migration process, particularly those referenced within a migration environment’s `env.py` file.

## env.py Directives

The `alembic.context` module contains API features that are generally used within `env.py` files.

The central object in use is the `Context` object. This object is made present when the `env.py` script calls upon the `configure()` method for the first time. Before this function is called, there’s not yet any database connection or dialect-specific state set up, and those functions which require this state will raise an exception when used, until `configure()` is called successfully.

`sqlalchemy.engine.` `engine_from_config`(configuration, prefix='sqlalchemy.', **kwargs)

  Create a new Engine instance using a configuration dictionary.

  The dictionary is typically produced from a config file where keys are prefixed, such as sqlalchemy.url, sqlalchemy.echo, etc. The ‘prefix’ argument indicates the prefix to be searched for.

  A select set of keyword arguments will be “coerced” to their expected type based on string values. In a future release, this functionality will be expanded and include dialect-specific arguments.

class `alembic.context.` `Context`(dialect, script, connection, fn, as_sql=False, output_buffer=None, transactional_ddl=None, starting_rev=None, compare_type=False, compare_server_default=False)

  Maintains state throughout the migration running process.

  Mediates the relationship between an `env.py` environment script, a `ScriptDirectory` instance, and a `DefaultImpl` instance.

  The `Context` is available directly via the `get_context()` function, though usually it is referenced behind the scenes by the various module level functions within the `alembic.context` module.

  `bind`

    Return the current “bind”.

    In online mode, this is an instance of `sqlalchemy.engine.base.Connection`, and is suitable for ad-hoc execution of any kind of usage described in SQL Expression Language Tutorial as well as for usage with the `sqlalchemy.schema.Table.create()` and `sqlalchemy.schema.MetaData.create_all()` methods of `Table`, `MetaData`.

    Note that when “standard output” mode is enabled, this bind will be a “mock” connection handler that cannot return results and is only appropriate for a very limited subset of commands.

`alembic.context.` `begin_transaction`()

  Return a context manager that will enclose an operation within a “transaction”, as defined by the environment’s offline and transactional DDL settings.

  e.g.:

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

  `begin_transaction()` is intended to “do the right thing” regardless of calling context:

  - If `is_transactional_ddl()` is `False`, returns a “do nothing” context manager which otherwise produces no transactional state or directives.
  - If `is_offline_mode()` is `True`, returns a context manager that will invoke the `DefaultImpl.emit_begin()` and `DefaultImpl.emit_commit()` methods, which will produce the string directives `BEGIN` and `COMMIT` on the output stream, as rendered by the target backend (e.g. SQL Server would emit `BEGIN TRANSACTION`).
  - Otherwise, calls `sqlalchemy.engine.base.Connection.begin()` on the current online connection, which returns a `sqlalchemy.engine.base.Transaction` object. This object demarcates a real transaction and is itself a context manager, which will roll back if an exception is raised.

  Note that a custom `env.py` script which has more specific transactional needs can of course manipulate the `Connection` directly to produce transactional state in “online” mode.

`alembic.context.` `config`

  The current `Config` object.

  This is the gateway to the `alembic.ini` or other .ini file in use for the current command.

  This function does not require that the `Context` has been configured.

`alembic.context.` `configure`(connection=None, url=None, dialect_name=None, transactional_ddl=None, output_buffer=None, starting_rev=None, tag=None, target_metadata=None, compare_type=False, compare_server_default=False, upgrade_token='upgrades', downgrade_token='downgrades', sqlalchemy_module_prefix='sa.', **kw)

  Configure the migration environment.

  The important thing needed here is first a way to figure out what kind of “dialect” is in use. The second is to pass an actual database connection, if one is required.

  If the `is_offline_mode()` function returns `True`, then no connection is needed here. Otherwise, the `connection` parameter should be present as an instance of `sqlalchemy.engine.base.Connection`.

  This function is typically called from the `env.py` script within a migration environment. It can be called multiple times for an invocation. The most recent `Connection` for which it was called is the one that will be operated upon by the next call to `run_migrations()`.

  General parameters:

  Parameters: | connection – a `Connection` to use for SQL execution in “online” mode. When present, is also used to determine the type of dialect in use. url – a string database url, or a `sqlalchemy.engine.url.URL` object. The type of dialect to be used will be derived from this if `connection` is not passed. dialect_name – string name of a dialect, such as “postgresql”, “mssql”, etc. The type of dialect to be used will be derived from this if `connection` and `url` are not passed. transactional_ddl – Force the usage of “transactional” DDL on or off; this otherwise defaults to whether or not the dialect in use supports it. output_buffer – a file-like object that will be used for textual output when the `--sql` option is used to generate SQL scripts. Defaults to `sys.stdout` if not passed here and also not present on the `Config` object. The value here overrides that of the `Config` object. 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.

  Parameters specific to the autogenerate feature, when `alembic revision` is run with the `--autogenerate` feature:

  - Parameters: | target_metadata – a `sqlalchemy.schema.MetaData` object that will be consulted during autogeneration. The tables present will be compared against what is locally available on the target `Connection` to produce candidate upgrade/downgrade operations. compare_type – Indicates type comparison behavior during an autogenerate operation. Defaults to `False` which disables type comparison. Set to `True` to turn on default type comparison, which has varied accuracy depending on backend. To customize type comparison behavior, a callable may be specified which can filter type comparisons during an autogenerate operation. The format of this callable is:
        def my_compare_type(context, inspected_column,
                    metadata_column, inspected_type, metadata_type):
            # return True if the types are different,
            # False if not, or None to allow the default implementation
            # to compare these types
            pass
  - `inspected_column` is a dictionary structure as returned by `sqlalchemy.engine.reflection.Inspector.get_columns()`, whereas `metadata_column` is a `sqlalchemy.schema.Column` from the local model environment. A return value of `None` indicates to allow default type comparison to proceed. compare_server_default – Indicates server default comparison behavior during an autogenerate operation. Defaults to `False` which disables server default comparison. Set to `True` to turn on server default comparison, which has varied accuracy depending on backend. To customize server default comparison behavior, a callable may be specified which can filter server default comparisons during an autogenerate operation. defaults during an autogenerate operation. The format of this callable is:
        def my_compare_server_default(context, inspected_column,
                    metadata_column, inspected_default, metadata_default,
                    rendered_metadata_default):
            # return True if the defaults are different,
            # False if not, or None to allow the default implementation
            # to compare these defaults
            pass
  `inspected_column` is a dictionary structure as returned by `sqlalchemy.engine.reflection.Inspector.get_columns()`, whereas `metadata_column` is a `sqlalchemy.schema.Column` from the local model environment. A return value of `None` indicates to allow default server default comparison to proceed. Note that some backends such as Postgresql actually execute the two defaults on the database side to compare for equivalence. upgrade_token – When autogenerate completes, the text of the candidate upgrade operations will be present in this template variable when `script.py.mako` is rendered. Defaults to `upgrades`. downgrade_token – When autogenerate completes, the text of the candidate downgrade operations will be present in this template variable when `script.py.mako` is rendered. Defaults to `downgrades`. sqlalchemy_module_prefix – When autogenerate refers to SQLAlchemy `Column` or type classes, this prefix will be used (i.e. `sa.Column("somename", sa.Integer)`) Defaults to “`sa.`”. Can be `None` to indicate no prefix. Note that when dialect-specific types are rendered, autogenerate will render them using the dialect module name, i.e. `mssql.BIT()`, `postgresql.UUID()`.

  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.

`alembic.context.` `configure_connection`(connection)

  Deprecated; use `alembic.context.configure()`.

`alembic.context.` `execute`(sql)

  Execute the given SQL using the current change context.

  The behavior of `context.execute()` is the same as that of `op.execute()`. Please see that function’s documentation for full detail including caveats and limitations.

  This function requires that a `Context` has first been made available via `configure()`.

`alembic.context.` `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 `Context` has first been made available via `configure()`.

`alembic.context.` `get_context`()

  Return the current `Context` object.

  If `configure()` has not been called yet, raises an exception.

  Generally, env.py scripts should access the module-level functions in `alebmic.context` to get at this object’s functionality.

`alembic.context.` `get_head_revision`()

  Return the hex identifier of the ‘head’ revision.

  This function does not require that the `Context` has been configured.

`alembic.context.` `get_revision_argument`()

  Get the ‘destination’ revision argument.

  This is typically the argument passed to the `upgrade` or `downgrade` command.

  If it was specified as `head`, the actual version number is returned; if specified as `base`, `None` is returned.

  This function does not require that the `Context` has been configured.

`alembic.context.` `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 `Context` has been configured.

`alembic.context.` `get_tag_argument`()

  Return the value passed for the `--tag` argument, if any.

  The `--tag` argument is not used directly by Alembic, but is available for custom `env.py` configurations that wish to use it; particularly for offline generation scripts that wish to generate tagged filenames.

  This function does not require that the `Context` has been configured.

`alembic.context.` `is_offline_mode`()

  Return True if the current migrations environment is running in “offline mode”.

  This is `True` or `False` depending on the the `--sql` flag passed.

  This function does not require that the `Context` has been configured.

`alembic.context.` `is_transactional_ddl`()

  Return True if the context is configured to expect a transactional DDL capable backend.

  This defaults to the type of database in use, and can be overridden by the `transactional_ddl` argument to `configure()`

  This function requires that a `Context` has first been made available via `configure()`.

`alembic.context.` `run_migrations`(**kw)

  Run migrations as determined by the current command line configuration as well as versioning information present (or not) in the current database connection (if one is present).

  The function accepts optional `**kw` arguments. If these are passed, they are sent directly to the `upgrade()` and `downgrade()` functions within each target revision file. By modifying the `script.py.mako` file so that the `upgrade()` and `downgrade()` functions accept arguments, parameters can be passed here so that contextual information, usually information to identify a particular database in use, can be passed from a custom `env.py` script to the migration functions.

  This function requires that a `Context` has first been made available via `configure()`.

`alembic.context.` `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.

## 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")

`alembic.command.` `branches`(config)

  Show current un-spliced branch points

`alembic.command.` `current`(config)

  Display the current revision for each database.

`alembic.command.` `downgrade`(config, revision, sql=False, tag=None)

  Revert to a previous version.

`alembic.command.` `history`(config)

  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.` `revision`(config, message=None, autogenerate=False)

  Create a new revision file.

`alembic.command.` `splice`(config, parent, child)

  ‘splice’ two branches, creating a new revision file.

  this command isn’t implemented right now.

`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

class `alembic.config.` `Config`(file_, ini_section='alembic', output_buffer=None)

  Represent an Alembic configuration.

  Within an `env.py` script, this is available via the `alembic.context.config` attribute:

      from alembic import context

      some_param = context.config.get_main_option("my option")

  When invoking Alembic programatically, a new `Config` can be created simply by passing the name of an .ini file to the constructor:

      from alembic.config import Config
      alembic_cfg = Config("/path/to/yourapp/alembic.ini")

  With a `Config` object, you can then run Alembic commands programmatically using the directives in `alembic.command`.

  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 `Context` - used to redirect access when using Alembic programmatically.

  `config_file_name`

    Filesystem path to the .ini file in use.

  `config_ini_section`

    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.

  `get_main_option`(name, default=None)

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

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

  `get_section`(name)

    Return all the configuration options from a given .ini file section as a dictionary.

  `get_section_option`(section, name, default=None)

    Return an option from the given section of the .ini file.

  `get_template_directory`()

    Return the directory where Alembic setup templates are found.

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

  `set_main_option`(name, value)

    Set an option programmatically within the ‘main’ section.

    This overrides whatever was in the .ini file.

`alembic.config.` `main`(argv=None, **kwargs)

  The console runner function for Alembic.

## Internals

class `alembic.script.` `Script`(module, rev_id)

  Represent a single revision file in a `versions/` directory.

  `add_nextrev`(rev)
  `doc`
  classmethod `from_filename`(dir_, filename)
  classmethod `from_path`(path)
  `is_branch_point`
  `is_head`

class `alembic.script.` `ScriptDirectory`(dir)

  Provides operations upon an Alembic script directory.

  `copy_file`(src, dest)
  `downgrade_to`(destination, current_rev)
  `env_py_location`
  classmethod `from_config`(config)
  `generate_rev`(revid, message, refresh=False, **kw)
  `generate_template`(src, dest, **kw)
  `run_env`()

    Run the script environment.

    This basically runs the `env.py` script present in the migration environment. It is called exclusively by the command functions in `alembic.command`.

    As `env.py` runs `context.configure_connection()`, the connection environment should be set up first. This is typically achieved using the `context.opts()`.

  `upgrade_from`(destination, current_rev)
  `walk_revisions`()

    Iterate through all revisions.

    This is actually a breadth-first tree traversal, with leaf nodes being heads.

  `write`(rev_id, content)

### DDL Internals

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)
  `add_constraint`(const)
  `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)
  `bind`
  `bulk_insert`(table, rows)
  `compare_server_default`(inspector_column, metadata_column, rendered_metadata_default)
  `compare_type`(inspector_column, metadata_column)
  `create_index`(index)
  `create_table`(table)
  `drop_column`(table_name, column, **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 `context.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 `context.begin_transaction()`.

  `execute`(sql)
  classmethod `get_by_dialect`(dialect)
  `rename_table`(old_table_name, new_table_name, schema=None)
  `start_migrations`()

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

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

  `static_output`(text)

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

#### MySQL

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

  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)

#### 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)
  `bulk_insert`(table, rows)
  `drop_column`(table_name, column, **kw)
  `emit_begin`()

`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_rename_column`(element, compiler, **kw)

#### Postgresql

class `alembic.ddl.postgresql.` `PostgresqlImpl`(dialect, connection, as_sql, transactional_ddl, output_buffer, context_opts)

  Bases: `alembic.ddl.impl.DefaultImpl`

  `compare_server_default`(inspector_column, metadata_column, rendered_metadata_default)

#### SQLite

class `alembic.ddl.sqlite.` `SQLiteImpl`(dialect, connection, as_sql, transactional_ddl, output_buffer, context_opts)

  Bases: `alembic.ddl.impl.DefaultImpl`

### Navigation

- index
- modules |
- previous |
- Alembic v0.1.0 documentation »