import os
class Config(object):
+ """Represent an Alembic configuration.
+
+ You can get at one of these by specifying the name of
+ an .ini file::
+
+ from alembic.config import Config
+ alembic_cfg = Config("/path/to/yourapp/alembic.ini")
+
+ With a :class:`.Config` object, you can then
+ run Alembic commands programmatically using the directives
+ in :mod:`alembic.command`.
+
+ """
def __init__(self, file_, ini_section='alembic'):
self.config_file_name = file_
self.config_ini_section = ini_section
return default
def main(argv):
+ """The console runner function for Alembic."""
def add_options(parser, positional, kwargs):
if 'template' in kwargs:
what kind of "dialect" is in use. The second is to pass
an actual database connection, if one is required.
- If the :func:`requires_connection` function returns False,
+ If the :func:`.requires_connection` function returns False,
then no connection is needed here. Otherwise, the
- object should be an instance of :class:`sqlalchemy.engine.Connection`.
+ object should be an instance of :class:`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 :class:`~sqlalchemy.engine.Connection`
+ multiple times for an invocation. The most recent :class:`~sqlalchemy.engine.base.Connection`
for which it was called is the one that will be operated upon
by the next call to :func:`.run_migrations`.
- :param connection: a :class:`sqlalchemy.engine.Connection`. The type of dialect
+ :param connection: a :class:`sqlalchemy.engine.base.Connection`. The type of dialect
to be used will be derived from this.
:param url: a string database url, or a :class:`sqlalchemy.engine.url.URL` object.
The type of dialect to be used will be derived from this if ``connection`` is
"""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.
+
"""
_context.run_migrations(**kw)
get_context().execute(sql)
def get_context():
+ """Return the current :class:`.DefaultContext` object.
+
+ This object is the entrypoint to dialect specific behavior.
+
+ Generally, env.py scripts should access the module-level functions
+ in :mod:`alebmic.context` to get at this object's functionality.
+
+ """
if _context is None:
raise Exception("No context has been configured yet.")
return _context
\ No newline at end of file
_mod_def_re = re.compile(r'(upgrade|downgrade)_([a-z0-9]+)')
class ScriptDirectory(object):
+ """Provides operations upon an Alembic script directory.
+
+ """
def __init__(self, dir):
self.dir = dir
self.versions = os.path.join(self.dir, 'versions')
return script
class Script(object):
+ """Represent a single revision file in a ``versions/`` directory."""
nextrev = frozenset()
def __init__(self, module, rev_id):
Internals
=========
-.. automodule:: alembic.config
+.. currentmodule:: alembic.command
+
+Commands
+--------
+
+Alembic commands are all represented by functions in the :mod:`alembic.command`
+package. They all accept the same style of usage, being sent
+the :class:`~.alembic.config.Config` object as the first argument.
+
+
+.. automodule:: alembic.command
:members:
:undoc-members:
-.. automodule:: alembic.command
+Misc
+----
+.. automodule:: alembic.config
:members:
:undoc-members:
+
.. automodule:: alembic.script
:members:
:undoc-members:
.. automodule:: alembic.ddl.mysql
:members:
:undoc-members:
+ :show-inheritance:
MS-SQL
^^^^^^
.. automodule:: alembic.ddl.mssql
:members:
:undoc-members:
+ :show-inheritance:
Postgresql
^^^^^^^^^^
.. automodule:: alembic.ddl.postgresql
:members:
:undoc-members:
+ :show-inheritance:
SQLite
^^^^^^
.. automodule:: alembic.ddl.sqlite
:members:
:undoc-members:
+ :show-inheritance:
important that the Alembic directives, all of which are designed specifically to work
in both "live execution" as well as "offline SQL generation" mode, are used.
+Customizing the Environment
+---------------------------
+
+Users of the ``--sql`` option are encouraged to hack their ``env.py`` files to suit their
+needs. An ``env.py`` script can detect if the ``--sql`` option is in effect by reading
+:func:`.context.requires_connection`.
+
+For example, a multiple database configuration may want to run through each
+database and set the output of the migrations to different named files - the :func:`.context.configure`
+function accepts a parameter ``output_buffer`` for this purpose::
+
+ from alembic import context
+ import myapp
+ import sys
+
+ db_1 = myapp.db_1
+ db_2 = myapp.db_2
+
+ if not context.requires_connection():
+ for name, engine, file_ in [
+ ("db1", db_1, "db1.sql"),
+ ("db2", db_2, "db2.sql"),
+ ]:
+ context.configure(
+ url=engine.url,
+ transactional_ddl=False,
+ output_buffer=file(file_, 'w'))
+ context.execute("-- running migrations for '%s'" % name)
+ context.run_migrations(name=name)
+ sys.stderr.write("Wrote file '%s'" % file_)
+ else:
+ for name, engine, file_ in [
+ ("db1", db_1, "db1.sql"),
+ ("db2", db_2, "db2.sql"),
+ ]:
+ connection = engine.connect()
+ context.configure(connection=connection)
+ try:
+ context.run_migrations(name=name)
+ session.commit()
+ except:
+ session.rollback()
+ raise
Working with Branches
=====================
projects / thirdparty / sqlalchemy / alembic.git / commitdiff
