From: Mike Bayer Date: Fri, 11 Nov 2011 19:38:33 +0000 (-0800) Subject: some docs X-Git-Tag: rel_0_1_0~61 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=57df5838feaf11ee4168a6e26ca6f3a128eccde6;p=thirdparty%2Fsqlalchemy%2Falembic.git some docs --- diff --git a/alembic/config.py b/alembic/config.py index 5cfd10a9..dc1b694f 100644 --- a/alembic/config.py +++ b/alembic/config.py @@ -5,6 +5,19 @@ import inspect 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 @@ -32,6 +45,7 @@ class Config(object): return default def main(argv): + """The console runner function for Alembic.""" def add_options(parser, positional, kwargs): if 'template' in kwargs: diff --git a/alembic/context.py b/alembic/context.py index a7b66cf7..7b31cd94 100644 --- a/alembic/context.py +++ b/alembic/context.py @@ -236,17 +236,17 @@ def configure( 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 @@ -289,6 +289,16 @@ def run_migrations(**kw): """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) @@ -302,6 +312,14 @@ def execute(sql): 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 diff --git a/alembic/script.py b/alembic/script.py index 7848ebfc..d7a0856e 100644 --- a/alembic/script.py +++ b/alembic/script.py @@ -9,6 +9,9 @@ _rev_file = re.compile(r'([a-z0-9]+)\.py$') _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') @@ -209,6 +212,7 @@ class ScriptDirectory(object): return script class Script(object): + """Represent a single revision file in a ``versions/`` directory.""" nextrev = frozenset() def __init__(self, module, rev_id): diff --git a/docs/build/api.rst b/docs/build/api.rst index 4747ae60..ef442342 100644 --- a/docs/build/api.rst +++ b/docs/build/api.rst @@ -18,14 +18,27 @@ env.py Directives 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: @@ -47,6 +60,7 @@ MySQL .. automodule:: alembic.ddl.mysql :members: :undoc-members: + :show-inheritance: MS-SQL ^^^^^^ @@ -54,6 +68,7 @@ MS-SQL .. automodule:: alembic.ddl.mssql :members: :undoc-members: + :show-inheritance: Postgresql ^^^^^^^^^^ @@ -61,6 +76,7 @@ Postgresql .. automodule:: alembic.ddl.postgresql :members: :undoc-members: + :show-inheritance: SQLite ^^^^^^ @@ -68,3 +84,4 @@ SQLite .. automodule:: alembic.ddl.sqlite :members: :undoc-members: + :show-inheritance: diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst index 4dba065f..f801c644 100644 --- a/docs/build/tutorial.rst +++ b/docs/build/tutorial.rst @@ -511,6 +511,49 @@ into memory via a ``SELECT`` statement will not work in ``--sql`` mode. It's a 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 =====================