doc clarification re: schema translate

add tip that ORM session should use an option engine for schema
translate

Change-Id: I5807b486275cac72087be5217fff7c878783435f
References: #5978
(cherry picked from commit da1bc669d59f06982356c69039512ef4f5c6950b)

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index 28d69a176b0c1ef33c4513d8d404857ee57f8961..96f645e54f4fec94440de6b70d7ff798bb17c39b 100644 (file)
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -664,6 +664,21 @@ using table reflection given a :class:`_schema.Table` object.  However it does
 **not** affect the operations present on the :class:`_reflection.Inspector` object,
 as the schema name is passed to these methods explicitly.
 
+.. tip::
+
+  To use the schema translation feature with the ORM :class:`_orm.Session`,
+  set this option at the level of the :class:`_engine.Engine`, then pass that engine
+  to the :class:`_orm.Session`.  The :class:`_orm.Session` uses a new
+  :class:`_engine.Connection` for each transaction::
+
+      schema_engine = engine.execution_options(schema_translate_map = { ... } )
+
+      session = Session(schema_engine)
+
+      ...
+
+
+
 .. versionadded:: 1.1
 
 .. _engine_disposal: