bdr: Start to explain some concepts in the docs.

Initial explanation of distributed sequences, ddl replication and ddl
locking are included.

diff --git a/doc/bdr.sgml b/doc/bdr.sgml
index cb1fb1847c52516115c857a08561d1de70b4ab21..50d90653d5a8da6206f7c64e854d5f5674d6515d 100644 (file)
--- a/doc/bdr.sgml
+++ b/doc/bdr.sgml
@@ -74,7 +74,9 @@ To set up BDR you'll need to: ...
   <title>Main Manual</title>
   <partintro>
    <para>
-    This chapter documents <productname>BDR</productname>
+    This chapter documents how to
+    configure <productname>BDR</productname>
+    and <productname>UDR</productname>'s.
    </para>
   </partintro>
 
@@ -83,6 +85,79 @@ To set up BDR you'll need to: ...
    <para>sup</para>
   </chapter>
 
+  <chapter id="concepts">
+   <title>Concepts</title>
+
+    <sect1 id="ddl-replication">
+      <indexterm>
+        <primary>DDL replication</primary>
+      </indexterm>
+      <title>DDL Replication</title>
+
+      <para>
+        <productname>BDR</productname> supports replicating changes to
+        a database's schemas to other connected nodes. That allows to
+        quite easily make certain DDL changes without worrying about
+        having to deploy them on other nodes first (which is not
+        always possible).
+      </para>
+
+      <para>
+        To safely manipulate the database schema in a asynchronous
+        multimaster setup, all pending changes have to be replicated
+        first. Otherwise it can e.g. happen that a column constains
+        data for a row that has been dropped, or no data for a row
+        that is marked NOT NULL. To handle that
+        problem, <productname>BDR</productname> acquires a so called
+        DDL lock the first time in a transaction schema changes are
+        moade.
+      </para>
+
+      <para>
+        Acquiring such a DDL locks requires contacting all nodes in a
+        configiuration setup, asking them to replicate all pending
+        changes, and prevent further changes from being made. Once all
+        nodes are in that state, the originator of the DDL lock is
+        free to perform schema changes.
+      </para>
+
+      <para>
+        This means that schema changes, in contrary to data changes,
+        can only be performed while all configured nodes are
+        reachable. If DDL has to be performed while a node is down, it
+        has to be removed from the configuration (using
+        bdr.bdr_part_by_node_names <!-- FIXME: link once
+        documented-->) first.
+      </para>
+    </sect1>
+
+
+    <sect1 id="distributed-sequences">
+      <indexterm>
+        <primary>distributed sequences</primary>
+      </indexterm>
+      <title>distributed sequences</title>
+      <para>
+        In a asynchronous multimaster environment it can be hard to
+        have generated surrogate keys without a chance of
+        conflicts. Possible solutions includee using random
+        identifiers (like UUIDs) and assigning large ranges of values
+        to individual nodes.
+      </para>
+
+      <para>
+        <productname>BDR</productname> provides distributed sequences
+        as a solution for that problem, without preventing
+        implementation of other solutions. These assign small ranges
+        of values to individual nodes, which these than can hand out
+        during inserts. To make usage of these as simple as possible
+        all that has to be done to use these, in comparison to normal
+        sequences, is to specify the <literal>USING bdr</literal>
+        option when creating a sequence.
+      </para>
+    </sect1>
+  </chapter>
+
   <chapter id="settings">
    <title>Settings for BDR</title>