Allow target_metadata to be a sequence

The :paramref:`.EnvironmentContext.configure.target_metadata` parameter
may now be optionally specified as a sequence of :class:`.MetaData`
objects instead of a single :class:`.MetaData` object.  The
autogenerate process will process the sequence of :class:`.MetaData`
objects in order.

Change-Id: I6485c05d68219ff7af1611b34550487d316e0242
Fixes: #38

1 files changed, 24 insertions, 0 deletions

diff --git a/docs/build/autogenerate.rst b/docs/build/autogenerate.rst
index d1ae069..a5bd5d1 100644
--- a/docs/build/autogenerate.rst
+++ b/docs/build/autogenerate.rst
@@ -180,6 +180,30 @@ Autogenerate can't currently, but **will eventually detect**:
   the supporting SQLAlchemy dialect.
 * Sequence additions, removals - not yet implemented.
 
+Autogenerating Multiple MetaData collections
+--------------------------------------------
+
+The ``target_metadata`` collection may also be defined as a sequence
+if an application has multiple :class:`~sqlalchemy.schema.MetaData`
+collections involved::
+
+    from myapp.mymodel1 import Model1Base
+    from myapp.mymodel2 import Model2Base
+    target_metadata = [Model1Base.metadata, Model2Base.metadata]
+
+The sequence of :class:`~sqlalchemy.schema.MetaData` collections will be
+consulted in order during the autogenerate process.  Note that each
+:class:`~sqlalchemy.schema.MetaData` must contain **unique** table keys
+(e.g. the "key" is the combination of the table's name and schema);
+if two :class:`~sqlalchemy.schema.MetaData` objects contain a table
+with the same schema/name combination, an error is raised.
+
+.. versionchanged:: 0.9.0 the
+  :paramref:`.EnvironmentContext.configure.target_metadata`
+  parameter may now be passed a sequence of
+  :class:`~sqlalchemy.schema.MetaData` objects to support
+  autogeneration of multiple :class:`~sqlalchemy.schema.MetaData`
+  collections.
 
 Comparing and Rendering Types
 ------------------------------