improve cross-linking between Core /ORM for schema arg

this should be backported to 1.3 as well to as much a degree
as possible.

Includes a new recipe to set the default schema name
on connect.   this will only work on 1.4, but also requires
that we fix #5708 for it to work fully.

Change-Id: I882edd5bbe06ee5b4d0a9c148854a57b2bcd4741

2 files changed, 43 insertions, 41 deletions

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index 3c33d9ee8..79839ae39 100644
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -225,6 +225,46 @@ SERIALIZABLE isolation.
 .. versionadded:: 1.4 added support for the ``postgresql_readonly``
    and ``postgresql_deferrable`` execution options.
 
+.. _postgresql_alternate_search_path:
+
+Setting Alternate Search Paths on Connect
+------------------------------------------
+
+The PostgreSQL ``search_path`` variable refers to the list of schema names
+that will be implicitly referred towards when a particular table or other
+object is referenced in a SQL statement.  As detailed in the next section
+:ref:`postgresql_schema_reflection`, SQLAlchemy is generally organized around
+the concept of keeping this variable at its default value of ``public``,
+however, in order to have it set to any arbirary name or names when connections
+are used automatically, the "SET SESSION search_path" command may be invoked
+for all connections in a pool using the following event handler, as discussed
+at :ref:`schema_set_default_connections`::
+
+    from sqlalchemy import event
+    from sqlalchemy import create_engine
+
+    engine = create_engine("postgresql+psycopg2://scott:tiger@host/dbname")
+
+    @event.listens_for(engine, "connect", insert=True)
+    def set_search_path(dbapi_connection, connection_record):
+        existing_autocommit = dbapi_connection.autocommit
+        dbapi_connection.autocommit = True
+        cursor = dbapi_connection.cursor()
+        cursor.execute("SET SESSION search_path='%s'" % schema_name)
+        cursor.close()
+        dbapi_connection.autocommit = existing_autocommit
+
+The reason the recipe is complicated by use of the ``.autocommit`` DBAPI
+attribute is so that when the ``SET SESSION search_path`` directive is invoked,
+it is invoked outside of the scope of any tranasction and therefore will not
+be reverted when the DBAPI connection has a rollback.
+
+.. seealso::
+
+  :ref:`schema_set_default_connections` - in the :ref:`metadata_toplevel` documentation
+
+
+
 
 .. _postgresql_schema_reflection:
 
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index b7e5dac31..4b19ff02a 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -3982,49 +3982,11 @@ class MetaData(SchemaItem):
            :class:`.Sequence`, and potentially other objects associated with
            this :class:`_schema.MetaData`. Defaults to ``None``.
 
-           When this value is set, any :class:`_schema.Table` or
-           :class:`.Sequence`
-           which specifies ``None`` for the schema parameter will instead
-           have this schema name defined.  To build a :class:`_schema.Table`
-           or :class:`.Sequence` that still has ``None`` for the schema
-           even when this parameter is present, use the :attr:`.BLANK_SCHEMA`
-           symbol.
-
-           .. note::
-
-                As referred above, the :paramref:`_schema.MetaData.schema`
-                parameter
-                only refers to the **default value** that will be applied to
-                the :paramref:`_schema.Table.schema` parameter of an incoming
-                :class:`_schema.Table` object.   It does not refer to how the
-                :class:`_schema.Table` is catalogued within the
-                :class:`_schema.MetaData`,
-                which remains consistent vs. a :class:`_schema.MetaData`
-                collection
-                that does not define this parameter.  The
-                :class:`_schema.Table`
-                within the :class:`_schema.MetaData`
-                will still be keyed based on its
-                schema-qualified name, e.g.
-                ``my_metadata.tables["some_schema.my_table"]``.
-
-                The current behavior of the :class:`_schema.ForeignKey`
-                object is to
-                circumvent this restriction, where it can locate a table given
-                the table name alone, where the schema will be assumed to be
-                present from this value as specified on the owning
-                :class:`_schema.MetaData` collection.  However,
-                this implies  that a
-                table qualified with BLANK_SCHEMA cannot currently be referred
-                to by string name from :class:`_schema.ForeignKey`.
-                Other parts of
-                SQLAlchemy such as Declarative may not have similar behaviors
-                built in, however may do so in a future release, along with a
-                consistent method of referring to a table in BLANK_SCHEMA.
-
-
            .. seealso::
 
+                :ref:`schema_metadata_schema_name` - details on how the
+                :paramref:`_schema.MetaData.schema` parameter is used.
+
                 :paramref:`_schema.Table.schema`
 
                 :paramref:`.Sequence.schema`