<!--
doc/src/sgml/ref/create_schema.sgml
PostgreSQL documentation
-->

<refentry id="sql-createschema">
 <indexterm zone="sql-createschema">
  <primary>CREATE SCHEMA</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>CREATE SCHEMA</refentrytitle>
  <manvolnum>7</manvolnum>
  <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">schema_name</replaceable> [ AUTHORIZATION <replaceable class="parameter">role_specification</replaceable> ] [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
CREATE SCHEMA AUTHORIZATION <replaceable class="parameter">role_specification</replaceable> [ <replaceable class="parameter">schema_element</replaceable> [ ... ] ]
CREATE SCHEMA IF NOT EXISTS <replaceable class="parameter">schema_name</replaceable> [ AUTHORIZATION <replaceable class="parameter">role_specification</replaceable> ]
CREATE SCHEMA IF NOT EXISTS AUTHORIZATION <replaceable class="parameter">role_specification</replaceable>

<phrase>where <replaceable class="parameter">role_specification</replaceable> can be:</phrase>

    <replaceable class="parameter">user_name</replaceable>
  | CURRENT_ROLE
  | CURRENT_USER
  | SESSION_USER
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>CREATE SCHEMA</command> enters 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, data types, functions, and operators)
   whose names can duplicate those of other objects existing in other
   schemas.  Named objects are accessed either by <quote>qualifying</quote>
   their names with the schema name as a prefix, or by setting a search
   path that includes the desired schema(s).  A <literal>CREATE</literal> command
   specifying an unqualified object name creates the object
   in the current schema (the one at the front of the search path,
   which can be determined with the function <function>current_schema</function>).
  </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</literal> clause is used,
   all the created objects will be owned by that user.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">schema_name</replaceable></term>
      <listitem>
       <para>
        The name of a schema to be created.  If this is omitted, the
        <replaceable class="parameter">user_name</replaceable>
        is used as the schema name.  The name cannot
        begin with <literal>pg_</literal>, as such names
        are reserved for system schemas.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><replaceable class="parameter">user_name</replaceable></term>
      <listitem>
       <para>
        The role name of the user who will own the new schema.  If omitted,
        defaults to the user executing the command.  To create a schema
        owned by another role, you must be able to
        <literal>SET ROLE</literal> to that role.
       </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>,