From: Craig Ringer <craig@2ndquadrant.com>
Date: Mon, 23 Mar 2015 03:43:42 +0000 (+0800)
Subject: bdr: doc: Add stub docs for upgrade
X-Git-Tag: bdr-plugin/0.9.0~27
X-Git-Url: http://git.postgresql.org/gitweb/static/gitweb.js?a=commitdiff_plain;h=da922b95ac1e9ecbd09cd83a52bd805c38898d7c;p=2ndquadrant_bdr.git

bdr: doc: Add stub docs for upgrade

Add skeletal upgrade docs with entry for bdr_upgrade_to_090.

Also documents bdr_replicate_ddl_command
---

diff --git a/doc/bdr.sgml b/doc/bdr.sgml
index 60fea5ff5a..fe1b116db3 100644
--- a/doc/bdr.sgml
+++ b/doc/bdr.sgml
@@ -81,6 +81,7 @@
   &manual-monitoring;
   &manual-settings;
   &manual-functions;
+  &manual-upgrade;
 
  </part>
 
diff --git a/doc/filelist.sgml b/doc/filelist.sgml
index 6035229354..55fd9da2da 100644
--- a/doc/filelist.sgml
+++ b/doc/filelist.sgml
@@ -45,4 +45,5 @@
 <!ENTITY manual-monitoring      SYSTEM "manual-monitoring.sgml">
 <!ENTITY manual-settings      SYSTEM "manual-settings.sgml">
 <!ENTITY manual-functions      SYSTEM "manual-functions.sgml">
+<!ENTITY manual-upgrade		SYSTEM "manual-upgrade.sgml">
 <!ENTITY appendix-signatures      SYSTEM "appendix-signatures.sgml">
diff --git a/doc/manual-functions.sgml b/doc/manual-functions.sgml
index 992068f44c..399c40ed49 100644
--- a/doc/manual-functions.sgml
+++ b/doc/manual-functions.sgml
@@ -17,10 +17,11 @@
 
  <warning>
   <para>
-   Do <emphasis>not</emphasis> directly call functions with the suffix
+   Do <emphasis>not</emphasis> directly call functions with the prefix
    <literal>internal</literal>, they are intended for &bdr;'s internal
    use only and may lack sanity checks present in the public-facing
-   functions. Stick to using the functions documented here, others
+   functions and <emphasis>could break your replication setup</emphasis>.
+   Stick to using the functions documented here, others
    are subject to change without notice.
   </para>
  </warning>
@@ -134,6 +135,7 @@
         </indexterm>
         <literal><function>bdr.bdr_apply_pause()</function></literal>
        </entry>
+       <entry>void</entry>
        <entry>
         Temporarily stop applying changes from remote nodes to the local node,
         until resume is requested with
@@ -156,12 +158,30 @@
         </indexterm>
         <literal><function>bdr.bdr_apply_resume()</function></literal>
        </entry>
+       <entry>void</entry>
        <entry>
         Resume replaying changes from peer nodes after replay has been paused
         by <function>bdr.bdr_apply_pause()</function>.
        </entry>
       </row>
 
+      <row>
+       <entry>&bdr;</entry>
+       <entry>
+        <indexterm>
+         <primary>bdr.bdr_replicate_ddl_command</primary>
+        </indexterm>
+        <literal><function>bdr.bdr_replicate_ddl_command(<replaceable>cmd text</replaceable>)</function></literal>
+       </entry>
+       <entry>void</entry>
+       <entry>
+        Execute the <acronym>SQL</acronym> (usually <acronym>DDL</acronym>)
+        <replaceable>cmd</replaceable> on the local node and queue it for
+        extension on all peer nodes. <emphasis>This function is mainly for &bdr; internal
+        use and bypasses some safety checks, use with caution.</emphasis>
+       </entry>
+      </row>
+
      </tbody>
     </tgroup>
    </table>
@@ -472,4 +492,42 @@
 
  </sect1>
 
+ <sect1 id="functions-upgrade" xreflabel="Upgrade functions">
+  <title>Upgrade functions</title>
+
+  <para>
+   The following function(s) are used when upgrading &bdr; to a new version:
+
+   <table>
+    <title>Upgrade functions</title>
+    <tgroup cols="4">
+     <thead>
+      <row>
+       <entry>&udr;/&bdr;</entry>
+       <entry>Function</entry>
+       <entry>Return Type</entry>
+       <entry>Description</entry>
+      </row>
+     </thead>
+     <tbody>
+
+      <row>
+       <entry>&bdr;</entry>
+       <entry>
+        <indexterm>
+         <primary>bdr.bdr_upgrade_to_090</primary>
+        </indexterm>
+        <literal><function>bdr.bdr_upgrade_to_090(<replaceable>my_conninfo cstring</replaceable>, <replaceable>local_conninfo cstring</replaceable>, <replaceable>remote_conninfo cstring</replaceable>)</function></literal>
+       </entry>
+       <entry>void</entry>
+       <entry>Used during upgrade from 0.7.x or 0.8.x to &bdr; version 0.9.x. See <xref linkend="upgrade">.</entry>
+      </row>
+
+     </tbody>
+    </tgroup>
+   </table>
+  </para>
+
+ </sect1>
+
 </chapter>
diff --git a/doc/manual-upgrade.sgml b/doc/manual-upgrade.sgml
new file mode 100644
index 0000000000..9765cc0ccb
--- /dev/null
+++ b/doc/manual-upgrade.sgml
@@ -0,0 +1,15 @@
+<chapter id="upgrade" xreflabel="Upgrading BDR">
+ <title>Upgrading &bdr;</title>
+ <indexterm>
+  <primary>Upgrading BDR</primary>
+ </indexterm>
+
+ <para>
+  Documentation for the process of upgrading &bdr; from 0.7.x or 0.8.x to the current-at-time-of-writing 0.9.x release is currently under development.
+ </para>
+ 
+ <para>
+  See also: <xref linkend="functions-upgrade">.
+ </para>
+
+</chapter>