Home Explore Blog CI



postgresql

4th chunk of `doc/src/sgml/manage-ag.sgml`
5b1c26752f04f906fdb023e06f02a72d870e4d329fdbb97e0000000100000fa1
 being taken when those databases are created.
  </para>

  <para>
   However, <command>CREATE DATABASE</command> does not copy database-level
   <command>GRANT</command> permissions attached to the source database.
   The new database has default database-level permissions.
  </para>

  <para>
   There is a second standard system database named
   <literal>template0</literal>.<indexterm><primary>template0</primary></indexterm> This
   database contains the same data as the initial contents of
   <literal>template1</literal>, that is, only the standard objects
   predefined by your version of
   <productname>PostgreSQL</productname>.  <literal>template0</literal>
   should never be changed after the database cluster has been
   initialized.  By instructing
   <command>CREATE DATABASE</command> to copy <literal>template0</literal> instead
   of <literal>template1</literal>, you can create a <quote>pristine</quote> user
   database (one where no user-defined objects exist and where the system
   objects have not been altered) that contains none of the site-local additions in
   <literal>template1</literal>.  This is particularly handy when restoring a
   <literal>pg_dump</literal> dump: the dump script should be restored in a
   pristine database to ensure that one recreates the correct contents
   of the dumped database, without conflicting with objects that
   might have been added to <literal>template1</literal> later on.
  </para>

  <para>
   Another common reason for copying <literal>template0</literal> instead
   of <literal>template1</literal> is that new encoding and locale settings
   can be specified when copying <literal>template0</literal>, whereas a copy
   of <literal>template1</literal> must use the same settings it does.
   This is because <literal>template1</literal> might contain encoding-specific
   or locale-specific data, while <literal>template0</literal> is known not to.
  </para>

  <para>
   To create a database by copying <literal>template0</literal>, use:
<programlisting>
CREATE DATABASE <replaceable>dbname</replaceable> TEMPLATE template0;
</programlisting>
   from the SQL environment, or:
<programlisting>
createdb -T template0 <replaceable>dbname</replaceable>
</programlisting>
   from the shell.
  </para>

  <para>
   It is possible to create additional template databases, and indeed
   one can copy any database in a cluster by specifying its name
   as the template for <command>CREATE DATABASE</command>.  It is important to
   understand, however, that this is not (yet) intended as
   a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
   The principal limitation is that no other sessions can be connected to
   the source database while it is being copied.  <command>CREATE
   DATABASE</command> will fail if any other connection exists when it starts;
   during the copy operation, new connections to the source database
   are prevented.
  </para>

  <para>
   Two useful flags exist in <literal>pg_database</literal><indexterm><primary>pg_database</primary></indexterm> for each
   database: the columns <literal>datistemplate</literal> and
   <literal>datallowconn</literal>.  <literal>datistemplate</literal>
   can be set to indicate that a database is intended as a template for
   <command>CREATE DATABASE</command>.  If this flag is set, the database can be
   cloned by any user with <literal>CREATEDB</literal> privileges; if it is not set,
   only superusers and the owner of the database can clone it.
   If <literal>datallowconn</literal> is false, then no new connections
   to that database will be allowed (but existing sessions are not terminated
   simply by setting the flag false).  The <literal>template0</literal>
   database is normally marked <literal>datallowconn = false</literal> to prevent its modification.
   Both <literal>template0</literal> and <literal>template1</literal>
   should always be marked with <literal>datistemplate = true</literal>.
  </para>

  <note>

Title: Template Databases: template0 and Custom Templates
Summary
CREATE DATABASE doesn't copy database-level GRANT permissions. template0 contains only standard objects and should not be altered after initialization. Copying template0 creates a 'pristine' database, useful when restoring pg_dump dumps. template0 can also be used when specifying new encoding and locale settings. Use CREATE DATABASE ... TEMPLATE template0 or createdb -T template0 to copy it. Any database can be a template, but no other sessions can be connected during the copy. pg_database columns datistemplate and datallowconn control template eligibility and connection allowances. datistemplate grants CREATEDB privileges for cloning; datallowconn prevents new connections. template0 should have datallowconn = false and both template0 and template1 should have datistemplate = true.