diff options
Diffstat (limited to 'docs/build/api.rst')
| -rw-r--r-- | docs/build/api.rst | 13 |
1 files changed, 13 insertions, 0 deletions
diff --git a/docs/build/api.rst b/docs/build/api.rst index 48da805..fea4e14 100644 --- a/docs/build/api.rst +++ b/docs/build/api.rst @@ -87,6 +87,19 @@ object, as in:: alembic_cfg = Config("/path/to/yourapp/alembic.ini") command.upgrade(alembic_cfg, "head") +In many cases, and perhaps more often than not, an application will wish +to call upon a series of Alembic commands and/or other features. It is +usually a good idea to link multiple commands along a single connection +and transaction, if feasible. This can be achieved using the +:attr:`.Config.attributes` dictionary in order to share a connection:: + + with engine.begin() as connection: + alembic_cfg.attributes['connection'] = connection + command.upgrade(alembic_cfg, "head") + +This recipe requires that ``env.py`` consumes this connection argument; +see the example in :ref:`connection_sharing` for details. + To write small API functions that make direct use of database and script directory information, rather than just running one of the built-in commands, use the :class:`.ScriptDirectory` and :class:`.MigrationContext` |