to be written to the same directory locations as the original
   tablespaces.
  </para>

  <para>
   When tar format is used, it is the user's responsibility to unpack each
   tar file before starting a PostgreSQL server that uses the data. If there
   are additional tablespaces, the
   tar files for them need to be unpacked in the correct locations. In this
   case the symbolic links for those tablespaces will be created by the server
   according to the contents of the <filename>tablespace_map</filename> file that is
   included in the <filename>base.tar</filename> file.
  </para>

  <para>
   <application>pg_basebackup</application> works with servers of the same
   or older major version, down to 9.1. However, WAL streaming mode (<literal>-X
   stream</literal>) only works with server version 9.3 and later, the tar format
   (<literal>--format=tar</literal>) only works with server version 9.5
   and later, and incremental backup (<literal>--incremental</literal>) only works
   with server version 17 and later.
  </para>

  <para>
   <application>pg_basebackup</application> will preserve group permissions
   for data files if group permissions are enabled on the source cluster.
  </para>

 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   To create a base backup of the server at <literal>mydbserver</literal>
   and store it in the local directory
   <filename>/usr/local/pgsql/data</filename>:
<screen>
<prompt>$</prompt> <userinput>pg_basebackup -h mydbserver -D /usr/local/pgsql/data</userinput>
</screen>
  </para>

  <para>
   To create a backup of the local server with one compressed
   tar file for each tablespace, and store it in the directory
   <filename>backup</filename>, showing a progress report while running:
<screen>
<prompt>$</prompt> <userinput>pg_basebackup -D backup -Ft -z -P</userinput>
</screen>
  </para>

  <para>
   To create a backup of a single-tablespace local database and compress
   this with <productname>bzip2</productname>:
<screen>
<prompt>$</prompt> <userinput>pg_basebackup -D - -Ft -X fetch | bzip2 &gt; backup.tar.bz2</userinput>
</screen>
   (This command will fail if there are multiple tablespaces in the
   database.)
  </para>

  <para>
   To create a backup of a local database where the tablespace in
   <filename>/opt/ts</filename> is relocated
   to <filename>./backup/ts</filename>:
<screen>
<prompt>$</prompt> <userinput>pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts</userinput>
</screen></para>

  <para>
   To create a backup of the local server with one tar file for each tablespace
   compressed with <application>gzip</application> at level 9, stored in the
   directory <filename>backup</filename>:
<screen>
<prompt>$</prompt> <userinput>pg_basebackup -D backup -Ft --compress=gzip:9</userinput>
</screen></para>

 </refsect1>

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="app-pgdump"/></member>
   <member><xref linkend="basebackup-progress-reporting"/></member>
  </simplelist>
 </refsect1>

</refentry>