doc clarification re: schema translate

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

Change-Id: I5807b486275cac72087be5217fff7c878783435f
References: #5978

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index 1bb784068de67d42bee0959d43c3149fd5a32491..38ea21ae82ffa9fef28d99d66f6815ef3d279ace 100644 (file)
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -763,6 +763,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
 
 .. _sql_caching: