granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/create_schema.sgml

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/create_schema.sgml,v 1.13 2004/06/25 21:55:50 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATESCHEMA">
   7  <refmeta>
   8   <refentrytitle id="sql-createschema-title">CREATE SCHEMA</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CREATE SCHEMA</refname>
  14   <refpurpose>define a new schema</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-createschema">
  18   <primary>CREATE SCHEMA</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CREATE SCHEMA <replaceable class="parameter">schemaname</replaceable> [ AUTHORIZATION <replaceable class="parameter">username</replaceable> ] [ TABLESPACE <replaceable class="parameter">tablespace</replaceable> ] [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
  24 CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">username</replaceable> [ TABLESPACE <replaceable class="parameter">tablespace</replaceable> ] [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
  25 </synopsis>
  26  </refsynopsisdiv>
  27
  28  <refsect1>
  29   <title>Description</title>
  30
  31   <para>
  32    <command>CREATE SCHEMA</command> will enter a new schema
  33    into the current database.
  34    The schema name must be distinct from the name of any existing schema
  35    in the current database.
  36   </para>
  37
  38   <para>
  39    A schema is essentially a namespace:
  40    it contains named objects (tables, data types, functions, and operators)
  41    whose names may duplicate those of other objects existing in other
  42    schemas.  Named objects are accessed either by <quote>qualifying</>
  43    their names with the schema name as a prefix, or by setting a search
  44    path that includes the desired schema(s).  Unqualified objects are
  45    created in the current schema (the one at the front of the search path,
  46    which can be determined with the function <function>current_schema</function>).
  47   </para>
  48
  49   <para>
  50    Optionally, <command>CREATE SCHEMA</command> can include subcommands
  51    to create objects within the new schema.  The subcommands are treated
  52    essentially the same as separate commands issued after creating the
  53    schema, except that if the <literal>AUTHORIZATION</> clause is used,
  54    all the created objects will be owned by that user.
  55   </para>
  56  </refsect1>
  57
  58  <refsect1>
  59   <title>Parameters</title>
  60
  61     <variablelist>
  62      <varlistentry>
  63       <term><replaceable class="parameter">schemaname</replaceable></term>
  64       <listitem>
  65        <para>
  66         The name of a schema to be created.  If this is omitted, the user name
  67         is used as the schema name.  The name cannot
  68         begin with <literal>pg_</literal>, as such names
  69         are reserved for system schemas.
  70        </para>
  71       </listitem>
  72      </varlistentry>
  73
  74      <varlistentry>
  75       <term><replaceable class="parameter">username</replaceable></term>
  76       <listitem>
  77        <para>
  78         The name of the user who will own the schema.  If omitted,
  79         defaults to the user executing the command.  Only superusers
  80         may create schemas owned by users other than themselves.
  81        </para>
  82       </listitem>
  83      </varlistentry>
  84
  85      <varlistentry>
  86       <term><replaceable class="parameter">tablespace</replaceable></term>
  87       <listitem>
  88        <para>
  89         The name of the tablespace that is to be the default tablespace
  90         for all new objects created in the schema. If not supplied, the schema
  91         will inherit the default tablespace of the database.
  92        </para>
  93       </listitem>
  94      </varlistentry>
  95
  96      <varlistentry>
  97       <term><replaceable class="parameter">schema_element</replaceable></term>
  98       <listitem>
  99        <para>
 100         An SQL statement defining an object to be created within the
 101         schema. Currently, only <command>CREATE
 102         TABLE</>, <command>CREATE VIEW</>, <command>CREATE
 103         INDEX</>, <command>CREATE SEQUENCE</>, <command>CREATE
 104         TRIGGER</> and <command>GRANT</> are accepted as clauses
 105         within <command>CREATE SCHEMA</>. Other kinds of objects may
 106         be created in separate commands after the schema is created.
 107        </para>
 108       </listitem>
 109      </varlistentry>
 110     </variablelist>
 111  </refsect1>
 112
 113  <refsect1>
 114   <title>Notes</title>
 115
 116   <para>
 117    To create a schema, the invoking user must have the
 118    <literal>CREATE</> privilege for the current database.
 119    Also, the <literal>TABLESPACE</> option requires having
 120    <literal>CREATE</> privilege for the specified tablespace.
 121    (Of course, superusers bypass these checks.)
 122   </para>
 123  </refsect1>
 124
 125  <refsect1>
 126   <title>Examples</title>
 127
 128   <para>
 129    Create a schema:
 130 <programlisting>
 131 CREATE SCHEMA myschema;
 132 </programlisting>
 133   </para>
 134
 135   <para>
 136    Create a schema for user <literal>joe</>; the schema will also be
 137    named <literal>joe</>:
 138 <programlisting>
 139 CREATE SCHEMA AUTHORIZATION joe;
 140 </programlisting>
 141   </para>
 142
 143   <para>
 144    Create a schema and create a table and view within it:
 145 <programlisting>
 146 CREATE SCHEMA hollywood
 147     CREATE TABLE films (title text, release date, awards text[])
 148     CREATE VIEW winners AS
 149         SELECT title, release FROM films WHERE awards IS NOT NULL;
 150 </programlisting>
 151    Notice that the individual subcommands do not end with semicolons.
 152   </para>
 153
 154   <para>
 155    The following is an equivalent way of accomplishing the same result:
 156 <programlisting>
 157 CREATE SCHEMA hollywood;
 158 CREATE TABLE hollywood.films (title text, release date, awards text[]);
 159 CREATE VIEW hollywood.winners AS
 160     SELECT title, release FROM hollywood.films WHERE awards IS NOT NULL;
 161 </programlisting>
 162   </para>
 163  </refsect1>
 164
 165  <refsect1>
 166   <title>Compatibility</title>
 167
 168   <para>
 169    The SQL standard allows a <literal>DEFAULT CHARACTER SET</> clause
 170    in <command>CREATE SCHEMA</command>, as well as more subcommand
 171    types than are presently accepted by
 172    <productname>PostgreSQL</productname>.
 173   </para>
 174
 175   <para>
 176    The SQL standard specifies that the subcommands in <command>CREATE
 177    SCHEMA</command> may appear in any order.  The present
 178    <productname>PostgreSQL</productname> implementation does not
 179    handle all cases of forward references in subcommands; it may
 180    sometimes be necessary to reorder the subcommands in order to avoid
 181    forward references.
 182   </para>
 183
 184   <para>
 185    According to the SQL standard, the owner of a schema always owns
 186    all objects within it.  <productname>PostgreSQL</productname>
 187    allows schemas to contain objects owned by users other than the
 188    schema owner.  This can happen only if the schema owner grants the
 189    <literal>CREATE</> privilege on his schema to someone else.
 190   </para>
 191  </refsect1>
 192
 193  <refsect1>
 194   <title>See Also</title>
 195
 196   <simplelist type="inline">
 197    <member><xref linkend="sql-alterschema" endterm="sql-alterschema-title"></member>
 198    <member><xref linkend="sql-dropschema" endterm="sql-dropschema-title"></member>
 199     <member><xref linkend="sql-createtablespace" endterm="sql-createtablespace-title"></member>
 200  </simplelist>
 201  </refsect1>
 202
 203 </refentry>
 204
 205 <!-- Keep this comment at the end of the file
 206 Local variables:
 207 mode: sgml
 208 sgml-omittag:nil
 209 sgml-shorttag:t
 210 sgml-minimize-attributes:nil
 211 sgml-always-quote-attributes:t
 212 sgml-indent-step:1
 213 sgml-indent-data:t
 214 sgml-parent-document:nil
 215 sgml-default-dtd-file:"../reference.ced"
 216 sgml-exposed-tags:nil
 217 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 218 sgml-local-ecat-files:nil
 219 End:
 220 -->