Documentation for ALTER object SET SCHEMA commands. Also some minor

editorialization.

Documentation for ALTER object SET SCHEMA commands. Also some minor
editorialization.
f58434f1 · Tom Lane · 614b6e25 · f58434f1 · f58434f1 · f58434f1
6 changed file
--- a/doc/src/sgml/ref/alter_aggregate.sgml
+++ b/doc/src/sgml/ref/alter_aggregate.sgml
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_aggregate.sgml,v 1.5 2004/06/25 21:55:50 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_aggregate.sgml,v 1.6 2005/08/01 16:11:14 tgl Exp $
 PostgreSQL documentation
 -->

@@ -20,8 +20,9 @@ PostgreSQL documentation

 <refsynopsisdiv>
 <synopsis>
-ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>type</replaceable> ) RENAME TO <replaceable>newname</replaceable>
-ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>type</replaceable> ) OWNER TO <replaceable>newowner</replaceable>
+ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>type</replaceable> ) RENAME TO <replaceable>new_name</replaceable>
+ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>type</replaceable> ) OWNER TO <replaceable>new_owner</replaceable>
+ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>type</replaceable> ) SET SCHEMA <replaceable>new_schema</replaceable>
 </synopsis>
 </refsynopsisdiv>
  
@@ -32,6 +33,14 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>type</replaceable
   <command>ALTER AGGREGATE</command> changes the definition of an
   aggregate function.
  </para>
+
+  <para>
+   You must own the aggregate function to use <command>ALTER AGGREGATE</>;
+   except for <command>ALTER AGGREGATE OWNER</>, which may only be executed by
+   a superuser.
+   To change the schema of an aggregate function, you must also have
+   <literal>CREATE</literal> privilege on the new schema.
+  </para>
 </refsect1>
  
 <refsect1>
@@ -58,7 +67,7 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>type</replaceable
   </varlistentry>

   <varlistentry>
-    <term><replaceable class="parameter">newname</replaceable></term>
+    <term><replaceable class="parameter">new_name</replaceable></term>
    <listitem>
     <para>
      The new name of the aggregate function.
@@ -67,11 +76,19 @@ ALTER AGGREGATE <replaceable>name</replaceable> ( <replaceable>type</replaceable
   </varlistentry>

   <varlistentry>
-    <term><replaceable class="parameter">newowner</replaceable></term>
+    <term><replaceable class="parameter">new_owner</replaceable></term>
    <listitem>
     <para>
      The new owner of the aggregate function.
-      You must be a superuser to change an aggregate's owner.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">new_schema</replaceable></term>
+    <listitem>
+     <para>
+      The new schema for the aggregate function.
     </para>
    </listitem>
   </varlistentry>
@@ -94,6 +111,14 @@ ALTER AGGREGATE myavg(integer) RENAME TO my_average;
   <type>integer</type> to <literal>joe</literal>:
 <programlisting>
 ALTER AGGREGATE myavg(integer) OWNER TO joe;
+</programlisting>
+  </para>
+
+  <para>
+   To move the aggregate function <literal>myavg</literal> for type
+   <type>integer</type> into schema <literal>myschema</literal>:
+<programlisting>
+ALTER AGGREGATE myavg(integer) SET SCHEMA myschema;
 </programlisting>
  </para>
 </refsect1>

--- a/doc/src/sgml/ref/alter_domain.sgml
+++ b/doc/src/sgml/ref/alter_domain.sgml
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_domain.sgml,v 1.16 2005/07/14 06:17:36 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_domain.sgml,v 1.17 2005/08/01 16:11:14 tgl Exp $
 PostgreSQL documentation
 -->

@@ -34,6 +34,8 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
    DROP CONSTRAINT <replaceable class="PARAMETER">constraint_name</replaceable> [ RESTRICT | CASCADE ]
 ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
    OWNER TO <replaceable class="PARAMETER">new_owner</replaceable> 
+ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
+    SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable> 
  </synopsis>
 </refsynopsisdiv>

@@ -97,11 +99,23 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
     </para>
    </listitem>
   </varlistentry>
+
+   <varlistentry>
+    <term>SET SCHEMA</term>
+    <listitem>
+     <para>
+      This form changes the schema of the domain.  Any constraints
+      associated with the domain are moved into the new schema as well.
+     </para>
+    </listitem>
+   </varlistentry>
  </variablelist>

  <para>
   You must own the domain to use <command>ALTER DOMAIN</>; except for
   <command>ALTER DOMAIN OWNER</>, which may only be executed by a superuser.
+   To change a domain's schema, you must also have <literal>CREATE</>
+   privilege on the new schema.
  </para>
 </refsect1>

@@ -114,8 +128,8 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
      <term><replaceable class="PARAMETER">name</replaceable></term>
      <listitem>
       <para>
-	The name (possibly schema-qualified) of an existing domain to
-	alter.
+        The name (possibly schema-qualified) of an existing domain to
+        alter.
       </para>
      </listitem>
     </varlistentry>
@@ -124,7 +138,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
      <term><replaceable class="PARAMETER">domain_constraint</replaceable></term>
      <listitem>
       <para>
-	New domain constraint for the domain.
+        New domain constraint for the domain.
       </para>
      </listitem>
     </varlistentry>
@@ -133,7 +147,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
      <term><replaceable class="PARAMETER">constraint_name</replaceable></term>
      <listitem>
       <para>
-	Name of an existing constraint to drop.
+        Name of an existing constraint to drop.
       </para>
      </listitem>
     </varlistentry>
@@ -152,7 +166,7 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
      <listitem>
       <para>
        Refuse to drop the constraint if there are any dependent
-	objects. This is the default behavior.
+        objects. This is the default behavior.
       </para>
      </listitem>
     </varlistentry>
@@ -161,7 +175,16 @@ ALTER DOMAIN <replaceable class="PARAMETER">name</replaceable>
      <term><replaceable class="PARAMETER">new_owner</replaceable></term>
      <listitem>
       <para>
-	The user name of the new owner of the domain.
+        The user name of the new owner of the domain.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><replaceable class="PARAMETER">new_schema</replaceable></term>
+      <listitem>
+       <para>
+        The new schema for the domain.
       </para>
      </listitem>
     </varlistentry>
@@ -197,15 +220,22 @@ ALTER DOMAIN zipcode ADD CONSTRAINT zipchk CHECK (char_length(VALUE) = 5);
 ALTER DOMAIN zipcode DROP CONSTRAINT zipchk;
   </programlisting>
  </para>
+
+  <para>
+   To move the domain into a different schema:
+   <programlisting>
+ALTER DOMAIN zipcode SET SCHEMA customers;
+   </programlisting>
+  </para>
 </refsect1>

 <refsect1 id="SQL-ALTERDOMAIN-compatibility">
  <title>Compatibility</title>
    
  <para>
-   The <command>ALTER DOMAIN</command> statement is compatible with SQL:2003,
-   except for the <literal>OWNER</> variant, which is a
-   <productname>PostgreSQL</productname> extension.
+   <command>ALTER DOMAIN</command> conforms with <acronym>SQL:2003</acronym>,
+   except for the <literal>OWNER</> and <literal>SET SCHEMA</> variants,
+   which are <productname>PostgreSQL</productname> extensions.
  </para>
 </refsect1>


--- a/doc/src/sgml/ref/alter_function.sgml
+++ b/doc/src/sgml/ref/alter_function.sgml
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_function.sgml,v 1.7 2005/05/26 20:05:03 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_function.sgml,v 1.8 2005/08/01 16:11:14 tgl Exp $
 PostgreSQL documentation
 -->

@@ -23,9 +23,11 @@ PostgreSQL documentation
 ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
    <replaceable class="PARAMETER">action</replaceable> [, ... ] [ RESTRICT ]
 ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
-    RENAME TO <replaceable>newname</replaceable>
+    RENAME TO <replaceable>new_name</replaceable>
 ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
-    OWNER TO <replaceable>newowner</replaceable>
+    OWNER TO <replaceable>new_owner</replaceable>
+ALTER FUNCTION <replaceable>name</replaceable> ( [ [ <replaceable class="parameter">argmode</replaceable> ] [ <replaceable class="parameter">argname</replaceable> ] <replaceable class="parameter">argtype</replaceable> [, ...] ] )
+    SET SCHEMA <replaceable>new_schema</replaceable>

 where <replaceable class="PARAMETER">action</replaceable> is one of:

@@ -42,6 +44,13 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
   <command>ALTER FUNCTION</command> changes the definition of a
   function.
  </para>
+
+  <para>
+   You must own the function to use <command>ALTER FUNCTION</>; except for
+   <command>ALTER FUNCTION OWNER</>, which may only be executed by a superuser.
+   To change a function's schema, you must also have <literal>CREATE</>
+   privilege on the new schema.
+  </para>
 </refsect1>
  
 <refsect1>
@@ -98,7 +107,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
   </varlistentry>

   <varlistentry>
-    <term><replaceable class="parameter">newname</replaceable></term>
+    <term><replaceable class="parameter">new_name</replaceable></term>
    <listitem>
     <para>
      The new name of the function.
@@ -107,17 +116,25 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
   </varlistentry>

   <varlistentry>
-    <term><replaceable class="parameter">newowner</replaceable></term>
+    <term><replaceable class="parameter">new_owner</replaceable></term>
    <listitem>
     <para>
-      The new owner of the function.  To change the owner of a
-      function, you must be a superuser.  Note that if the function is
+      The new owner of the function.  Note that if the function is
      marked <literal>SECURITY DEFINER</literal>, it will subsequently
      execute as the new owner.
     </para>
    </listitem>
   </varlistentry>

+   <varlistentry>
+    <term><replaceable class="parameter">new_schema</replaceable></term>
+    <listitem>
+     <para>
+      The new schema for the function.
+     </para>
+    </listitem>
+   </varlistentry>
+
    <varlistentry>
     <term><literal>CALLED ON NULL INPUT</literal></term>
     <term><literal>RETURNS NULL ON NULL INPUT</literal></term>
@@ -191,6 +208,14 @@ ALTER FUNCTION sqrt(integer) RENAME TO square_root;
   <type>integer</type> to <literal>joe</literal>:
 <programlisting>
 ALTER FUNCTION sqrt(integer) OWNER TO joe;
+</programlisting>
+  </para>
+
+  <para>
+   To change the schema of the function <literal>sqrt</literal> for type
+   <type>integer</type> to <literal>maths</literal>:
+<programlisting>
+ALTER FUNCTION sqrt(integer) SET SCHEMA maths;
 </programlisting>
  </para>
 </refsect1>
@@ -203,7 +228,7 @@ ALTER FUNCTION sqrt(integer) OWNER TO joe;
   FUNCTION</> statement in the SQL standard. The standard allows more
   properties of a function to be modified, but does not provide the
   ability to rename a function, make a function a security definer,
-   or change the owner or volatility of a function. The standard also
+   or change the owner, schema, or volatility of a function. The standard also
   requires the <literal>RESTRICT</> key word; it is optional in
   <productname>PostgreSQL</>.
  </para>

--- a/doc/src/sgml/ref/alter_sequence.sgml
+++ b/doc/src/sgml/ref/alter_sequence.sgml
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_sequence.sgml,v 1.9 2004/11/27 21:27:07 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_sequence.sgml,v 1.10 2005/08/01 16:11:14 tgl Exp $
 PostgreSQL documentation
 -->

@@ -27,6 +27,7 @@ PostgreSQL documentation
 ALTER SEQUENCE <replaceable class="parameter">name</replaceable> [ INCREMENT [ BY ] <replaceable class="parameter">increment</replaceable> ]
    [ MINVALUE <replaceable class="parameter">minvalue</replaceable> | NO MINVALUE ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> | NO MAXVALUE ]
    [ RESTART [ WITH ] <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ [ NO ] CYCLE ]
+ALTER SEQUENCE <replaceable class="parameter">name</replaceable> SET SCHEMA <replaceable class="parameter">new_schema</replaceable>
  </synopsis>
 </refsynopsisdiv>

@@ -35,8 +36,14 @@ ALTER SEQUENCE <replaceable class="parameter">name</replaceable> [ INCREMENT [ B

  <para>
   <command>ALTER SEQUENCE</command> changes the parameters of an existing
-   sequence generator.  Any parameter not specifically set in the
-   <command>ALTER SEQUENCE</command> command retains its prior setting.
+   sequence generator.  Any parameters not specifically set in the
+   <command>ALTER SEQUENCE</command> command retain their prior settings.
+  </para>
+
+  <para>
+   You must own the sequence to use <command>ALTER SEQUENCE</>.
+   To change a sequence's schema, you must also have <literal>CREATE</>
+   privilege on the new schema.
  </para>
 </refsect1>

@@ -155,6 +162,15 @@ ALTER SEQUENCE <replaceable class="parameter">name</replaceable> [ INCREMENT [ B
       </para>
      </listitem>
     </varlistentry>
+
+     <varlistentry>
+      <term><replaceable class="parameter">new_schema</replaceable></term>
+      <listitem>
+       <para>
+        The new schema for the sequence.
+       </para>
+      </listitem>
+     </varlistentry>
    </variablelist>
   </para>
  </refsect1>
@@ -186,6 +202,12 @@ ALTER SEQUENCE serial RESTART WITH 105;
   values. They will use up all cached values prior to noticing the changed
   sequence parameters.  The current backend will be affected immediately.
  </para>
+
+  <para>
+   Some variants of <command>ALTER TABLE</command> can be used with
+   sequences as well; for example, to rename a sequence use <command>ALTER
+   TABLE RENAME</command>.
+  </para>
 </refsect1>


@@ -193,7 +215,9 @@ ALTER SEQUENCE serial RESTART WITH 105;
  <title>Compatibility</title>

  <para>
-   <command>ALTER SEQUENCE</command> conforms with <acronym>SQL:2003</acronym>.
+   <command>ALTER SEQUENCE</command> conforms with <acronym>SQL:2003</acronym>,
+   except for the <literal>SET SCHEMA</literal> variant, which is a
+   <productname>PostgreSQL</productname> extension.
  </para>
 </refsect1>
 </refentry>

--- a/doc/src/sgml/ref/alter_table.sgml
+++ b/doc/src/sgml/ref/alter_table.sgml
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.77 2005/01/14 01:16:52 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_table.sgml,v 1.78 2005/08/01 16:11:14 tgl Exp $
 PostgreSQL documentation
 -->

@@ -26,6 +26,8 @@ ALTER TABLE [ ONLY ] <replaceable class="PARAMETER">name</replaceable> [ * ]
    RENAME [ COLUMN ] <replaceable class="PARAMETER">column</replaceable> TO <replaceable class="PARAMETER">new_column</replaceable>
 ALTER TABLE <replaceable class="PARAMETER">name</replaceable>
    RENAME TO <replaceable class="PARAMETER">new_name</replaceable>
+ALTER TABLE <replaceable class="PARAMETER">name</replaceable>
+    SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable>

 where <replaceable class="PARAMETER">action</replaceable> is one of:

@@ -43,7 +45,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
    SET WITHOUT CLUSTER
    SET WITHOUT OIDS
    OWNER TO <replaceable class="PARAMETER">new_owner</replaceable>
-    SET TABLESPACE <replaceable class="PARAMETER">tablespace_name</replaceable>
+    SET TABLESPACE <replaceable class="PARAMETER">new_tablespace</replaceable>
 </synopsis>
 </refsynopsisdiv>

@@ -59,7 +61,7 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
    <term><literal>ADD COLUMN</literal></term>
    <listitem>
     <para>
-      This form adds a new column to the table using the same syntax as
+      This form adds a new column to the table, using the same syntax as
      <xref linkend="SQL-CREATETABLE" endterm="SQL-CREATETABLE-TITLE">.
     </para>
    </listitem>
@@ -264,11 +266,22 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
    </listitem>
   </varlistentry>

+   <varlistentry>
+    <term><literal>SET SCHEMA</literal></term>
+    <listitem>
+     <para>
+      This form moves the table into another schema.  Associated indexes,
+      constraints, and SERIAL-column sequences are moved as well.
+     </para>
+    </listitem>
+   </varlistentry>
+
  </variablelist>
  </para>

  <para>
-   All the actions except <literal>RENAME</literal> can be combined into
+   All the actions except <literal>RENAME</literal> and <literal>SET SCHEMA</>
+   can be combined into
   a list of multiple alterations to apply in parallel.  For example, it
   is possible to add several columns and/or alter the type of several
   columns in a single command.  This is particularly useful with large
@@ -278,6 +291,8 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
  <para>
   You must own the table to use <command>ALTER TABLE</>; except for
   <command>ALTER TABLE OWNER</>, which may only be executed by a superuser.
+   To change the schema of a table, you must also have
+   <literal>CREATE</literal> privilege on the new schema.
  </para>
 </refsect1>

@@ -397,10 +412,19 @@ where <replaceable class="PARAMETER">action</replaceable> is one of:
     </varlistentry>

     <varlistentry>
-      <term><replaceable class="PARAMETER">tablespace_name</replaceable></term>
+      <term><replaceable class="PARAMETER">new_tablespace</replaceable></term>
+      <listitem>
+       <para>
+        The name of the tablespace to which the table will be moved.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><replaceable class="PARAMETER">new_schema</replaceable></term>
      <listitem>
       <para>
-        The tablespace name to which the table will be moved.
+        The name of the schema to which the table will be moved.
       </para>
      </listitem>
     </varlistentry>
@@ -610,9 +634,16 @@ ALTER TABLE distributors ADD PRIMARY KEY (dist_id);
  </para>

  <para> 
-        To move a table to a different tablespace:
+   To move a table to a different tablespace:
 <programlisting>
 ALTER TABLE distributors SET TABLESPACE fasttablespace;
+</programlisting>
+  </para>
+
+  <para> 
+   To move a table to a different schema:
+<programlisting>
+ALTER TABLE myschema.distributors SET SCHEMA yourschema;
 </programlisting>
  </para>


--- a/doc/src/sgml/ref/alter_type.sgml
+++ b/doc/src/sgml/ref/alter_type.sgml
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/alter_type.sgml,v 1.1 2004/06/25 21:55:50 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/alter_type.sgml,v 1.2 2005/08/01 16:11:14 tgl Exp $
 PostgreSQL documentation
 -->

@@ -25,6 +25,7 @@ PostgreSQL documentation
 <refsynopsisdiv>
  <synopsis>
 ALTER TYPE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceable class="PARAMETER">new_owner</replaceable> 
+ALTER TYPE <replaceable class="PARAMETER">name</replaceable> SET SCHEMA <replaceable class="PARAMETER">new_schema</replaceable>
  </synopsis>
 </refsynopsisdiv>

@@ -33,7 +34,8 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceab

  <para>
   <command>ALTER TYPE</command> changes the definition of an existing type.
-   The only currently available capability is changing the owner of a type.
+   The only currently available capabilities are changing the owner and schema
+   of a type.
  </para>
 </refsect1>

@@ -62,6 +64,17 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceab
      </listitem>
     </varlistentry>

+     <varlistentry>
+      <term><replaceable class="PARAMETER">new_schema</replaceable></term>
+      <listitem>
+       <para>
+        The new schema for the type.  To move a
+        type to a new schema, you must be the owner of the
+        type and have <literal>CREATE</> privilege on the new schema.
+       </para>
+      </listitem>
+     </varlistentry>
+
    </variablelist>
   </para>
  </refsect1>
@@ -76,6 +89,14 @@ ALTER TYPE <replaceable class="PARAMETER">name</replaceable> OWNER TO <replaceab
 ALTER TYPE email OWNER TO joe;
   </programlisting>
  </para>
+
+  <para>
+   To change the schema of the user-defined type <literal>email</literal>
+   to <literal>customers</literal>:
+   <programlisting>
+ALTER TYPE email SET SCHEMA customers;
+   </programlisting>
+  </para>
 </refsect1>

 <refsect1>