- add a new section "Run Multiple Alembic Environments from one .ini file",

clarify what the --name flag does and how this differs from
"multiple bases".

Change-Id: If65a8a11802db18bc2f42ffea360c70cbc9113bb

docs/build/branches.rst

@@ -509,6 +509,13 @@ before the head::
 Working with Multiple Bases
 ---------------------------
 
+.. note::  The multiple base feature is intended to allow for multiple Alembic
+   versioning lineages which **share the same alembic_version table**.  This is
+   so that individual revisions within the lineages can have cross-dependencies
+   on each other.   For the simpler case where one project has multiple,
+   **completely independent** revision lineages that refer to **separate**
+   alembic_version tables, see the example in :ref:`multiple_environments`.
+
 We've seen in the previous section that ``alembic upgrade`` is fine
 if we have multiple heads, ``alembic revision`` allows us to tell it which
 "head" we'd like to associate our new revision file with, and branch labels

docs/build/cookbook.rst

@@ -830,3 +830,54 @@ Then define ``include_object`` as::
         return not object.info.get('is_view', False)
 
 Finally, in ``env.py`` pass your ``include_object`` as a keyword argument to :meth:`.EnvironmentContext.configure`.
+
+.. _multiple_environments:
+
+Run Multiple Alembic Environments from one .ini file
+====================================================
+
+Long before Alembic had the "multiple bases" feature described in :ref:`multiple_bases`,
+projects had a need to maintain more than one Alembic version history in a single
+project, where these version histories are completely independent of each other
+and each refer to their own alembic_version table, either across multiple databases,
+schemas, or namespaces.  A simple approach was added to support this, the
+``--name`` flag on the commandline.
+
+First, one would create an alembic.ini file of this form::
+
+    [DEFAULT]
+    # all defaults shared between environments go here
+
+    sqlalchemy.url = postgresql://scott:tiger@hostname/mydatabase
+
+
+    [schema1]
+    # path to env.py and migration scripts for schema1
+    script_location = myproject/revisions/schema1
+
+    [schema2]
+    # path to env.py and migration scripts for schema2
+    script_location = myproject/revisions/schema2
+
+    [schema3]
+    # path to env.py and migration scripts for schema3
+    script_location = myproject/revisions/db2
+
+    # this schema uses a different database URL as well
+    sqlalchemy.url = postgresql://scott:tiger@hostname/myotherdatabase
+
+
+Above, in the ``[DEFAULT]`` section we set up a default database URL.
+Then we create three sections corresponding to different revision lineages
+in our project.   Each of these directories would have its own ``env.py``
+and set of versioning files.   Then when we run the ``alembic`` command,
+we simply give it the name of the configuration we want to use::
+
+    alembic --name schema2 revision -m "new rev for schema 2" --autogenerate
+
+Above, the ``alembic`` command makes use of the configuration in ``[schema2]``,
+populated with defaults from the ``[DEFAULT]`` section.
+
+The above approach can be automated by creating a custom front-end to the
+Alembic commandline as well.
+

docs/build/tutorial.rst

@@ -186,7 +186,10 @@ with the path to the Alembic script location.
 This file contains the following features:
 
 * ``[alembic]`` - this is the section read by Alembic to determine configuration.  Alembic
-  itself does not directly read any other areas of the file.
+  itself does not directly read any other areas of the file.    The name "alembic" can
+  be customized using the ``--name`` commandline flag; see :ref:`multiple_environments`
+  for a basic example of this.
+
 * ``script_location`` - this is the location of the Alembic environment.   It is normally
   specified as a filesystem location, either relative or absolute.  If the location is
   a relative path, it's interpreted as relative to the current directory.

tests/test_postgresql.py

@@ -66,6 +66,12 @@ class PostgresqlOpTest(TestBase):
             'ALTER TABLE t ALTER COLUMN c TYPE INTEGER USING c::integer'
         )
 
+    def test_col_w_pk_is_serial(self):
+        context = op_fixture("postgresql")
+        op.add_column("some_table", Column('q', Integer, primary_key=True))
+        context.assert_(
+            'ALTER TABLE some_table ADD COLUMN q SERIAL NOT NULL'
+        )
 
 class PGOfflineEnumTest(TestBase):