diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index aa0d23b02fe5625ad2cd21ca0f909f47740f4521..c039f661b0cdf94a3bced27829721f0d23dd874e 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.38 2002/04/24 02:49:50 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.39 2002/04/25 21:47:07 tgl Exp $
PostgreSQL documentation
Complete list of usable sgml source files in this directory.
-->
@@ -60,6 +60,7 @@ Complete list of usable sgml source files in this directory.
<!entity createLanguage system "create_language.sgml">
<!entity createOperator system "create_operator.sgml">
<!entity createRule system "create_rule.sgml">
+<!entity createSchema system "create_schema.sgml">
<!entity createSequence system "create_sequence.sgml">
<!entity createTable system "create_table.sgml">
<!entity createTableAs system "create_table_as.sgml">
diff --git a/doc/src/sgml/ref/create_schema.sgml b/doc/src/sgml/ref/create_schema.sgml
new file mode 100644
index 0000000000000000000000000000000000000000..64f96b34d9a8808253c92544eaad4a0faa6a4acf
--- /dev/null
+++ b/doc/src/sgml/ref/create_schema.sgml
@@ -0,0 +1,240 @@
+<!--
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_schema.sgml,v 1.1 2002/04/25 21:47:07 tgl Exp $
+PostgreSQL documentation
+-->
+
+<refentry id="SQL-CREATESCHEMA">
+ <refmeta>
+ <refentrytitle id="sql-createschema-title">CREATE SCHEMA</refentrytitle>
+ <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname>
+ CREATE SCHEMA
+ </refname>
+ <refpurpose>
+ define a new schema
+ </refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <synopsis>
+CREATE SCHEMA <replaceable class="parameter">schemaname</replaceable> [ AUTHORIZATION <replaceable class="parameter">username</replaceable> ] [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
+CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable> [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
+ </synopsis>
+
+ <refsect2 id="R2-SQL-CREATESCHEMA-1">
+ <title>
+ Inputs
+ </title>
+ <para>
+
+ <variablelist>
+ <varlistentry>
+ <term><replaceable class="parameter">schemaname</replaceable></term>
+ <listitem>
+ <para>
+ The name of a schema to be created. If this is omitted, the username
+ is used as the schema name.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="parameter">username</replaceable></term>
+ <listitem>
+ <para>
+ The name of the user who will own the schema. If omitted,
+ defaults to the user executing the command. Only superusers
+ may create schemas owned by users other than themselves.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><replaceable class="parameter">schema_element</replaceable></term>
+ <listitem>
+ <para>
+ An SQL statement defining an object to be created within the schema.
+ Currently, only <command>CREATE TABLE</>, <command>CREATE VIEW</>,
+ and <command>GRANT</> are accepted as clauses within
+ <command>CREATE SCHEMA</>. Other kinds of objects may be created
+ in separate commands after the schema is created.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-SQL-CREATESCHEMA-2">
+ <title>
+ Outputs
+ </title>
+ <para>
+
+ <variablelist>
+ <varlistentry>
+ <term><computeroutput>
+CREATE
+ </computeroutput></term>
+ <listitem>
+ <para>
+ Message returned if the command is successful.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><computeroutput>
+ERROR: namespace "<replaceable class="parameter">schemaname</replaceable>" already exists
+ </computeroutput></term>
+ <listitem>
+ <para>
+ If the schema specified already exists.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect2>
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-SQL-CREATESCHEMA-1">
+ <title>
+ Description
+ </title>
+ <para>
+ <command>CREATE SCHEMA</command> will enter a new schema
+ into the current database.
+ The schema name must be distinct from the name of any existing schema
+ in the current database.
+ </para>
+
+ <para>
+ A schema is essentially a namespace:
+ it contains named objects (tables, datatypes, functions, and operators)
+ whose names may duplicate those of other objects existing in other
+ schemas. Named objects are accessed either by <quote>qualifying</>
+ their names with the schema name as a prefix, or by setting a search
+ path that includes the desired schema(s).
+ </para>
+
+ <para>
+ Optionally, <command>CREATE SCHEMA</command> can include subcommands
+ to create objects within the new schema. The subcommands are treated
+ essentially the same as separate commands issued after creating the
+ schema, except that if the <literal>AUTHORIZATION</> clause is used,
+ all the created objects will be owned by that user.
+ </para>
+
+ <refsect2 id="R2-SQL-CREATESCHEMA-3">
+ <title>
+ Notes
+ </title>
+
+ <para>
+ To create a schema, the invoking user must have <literal>CREATE</>
+ privilege for the current database. (Of course, superusers bypass
+ this check.)
+ </para>
+
+ <para>
+ Use <command>DROP SCHEMA</command> to remove a schema.
+ </para>
+ </refsect2>
+ </refsect1>
+
+ <refsect1 id="R1-SQL-CREATESCHEMA-2">
+ <title>
+ Examples
+ </title>
+ <para>
+ Create a schema:
+
+ <programlisting>
+CREATE SCHEMA myschema;
+ </programlisting>
+ </para>
+
+ <para>
+ Create a schema for user <literal>joe</> --- the schema will also
+ be named <literal>joe</>:
+
+ <programlisting>
+CREATE SCHEMA AUTHORIZATION joe;
+ </programlisting>
+ </para>
+
+ <para>
+ Create a schema and create a table and view within it:
+
+ <programlisting>
+CREATE SCHEMA hollywood
+ CREATE TABLE films (title text, release date, awards text[])
+ CREATE VIEW winners AS
+ SELECT title, release FROM films WHERE awards IS NOT NULL;
+ </programlisting>
+ Notice that the individual subcommands do not end with semicolons.
+ </para>
+
+ <para>
+ The following is an equivalent way of accomplishing the same result:
+ <programlisting>
+CREATE SCHEMA hollywood;
+CREATE TABLE hollywood.films (title text, release date, awards text[]);
+CREATE VIEW hollywood.winners AS
+ SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL;
+ </programlisting>
+ </para>
+ </refsect1>
+
+ <refsect1 id="R1-SQL-CREATESCHEMA-3">
+ <title>
+ Compatibility
+ </title>
+
+ <refsect2 id="R2-SQL-CREATESCHEMA-4">
+ <title>
+ SQL92
+ </title>
+
+ <para>
+ SQL92 allows a <literal>DEFAULT CHARACTER SET</> clause in
+ <command>CREATE SCHEMA</command>, as well as more subcommand types
+ than are presently accepted by <productname>PostgreSQL</productname>.
+ </para>
+
+ <para>
+ SQL92 specifies that the subcommands in <command>CREATE SCHEMA</command>
+ may appear in any order. The present
+ <productname>PostgreSQL</productname> implementation does not handle all
+ cases of forward references in subcommands; it may sometimes be necessary
+ to reorder the subcommands to avoid forward references.
+ </para>
+
+ <para>
+ In SQL92, the owner of a schema always owns all objects within it.
+ <productname>PostgreSQL</productname> allows schemas to contain objects
+ owned by users other than the schema owner. This can happen only if the
+ schema owner grants <literal>CREATE</> rights on his schema to someone
+ else.
+ </para>
+ </refsect2>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index a91acd4f66932a41a1828c07bf269502852a16fe..d1d40f3a72b6aadec1b8163cb01834d0f6f422e4 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -1,5 +1,5 @@
<!-- reference.sgml
-$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.27 2002/04/24 02:49:50 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.28 2002/04/25 21:47:06 tgl Exp $
PostgreSQL Reference Manual
-->
@@ -69,6 +69,7 @@ PostgreSQL Reference Manual
&createLanguage;
&createOperator;
&createRule;
+ &createSchema;
&createSequence;
&createTable;
&createTableAs;