imprecise pg_basebackup documentation about excluded files
The pg_basebackup documentation says that only regular files and
directories are "allowed" in the data directory. But it is more correct
that any other files are skipped. Attached is a patch to correct that.
I also added a link to the protocol documentation and added more
details there, also about pg_replslot handling. Not sure exactly how
much detail we want to document, but it seems reasonable to make it
complete if we provide a list at all.
Attachments:
basebackup-files-doc.patchtext/x-patch; name=basebackup-files-doc.patchDownload
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index c37113c..3a2421b 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1997,12 +1997,29 @@ <title>Streaming Replication Protocol</title>
</listitem>
<listitem>
<para>
+ various temporary files created during the operation of the PostgreSQL server
+ </para>
+ </listitem>
+ <listitem>
+ <para>
<filename>pg_xlog</>, including subdirectories. If the backup is run
with WAL files included, a synthesized version of <filename>pg_xlog</filename> will be
included, but it will only contain the files necessary for the
backup to work, not the rest of the contents.
</para>
</listitem>
+ <listitem>
+ <para>
+ <filename>pg_replslot</> is copied as an empty directory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Files other than regular files and directories, such as symbolic
+ links and special device files, are skipped. (Symbolic links
+ in <filename>pg_tblspc</filename> are maintained.)
+ </para>
+ </listitem>
</itemizedlist>
Owner, group and file mode are set if the underlying file system on
the server supports it.
diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml
index 97b0af9..10c1743 100644
--- a/doc/src/sgml/ref/pg_basebackup.sgml
+++ b/doc/src/sgml/ref/pg_basebackup.sgml
@@ -571,8 +571,10 @@ <title>Notes</title>
<para>
The backup will include all files in the data directory and tablespaces,
including the configuration files and any additional files placed in the
- directory by third parties. Only regular files and directories are allowed
- in the data directory, no symbolic links or special device files.
+ directory by third parties. But only regular files and directories are
+ copied. Symbolic links (other than those used for tablespaces) and special
+ device files are skipped. (See <xref linkend="protocol-replication"> for
+ the precise details.)
</para>
<para>
On Sat, May 10, 2014 at 3:33 AM, Peter Eisentraut <peter_e@gmx.net> wrote:
The pg_basebackup documentation says that only regular files and
directories are "allowed" in the data directory. But it is more correct
that any other files are skipped. Attached is a patch to correct that.
I also added a link to the protocol documentation and added more
details there, also about pg_replslot handling. Not sure exactly how
much detail we want to document, but it seems reasonable to make it
complete if we provide a list at all.
+1. Seems good to me.
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/