Create a new GUC variable search_path to control the namespace search

path.  The default behavior if no per-user schemas are created is that
all users share a 'public' namespace, thus providing behavior backwards
compatible with 7.2 and earlier releases.  Probably the semantics and
default setting will need to be fine-tuned, but this is a start.

doc/src/sgml/runtime.sgml

@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.110 2002/03/24 04:31:06 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.111 2002/04/01 03:34:24 tgl Exp $
 -->
 
 <Chapter Id="runtime">
@@ -1174,7 +1174,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
 
        <para>
         The default value for this parameter is
-        <literal>$libdir</literal>. If the value is set to an empty
+        <literal>'$libdir'</literal>. If the value is set to an empty
         string, the automatic path search is turned off.
        </para>
 
@@ -1189,6 +1189,69 @@ dynamic_library_path = '/usr/local/lib/postgresql:/home/my_project/lib:$libdir'
       </listitem>
      </varlistentry>
 
+     <varlistentry>
+      <term><varname>SEARCH_PATH</varname> (<type>string</type>)</term>
+      <indexterm><primary>search_path</></>
+      <indexterm><primary>namespaces</></>
+      <listitem>
+       <para>
+        This variable specifies the order in which namespaces are searched
+	when an object (table, datatype, function, etc) is referenced by a
+	simple name with no schema component.  When there are objects of
+	identical names in different namespaces, the one found first
+	in the search path is used.  An object that is not in any of the
+	namespaces in the search path can only be referenced by specifying
+	its containing namespace with a qualified (dotted) name.
+       </para>
+
+       <para>
+        The value for search_path has to be a comma-separated
+        list of namespace (schema) names.  If one of the list items is
+        the special value <literal>$user</literal>, then the namespace
+	having the same name as the SESSION_USER is substituted, if there
+	is such a namespace.  (If not, <literal>$user</literal> is ignored.)
+       </para>
+
+       <para>
+        The system catalog namespace, <literal>pg_catalog</>, is always
+	searched, whether it is mentioned in the path or not.  If it is
+	mentioned in the path then it will be searched in the specified
+	order.  If <literal>pg_catalog</> is not in the path then it will
+	be searched <emphasis>before</> searching any of the path items.
+	It should also be noted that the temporary-table namespace,
+	<literal>pg_temp_nnn</>, is implicitly searched before any of
+	these.
+       </para>
+
+       <para>
+        When objects are created without specifying a particular target
+	namespace, they will be placed in the first namespace listed
+	in the search path, or in <literal>pg_catalog</> if the search
+	path list is empty.  (Note that users do not normally have
+	permission to write in <literal>pg_catalog</>, so an empty search
+	path is not a very useful setting.)
+       </para>
+
+       <para>
+        The default value for this parameter is
+        <literal>'$user, public'</literal> (where the second part will be
+	ignored if there is no namespace named <literal>public</>).
+	This supports shared use of a database (where no users
+	have private namespaces, and all share use of <literal>public</>),
+	private per-user namespaces, and combinations of these.  Other
+	effects can be obtained by altering the default search path
+	setting, either globally or per-user.
+       </para>
+
+       <para>
+        By default, a newly created database will contain a world-writable
+	namespace named <literal>public</>, but no private namespaces.
+	The administrator may choose to restrict permissions on
+	<literal>public</> or even remove it, if that suits his purposes.
+       </para>
+      </listitem>
+     </varlistentry>
+
      <varlistentry>
       <indexterm>
        <primary>fsync</primary>