Document quoted_name use for PostgreSQL INHERITS (#13342)

diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py
index 936e7e63f0677b51f74ce4431623e0c6c0008061..e45b3c52e58c7170ddb25eddef4067e176d7f766 100644 (file)
--- a/lib/sqlalchemy/dialects/postgresql/base.py
+++ b/lib/sqlalchemy/dialects/postgresql/base.py
@@ -1236,6 +1236,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 1e04d8b254d99337e682613da3da4e74cfd043de..c5c30c4f8fde7ff8e3110807d1258782a109e2b3 100644 (file)
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -5706,9 +5706,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
@@ -5721,6 +5720,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``.
+
     """
 
     __slots__ = "quote", "lower", "upper"

diff --git a/test/dialect/postgresql/test_compiler.py b/test/dialect/postgresql/test_compiler.py
index d6ab7c136c1bdba869f1e834c7c39d4ea2970704..867e1f3686c179201c983ee638ded7ad5ff351e9 100644 (file)
--- a/test/dialect/postgresql/test_compiler.py
+++ b/test/dialect/postgresql/test_compiler.py
@@ -69,6 +69,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
@@ -531,6 +532,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(