Commits

Mike Bayer committed 0c72381

more cleanup

  • Participants
  • Parent commits 7cb12c9
  • Branches rel_0_7

Comments (0)

Files changed (2)

File doc/build/core/connections.rst

 from the :class:`.Table` object has a method :meth:`~.Executable.execute`, which will
 search for an :class:`.Engine` that's "bound" to the :class:`.Table`.
 
+Overall, the usage of "bound metadata" has three general effects:
+
+* SQL statement objects gain an :meth:`.Executable.execute` method which automatically
+  locates a "bind" with which to execute themselves.
+* The ORM :class:`.Session` object supports using "bound metadata" in order
+  to establish which :class:`.Engine` should be used to invoke SQL statements
+  on behalf of a particular mapped class, though the :class:`.Session`
+  also features its own explicit system of establishing complex :class:`.Engine`/
+  mapped class configurations.
+* The :meth:`.MetaData.create_all`, :meth:`.Metadata.drop_all`, :meth:`.Table.create`,
+  :meth:`.Table.drop`, and "autoload" features all make usage of the bound
+  :class:`.Engine` automatically without the need to pass it explicitly.
+
 .. note::
 
     The concepts of "bound metadata" and "implicit execution" are not emphasized in modern SQLAlchemy.
-    In applications
-    where multiple :class:`.Engine` objects are present, each one logically associated
+    While they offer some convenience, they are no longer required by any API and
+    are never necessary.
+
+    In applications where multiple :class:`.Engine` objects are present, each one logically associated
     with a certain set of tables (i.e. *vertical sharding*), the "bound metadata" technique can be used
     so that individual :class:`.Table` can refer to the appropriate :class:`.Engine` automatically;
     in particular this is supported within the ORM via the :class:`.Session` object
     as a means to associate :class:`.Table` objects with an appropriate :class:`.Engine`,
     as an alternative to using the bind arguments accepted directly by the :class:`.Session`.
+
     However, the "implicit execution" technique is not at all appropriate for use with the
     ORM, as it bypasses the transactional context maintained by the :class:`.Session`.
 
     are **not useful**.   While "bound metadata" has a marginal level of usefulness with regards to
     ORM configuration, "implicit execution" is a very old usage pattern that in most
     cases is more confusing than it is helpful, and its usage is discouraged.
+    Both patterns seem to encourage the overuse of expedient "short cuts" in application design
+    which lead to problems later on.
 
     Modern SQLAlchemy usage, especially the ORM, places a heavy stress on working within the context
     of a transaction at all times; the "implicit execution" concept makes the job of

File doc/build/core/schema.rst

   SQL script generation, ORM class generation, ORM model comparison, and extensive
   support for SQLite migrations.
 
-.. _metadata_binding:
-
-Binding MetaData to an Engine or Connection
---------------------------------------------
-
-The :class:`.MetaData` object can be associated directly with an :class:`.Engine`
-or :class:`.Connection` so that SQL statement objects gain an :meth:`.Executable.execute`
-method, and also provide an alternate means to the ORM :class:`.Session` object
-in order to locate an :class:`.Engine`, given a particular mapping to execute a
-query against.   However, this pattern is **not recommended for general use**.
-For background, see, :ref:`dbengine_implicit`.
 
 Specifying the Schema Name
 ---------------------------