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 environmentto create an
EnvironmentContext
, which allows you to actually run theenv.py
module within the migration environmentto 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 aMigrationContext
.
- class alembic.config.Config(file_: 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: ~sqlalchemy.cyextension.immutabledict.immutabledict = {}, attributes: dict | None = None)¶
Represent an Alembic configuration.
Within an
env.py
script, this is available via theEnvironmentContext.config
attribute, which in turn is available atalembic.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 inalembic.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 Pythonlogging.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 theConfig.file_config
attribute is first invoked, the replacement variablehere
will be added to this dictionary before the dictionary is passed toConfigParser()
to parse the .ini file.attributes –
optional dictionary of arbitrary Python keys/values, which will be populated into the
Config.attributes
dictionary.
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 fromalembic.command
programmatically.
- cmd_opts: Namespace | None = None¶
The command-line options passed to the
alembic
script.Within an
env.py
script this can be accessed via theEnvironmentContext.config
attribute.See also
- 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()
andConfig.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: Dict[str, str]) Dict[str, str] ¶
- get_section(name: str, default: Dict[str, str] | None = None) Dict[str, str] | None
Return all the configuration options from a given .ini file section as a dictionary.
- 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
andlist_templates
commands.
- print_stdout(text: str, *arg) 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.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.
- alembic.config.main(argv=None, prog=None, **kwargs)¶
The console runner function for Alembic.