Configuration — Alembic 1.15.2 documentation

Skip to main content
`Ctrl`+`K`

# 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 programmatically 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_: str | ~os.PathLike[str] | None = None, ini_section: str = 'alembic', output_buffer: ~typing.TextIO | None = None, stdout: ~typing.TextIO = <_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, cmd_opts: ~argparse.Namespace | None = None, config_args: ~typing.Mapping[str, ~typing.Any] = {}, attributes: ~typing.Dict[str, ~typing.Any] | None = 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 programmatically, 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("sqlalchemy.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`.

    - 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 `ConfigParser()` to parse the .ini file.

    - attributes –

      optional dictionary of arbitrary Python keys/values, which will be populated into the `Config.attributes` dictionary.

      See also

      Sharing a Connection across one or more programmatic migration commands

  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.

    See also

    Sharing a Connection across one or more programmatic migration commands

    `Config.attributes`

  cmd_opts: Namespace | None = None

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

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

    See also

    `EnvironmentContext.get_x_argument()`

  config_file_name: str | PathLike[str] | None = None

    Filesystem path to the .ini file in use.

  config_ini_section: str = 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 runner.

  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: str, default: str) → str
  get_main_option(name: str, default: str | None = None) → str | 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: str, default: None = None) → Dict[str, str] | None
  get_section(name: str, default: Dict[str, str]) → Dict[str, str]
  get_section(name: str, default: Mapping[str, str]) → Dict[str, str] | Mapping[str, str]

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

    If the given section does not exist, the value of `default` is returned, which is expected to be a dictionary or other mapping.

  get_section_option(section: str, name: str, default: str | None = None) → str | None

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

  get_template_directory() → str

    Return the directory where Alembic setup templates are found.

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

  messaging_opts

    The messaging options.

  print_stdout(text: str, *arg: Any) → None

    Render a message to standard out.

    When `Config.print_stdout()` is called with additional args those arguments will formatted against the provided text, otherwise we simply output the provided text verbatim.

    This is a no-op when the``quiet`` messaging option is enabled.

    e.g.:

        >>> config.print_stdout('Some text %s', 'arg')
        Some Text arg

  set_main_option(name: str, value: str) → None

    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: str, name: str, value: str) → None

    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.

class alembic.config.MessagingOptions

alembic.config.main(argv: Sequence[str] | None = None, prog: str | None = None, **kwargs: Any) → None

  The console runner function for Alembic.