Improve documentation about the relationship of extensions and schemas.

There's been some confusion expressed about this point, so clarify.
Extended version of a patch by David Wheeler.

diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 0ea021ec358e108afcb1b37d1f355496ea255e85..b571b5f66bf5fb642182317fdbfccf314fc159d4 100644 (file)
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -352,6 +352,12 @@
     extension.)  Also notice that while a table can be a member of an
     extension, its subsidiary objects such as indexes are not directly
     considered members of the extension.
+    Another important point is that schemas can belong to extensions, but not
+    vice versa: an extension as such has an unqualified name and does not
+    exist <quote>within</> any schema.  The extension's member objects,
+    however, will belong to schemas whenever appropriate for their object
+    types.  It may or may not be appropriate for an extension to own the
+    schema(s) its member objects are within.
    </para>
 
    <sect2>

diff --git a/doc/src/sgml/ref/create_extension.sgml b/doc/src/sgml/ref/create_extension.sgml
index 9ec0fa2fe16be88022795f2fc6cc888cb092862a..9c9bf6ff7d757ac1948d64038376f60edc012f46 100644 (file)
--- a/doc/src/sgml/ref/create_extension.sgml
+++ b/doc/src/sgml/ref/create_extension.sgml
@@ -22,7 +22,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name</replaceable>
-    [ WITH ] [ SCHEMA <replaceable class="parameter">schema</replaceable> ]
+    [ WITH ] [ SCHEMA <replaceable class="parameter">schema_name</replaceable> ]
              [ VERSION <replaceable class="parameter">version</replaceable> ]
              [ FROM <replaceable class="parameter">old_version</replaceable> ]
 </synopsis>
@@ -85,7 +85,7 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
      </varlistentry>
 
      <varlistentry>
-      <term><replaceable class="parameter">schema</replaceable></term>
+      <term><replaceable class="parameter">schema_name</replaceable></term>
       <listitem>
        <para>
         The name of the schema in which to install the extension's
@@ -94,6 +94,12 @@ CREATE EXTENSION [ IF NOT EXISTS ] <replaceable class="parameter">extension_name
         If not specified, and the extension's control file does not specify a
         schema either, the current default object creation schema is used.
        </para>
+       <para>
+        Remember that the extension itself is not considered to be within any
+        schema: extensions have unqualified names that must be unique
+        database-wide.  But objects belonging to the extension can be within
+        schemas.
+       </para>
       </listitem>
      </varlistentry>