<!-- doc/src/sgml/manage-ag.sgml -->

<chapter id="managing-databases">
 <title>Managing Databases</title>

 <indexterm zone="managing-databases"><primary>database</primary></indexterm>

 <para>
  Every instance of a running <productname>PostgreSQL</productname>
  server manages one or more databases.  Databases are therefore the
  topmost hierarchical level for organizing <acronym>SQL</acronym>
  objects (<quote>database objects</quote>).  This chapter describes
  the properties of databases, and how to create, manage, and destroy
  them.
 </para>

 <sect1 id="manage-ag-overview">
  <title>Overview</title>

  <indexterm zone="manage-ag-overview">
   <primary>schema</primary>
  </indexterm>

  <para>
   A small number of objects, like role, database, and tablespace
   names, are defined at the cluster level and stored in the
   <literal>pg_global</literal> tablespace.  Inside the cluster are
   multiple databases, which are isolated from each other but can access
   cluster-level objects.  Inside each database are multiple schemas,
   which contain objects like tables and functions.  So the full hierarchy
   is: cluster, database, schema, table (or some other kind of object,
   such as a function).
  </para>

  <para>
   When connecting to the database server, a client must specify the
   database name in its connection request.
   It is not possible to access more than one database per
   connection. However, clients can open multiple connections to
   the same database, or different databases.
   Database-level security has two components: access control
   (see <xref linkend="auth-pg-hba-conf"/>), managed at the
   connection level, and authorization control
   (see <xref linkend="ddl-priv"/>), managed via the grant system.
   Foreign data wrappers (see <xref linkend="postgres-fdw"/>)
   allow for objects within one database to act as proxies for objects in
   other database or clusters.
   The older dblink module (see <xref linkend="dblink"/>) provides a similar capability.
   By default, all users can connect to all databases using all connection methods.
  </para>

  <para>
   If one <productname>PostgreSQL</productname> server cluster is planned to contain
   unrelated projects or users that should be, for the most part, unaware
   of each other, it is recommended to put them into separate databases and
   adjust authorizations and access controls accordingly.
   If the projects or users are interrelated, and thus should be able to use
   each other's resources, they should be put in the same database but probably
   into separate schemas;  this provides a modular structure with namespace
   isolation and authorization control.
   More information about managing schemas is in <xref linkend="ddl-schemas"/>.
  </para>

  <para>
   While multiple databases can be created within a single cluster, it is advised
   to consider carefully whether the benefits outweigh the risks and limitations.
   In particular, the impact that having a shared WAL (see <xref linkend="wal"/>)
   has on backup and recovery options. While individual databases in the cluster
   are isolated when considered from the user's perspective, they are closely bound
   from the database administrator's point-of-view.
  </para>

  <para>
   Databases are created with the <command>CREATE DATABASE</command> command
   (see <xref linkend="manage-ag-createdb"/>) and destroyed with the
   <command>DROP DATABASE</command> command
   (see <xref linkend="manage-ag-dropdb"/>).
   To determine the set of existing databases, examine the
   <structname>pg_database</structname> system catalog, for example
<synopsis>
SELECT datname FROM pg_database;
</synopsis>
   The <xref linkend="app-psql"/> program's <literal>\l</literal> meta-command
   and <option>-l</option> command-line option are also useful for listing the
   existing databases.
  </para>

  <note>
   <para>
    The <acronym>SQL</acronym> standard calls databases <quote>catalogs</quote>, but there
    is no difference