Configuration — Alembic 0.8.5 documentation

# Configuration

Note

this section discusses the internal API of Alembic as regards internal configuration constructs. This section is only useful for developers who wish to extend the capabilities of Alembic. For documentation on configuration of an Alembic environment, please see Tutorial.

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 the `env.py` module within the migration environment
- to programatically run any of the commands in the Commands 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 a `MigrationContext`.

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 the `EnvironmentContext.config` attribute, which in turn is available at `alembic.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 in `alembic.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")

  Warning

  When using programmatic configuration, make sure the `env.py` file in use is compatible with the target configuration; including that the call to Python `logging.fileConfig()` is omitted if the programmatic configuration doesn’t actually include logging directives.

  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 the `Config.file_config` attribute is first invoked, the replacement variable `here` will be added to this dictionary before the dictionary is passed to `SafeConfigParser()` 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. See also Sharing a Connection with a Series of Migration Commands and Environments

  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 `sqlalchemy.engine.base.Connection` when calling commands from `alembic.command` programmatically.

    New in version 0.7.5.

    See also

    Sharing a Connection with a Series of Migration Commands and Environments

    `Config.attributes`

  `cmd_opts` = None

    The command-line options passed to the `alembic` script.

    Within an `env.py` script this can be accessed via the `EnvironmentContext.config` attribute.

    New in version 0.6.0.

    See also

    `EnvironmentContext.get_x_argument()`

  `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()` and `Config.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` and `list_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.

    Parameters: | name – name of the value value – the value. Note that this value is passed to `ConfigParser.set`, which supports variable interpolation using pyformat (e.g. `%(some_value)s`). A raw percent sign not part of an interpolation symbol must therefore be escaped, e.g. `%%`. The given value may refer to another value already in the file using the interpolation format.

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

    Parameters: | section – name of the section name – name of the value value – the value. Note that this value is passed to `ConfigParser.set`, which supports variable interpolation using pyformat (e.g. `%(some_value)s`). A raw percent sign not part of an interpolation symbol must therefore be escaped, e.g. `%%`. The given value may refer to another value already in the file using the interpolation format.

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

  The console runner function for Alembic.