Document quoted_name use for PostgreSQL INHERITS (#13342)

(cherry picked from commit ea1a30f4606eeaee7d696e0d1291a3501ff1fc8a)

Change-Id: I7046bd046a8b8818760b6d253ca528f62ed8a95d

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index a5e5d224a35e9735cf6178c56c2885ad764f6db8..872cc2b9c71242ec6927695996adad152c1b0b62 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -1198,6 +1198,21 @@ constraints, enabling table inheritance hierarchies in PostgreSQL.
 
     Table("some_table", metadata, ..., postgresql_inherits=("t1", "t2", ...))
 
+For schema-qualified parent table names, use :class:`.quoted_name` with
+``quote=False`` to prevent the dotted name from being quoted as a single
+identifier::
+
+    from sqlalchemy.sql import quoted_name
+
+    Table(
+        "some_table",
+        metadata,
+        ...,
+        postgresql_inherits=quoted_name(
+            "my_schema.some_supertable", quote=False
+        ),
+    )
+
 ``ON COMMIT``
 ^^^^^^^^^^^^^
 

diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 6a9df124127a367cfe7976c8cb6d1a07abd5beaa..b13839e0be180914dba4e0d96b905c955e19e22e 100644 (file)
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -5267,9 +5267,8 @@ class quoted_name(util.MemoizedSlots, str):
     :class:`_schema.Table`, :class:`_schema.Column`, and others.
     The class can also be
     passed explicitly as the name to any function that receives a name which
-    can be quoted.  Such as to use the :meth:`_engine.Engine.has_table`
-    method with
-    an unconditionally quoted name::
+    can be quoted, such as :meth:`.Inspector.has_table` with an
+    unconditionally quoted name::
 
         from sqlalchemy import create_engine
         from sqlalchemy import inspect
@@ -5282,6 +5281,11 @@ class quoted_name(util.MemoizedSlots, str):
     backend, passing the name exactly as ``"some_table"`` without converting to
     upper case.
 
+    A :class:`.quoted_name` object with ``quote=False`` may be passed to APIs
+    that apply automatic quoting in order to keep the given name unquoted,
+    such as when a PostgreSQL ``INHERITS`` option refers to a schema-qualified
+    table name like ``my_schema.some_table``.
+
     .. versionchanged:: 1.2 The :class:`.quoted_name` construct is now
        importable from ``sqlalchemy.sql``, in addition to the previous
        location of ``sqlalchemy.sql.elements``.

diff --git a/test/dialect/postgresql/test_compiler.py b/test/dialect/postgresql/test_compiler.py
index d53db137217e70ba2e73f040781d674dbdbc7ec4..12495ebeada2caa681d7e212c8dd24811e63f66d 100644 (file)
--- a/test/dialect/postgresql/test_compiler.py
+++ b/test/dialect/postgresql/test_compiler.py
@@ -64,6 +64,7 @@ from sqlalchemy.orm import Session
 from sqlalchemy.sql import column
 from sqlalchemy.sql import literal_column
 from sqlalchemy.sql import operators
+from sqlalchemy.sql import quoted_name
 from sqlalchemy.sql import table
 from sqlalchemy.sql import util as sql_util
 from sqlalchemy.sql.functions import GenericFunction
@@ -528,6 +529,22 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL):
             '( "Quote Me", "quote Me Too" )',
         )
 
+    def test_create_table_inherits_schema_qualified_quoted_name(self):
+        m = MetaData()
+        tbl = Table(
+            "atable",
+            m,
+            Column("id", Integer),
+            postgresql_inherits=quoted_name(
+                "my_schema.parent_table", quote=False
+            ),
+        )
+        self.assert_compile(
+            schema.CreateTable(tbl),
+            "CREATE TABLE atable (id INTEGER) "
+            "INHERITS ( my_schema.parent_table )",
+        )
+
     def test_create_table_partition_by_list(self):
         m = MetaData()
         tbl = Table(