From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 1 Mar 2021 12:33:13 +0000 (-0500)
Subject: doc clarification re: schema translate
X-Git-Tag: rel_1_3_24~15
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=667c963e48a92e95847a25337b9f11560f3b7b43;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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 28d69a176b..96f645e54f 100644
--- 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: