From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 18 Oct 2013 23:23:40 +0000 (-0400)
Subject: - add a "limitations of reflection" section, [ticket:2233]
X-Git-Tag: rel_0_8_3~7
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4187fb2811639c6391f8c552a73f433d881bf875;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add a "limitations of reflection" section, [ticket:2233]

Conflicts:
	doc/build/core/reflection.rst
---

diff --git a/doc/build/core/defaults.rst b/doc/build/core/defaults.rst
index 54a757e569..166273c186 100644
--- a/doc/build/core/defaults.rst
+++ b/doc/build/core/defaults.rst
@@ -219,6 +219,7 @@ have a way to "postfetch" the ID, and the statement is not "inlined", the SQL
 expression is pre-executed; otherwise, SQLAlchemy lets the default fire off on
 the database side normally.
 
+
 .. _triggered_columns:
 
 Triggered Columns
diff --git a/doc/build/core/reflection.rst b/doc/build/core/reflection.rst
index 17ff0b99ef..d0636e7da4 100644
--- a/doc/build/core/reflection.rst
+++ b/doc/build/core/reflection.rst
@@ -128,5 +128,39 @@ database is also available. This is known as the "Inspector"::
 .. autoclass:: sqlalchemy.engine.reflection.Inspector
     :members:
     :undoc-members:
-     
+
+Limitations of Reflection
+-------------------------
+
+It's important to note that the reflection process recreates :class:`.Table`
+metadata using only information which is represented in the relational database.
+This process by definition cannot restore aspects of a schema that aren't
+actually stored in the database.   State which is not available from reflection
+includes but is not limited to:
+
+* Client side defaults, either Python functions or SQL expressions defined using
+  the ``default`` keyword of :class:`.Column` (note this is separate from ``server_default``,
+  which specifically is what's available via reflection).
+
+* Column information, e.g. data that might have been placed into the
+  :attr:`.Column.info` dictionary
+
+* The value of the ``.quote`` setting for :class:`.Column` or :class:`.Table`
+
+* The assocation of a particular :class:`.Sequence` with a given :class:`.Column`
+
+The relational database also in many cases reports on table metadata in a
+different format than what was specified in SQLAlchemy.   The :class:`.Table`
+objects returned from reflection cannot be always relied upon to produce the identical
+DDL as the original Python-defined :class:`.Table` objects.   Areas where
+this occurs includes server defaults, column-associated sequences and various
+idosyncrasies regarding constraints and datatypes.   Server side defaults may
+be returned with cast directives (typically Postgresql will include a ``::<type>``
+cast) or different quoting patterns than originally specified.
+
+Another category of limitation includes schema structures for which reflection
+is only partially or not yet defined.  Recent improvements to reflection allow
+things like views, indexes and foreign key options to be reflected.  As of this
+writing, structures like CHECK constraints, table comments, and triggers are
+not reflected.