Recipe for ignoring connection tables that aren't in the metadata

Change-Id: Ic4e4feb8fa1407eaa69166d06043afaba0824a50

diff --git a/docs/build/cookbook.rst b/docs/build/cookbook.rst
index f7a2069659b4d91679588a3369653545c85260d6..0d034af454aaed5128e322b6f7a32090b2abb557 100644 (file)
--- a/docs/build/cookbook.rst
+++ b/docs/build/cookbook.rst
@@ -900,6 +900,39 @@ With the above rewriter, it generates as::
         # ### end Alembic commands ###
 
 
+Don't generate any DROP TABLE directives with autogenerate
+==========================================================
+
+When running autogenerate against a database that has existing tables outside
+of the application's autogenerated metadata, it may be desirable to prevent
+autogenerate from considering any of those existing tables to be dropped.
+This will prevent autogenerate from detecting tables removed from the
+local metadata as well however this is only a small caveat.
+
+The most direct way to achieve this using the
+:paramref:`.EnvironmentContext.configure.include_object` hook.   There is no
+need to hardcode a fixed "whitelist" of table names; the hook gives enough
+information in the given arguments to determine if a particular table name is
+not part of the local :class:`.MetaData` being autogenerated, by checking first
+that the type of object is ``"table"``, then that ``reflected`` is ``True``,
+indicating this table name is from the local database connection, not the
+:class:`.MetaData`, and finally that ``compare_to`` is ``None``, indicating
+autogenerate is not comparing this :class:`.Table` to any :class:`.Table` in
+the local :class:`.MetaData` collection::
+
+    # in env.py
+
+    def include_object(object, name, type_, reflected, compare_to):
+        if type_ == "table" and reflected and compare_to is None:
+            return False
+        else:
+            return True
+
+
+    context.configure(
+        # ...
+        include_object = include_object
+    )
 
 Don't emit CREATE TABLE statements for Views
 ============================================