Add 'basebackup_to_shell' contrib module.

As a demonstration of the sort of thing that can be done by adding a
custom backup target, this defines a 'shell' target which executes a
command defined by the system administrator. The command is executed
once for each tar archive generate by the backup and once for the
backup manifest, if any. Each time the command is executed, it
receives the contents of th file for which it is executed via standard
input.

The configured command can use %f to refer to the name of the archive
(e.g. base.tar, $TABLESPACE_OID.tar, backup_manifest) and %d to refer
to the target detail (pg_basebackup --target shell:DETAIL). A target
detail is required if %d appears in the configured command and
forbidden if it does not.

Patch by me, reviewed by Abhijit Menon-Sen.

Discussion: http://postgr.es/m/CA+TgmoaqvdT-u3nt+_kkZ7bgDAyqDB0i-+XOMmr5JN2Rd37hxw@mail.gmail.com

3 files changed, 71 insertions, 0 deletions

diff --git a/doc/src/sgml/basebackup-to-shell.sgml b/doc/src/sgml/basebackup-to-shell.sgml
new file mode 100644
index 00000000000..f36f37e5104
--- /dev/null
+++ b/doc/src/sgml/basebackup-to-shell.sgml
@@ -0,0 +1,69 @@
+<!-- doc/src/sgml/basebackup-to-shell.sgml -->
+
+<sect1 id="basebackup-to-shell" xreflabel="basebackup_to_shell">
+ <title>basebackup_to_shell</title>
+
+ <indexterm zone="basebackup-to-shell">
+  <primary>basebackup_to_shell</primary>
+ </indexterm>
+
+ <para>
+  <filename>basebackup_to_shell</filename> adds a custom basebackup target
+  called <literal>shell</literal>. This makes it possible to run
+  <literal>pg_basebackup --target=shell</literal> or, depending on how this
+  module is configured,
+  <literal>pg_basebackup --target=shell:DETAIL_STRING</literal>, and cause
+  a server command chosen by the server administrator to be executed for
+  each tar archive generated by the backup process. The command will receive
+  the contents of the archive via standard input.
+ </para>
+
+ <para>
+  This module is primarily intended as an example of how to create a new
+  backup targets via an extension module, but in some scenarios it may be
+  useful for its own sake.
+  In order to function, this module must be loaded via
+  <xref linkend="guc-shared-preload-libraries"/> or
+  <xref linkend="guc-local-preload-libraries"/>.
+ </para>
+
+ <sect2>
+  <title>Configuration Parameters</title>
+
+  <variablelist>
+   <varlistentry>
+    <term>
+     <varname>basebackup_to_shell.command</varname> (<type>string</type>)
+     <indexterm>
+      <primary><varname>basebackup_to_shell.command</varname> configuration parameter</primary>
+     </indexterm>
+    </term>
+    <listitem>
+     <para>
+      The command which the server should execute for each archive generated
+      by the backup process. If <literal>%f</literal> occurs in the command
+      string, it will be replaced by the name of the archive (e.g.
+      <literal>base.tar</literal>). If <literal>%d</literal> occurs in the
+      command string, it will be replaced by the target detail provided by
+      the user. A target detail is required if <literal>%d</literal> is
+      used in the command string, and prohibited otherwise. For security
+      reasons, it may contain only alphanumeric characters. If
+      <literal>%%</literal> occurs in the command string, it will be replaced
+      by a single <literal>%</literal>. If <literal>%</literal> occurs in
+      the command string followed by any other character or at the end of the
+      string, an error occurs.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </sect2>
+
+ <sect2>
+  <title>Author</title>
+
+  <para>
+   Robert Haas <email>rhaas@postgresql.org</email>
+  </para>
+ </sect2>
+
+</sect1>
diff --git a/doc/src/sgml/contrib.sgml b/doc/src/sgml/contrib.sgml
index be9711c6f2c..1e42ce1a7f7 100644
--- a/doc/src/sgml/contrib.sgml
+++ b/doc/src/sgml/contrib.sgml
@@ -99,6 +99,7 @@ CREATE EXTENSION <replaceable>module_name</replaceable>;
  &amcheck;
  &auth-delay;
  &auto-explain;
+ &basebackup-to-shell;
  &basic-archive;
  &bloom;
  &btree-gin;
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 328cd1f378c..fd853af01fa 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -114,6 +114,7 @@
 <!ENTITY auth-delay      SYSTEM "auth-delay.sgml">
 <!ENTITY auto-explain    SYSTEM "auto-explain.sgml">
 <!ENTITY basic-archive   SYSTEM "basic-archive.sgml">
+<!ENTITY basebackup-to-shell SYSTEM "basebackup-to-shell.sgml">
 <!ENTITY bloom           SYSTEM "bloom.sgml">
 <!ENTITY btree-gin       SYSTEM "btree-gin.sgml">
 <!ENTITY btree-gist      SYSTEM "btree-gist.sgml">