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

<refentry id="app-pgbasebackup">
 <indexterm zone="app-pgbasebackup">
  <primary>pg_basebackup</primary>
 </indexterm>

 <refmeta>
  <refentrytitle><application>pg_basebackup</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_basebackup</refname>
  <refpurpose>take a base backup of a <productname>PostgreSQL</productname> cluster</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_basebackup</command>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <para>
   <application>pg_basebackup</application> is used to take a base backup of
   a running <productname>PostgreSQL</productname> database cluster. The backup
   is taken without affecting other clients of the database, and can be used
   both for point-in-time recovery (see <xref linkend="continuous-archiving"/>)
   and as the starting point for a log-shipping or streaming-replication standby
   server (see <xref linkend="warm-standby"/>).
  </para>

  <para>
   <application>pg_basebackup</application> can take a full or incremental
   base backup of the database. When used to take a full backup, it makes an
   exact copy of the database cluster's files. When used to take an incremental
   backup, some files that would have been part of a full backup may be
   replaced with incremental versions of the same files, containing only those
   blocks that have been modified since the reference backup. An incremental
   backup cannot be used directly; instead,
   <xref linkend="app-pgcombinebackup"/> must first
   be used to combine it with the previous backups upon which it depends.
   See <xref linkend="backup-incremental-backup" /> for more information
   about incremental backups, and <xref linkend="backup-pitr-recovery" />
   for steps to recover from a backup.
  </para>

  <para>
   In any mode, <application>pg_basebackup</application> makes sure the server
   is put into and out of backup mode automatically. Backups are always taken of
   the entire database cluster; it is not possible to back up individual
   databases or database objects. For selective backups, another tool such as
   <xref linkend="app-pgdump"/> must be used.
  </para>

  <para>
   The backup is made over a regular <productname>PostgreSQL</productname>
   connection that uses the replication protocol. The connection must be made
   with a user ID that has <literal>REPLICATION</literal> permissions
   (see <xref linkend="role-attributes"/>) or is a superuser,
   and <link linkend="auth-pg-hba-conf"><filename>pg_hba.conf</filename></link>
   must permit the replication connection. The server must also be configured
   with <xref linkend="guc-max-wal-senders"/> set high enough to provide at
   least one walsender for the backup plus one for WAL streaming (if used).
  </para>

  <para>
   There can be multiple <command>pg_basebackup</command>s running at the same time, but it is usually
   better from a performance point of view to take only one backup, and copy
   the result.
  </para>

  <para>
   <application>pg_basebackup</application> can make a base backup from
   not only a primary server but also a standby. To take a backup from a standby,
   set up the standby so that it can accept replication connections (that is, set
   <varname>max_wal_senders</varname> and <xref linkend="guc-hot-standby"/>,
   and configure its <filename>pg_hba.conf</filename> appropriately).
   You will also need to enable <xref linkend="guc-full-page-writes"/> on the primary.
  </para>

  <para>
   Note that there are some limitations in taking a backup from a standby:

   <itemizedlist>
    <listitem>
     <para>
      The backup history file is not created in the database cluster backed up.
     </para>
    </listitem>
    <listitem>
     <para>
      <application>pg_basebackup</application>