</keywordset>
</bookinfo>
-&install;
-
-<part id="quickstart">
- <title>Quick Start</title>
-
- <partintro>
- <para>
- This section gives a quick introduction into setting up a sample &bdr;
- installation.
- These instructions are not suitable for a production install, as
- they neglect security considerations, proper system administration
- procedure, etc. If you're trying to set up a production &bdr;
- install, read the rest of the &bdr; manual.
- For this Quick Start example, we are setting up a two node cluster with two
- PostgreSQL instances on the same server. We are using the terms node and instance
- interchangebly.
- </para>
- </partintro>
-
- &quickstart-install;
- &quickstart-test;
+ <part id="getting-started">
+ <title>Getting started</title>
+ &overview;
+ &quickstart;
</part>
- <part id="manual">
- <title>Main Manual</title>
- <partintro>
- <para>
- This chapter documents how to configure &bdr; and &udr;'s.
- </para>
- </partintro>
+ &install;
+
+<part id="manual" xreflabel="BDR administration manual">
+ <title>&bdr; administration manual</title>
- &manual-overview;
&manual-node-management;
&manual-ddl-replication;
&manual-commands;
Include external documentation sections
-->
<!ENTITY install SYSTEM "install.sgml">
+<!ENTITY install-requirements SYSTEM "install-requirements.sgml">
<!ENTITY install-packages SYSTEM "install-packages.sgml">
<!ENTITY install-source SYSTEM "install-source.sgml">
-<!ENTITY quickstart-install SYSTEM "quickstart-install.sgml">
-<!ENTITY quickstart-test SYSTEM "quickstart-test.sgml">
-<!ENTITY manual-overview SYSTEM "manual-overview.sgml">
+<!ENTITY quickstart SYSTEM "quickstart.sgml">
+<!ENTITY overview SYSTEM "overview.sgml">
<!ENTITY manual-node-management SYSTEM "manual-node-management.sgml">
<!ENTITY manual-ddl-replication SYSTEM "manual-ddl-replication.sgml">
<!ENTITY manual-commands SYSTEM "manual-commands.sgml">
--- /dev/null
+ <sect1 id="install-requirements" xreflabel="BDR and UDR requirements">
+ <title>&bdr; / &udr; requirements</title>
+
+ <para>
+ To use logical replication via &bdr; or &udr; you will need PostgreSQL 9.4
+ or newer. Earlier versions are not supported and will never be supported.
+ </para>
+
+ <para>
+ Currently &bdr; requires a modified version of PostgreSQL 9.4. This modified
+ PostgreSQL adds functionality BDR needs to support DDL replication, multi-master
+ last-update-wins conflict resolution, user-defined conflict handlers, etc. This
+ modified version of PostgreSQL 9.4 is available from the &bdr; download page
+ alongside the extension in both package and source form. This requirement
+ means that <emphasis>you can't use &bdr; on unmodified PostgreSQL 9.4</emphasis>.
+ <note>
+ <simpara>
+ All the new features required have been submitted for inclusion in
+ PostgreSQL 9.5. Many have already been accepted and included. If all the
+ functionality &bdr; requires is added to PostgreSQL 9.5 then the need for
+ a modified PostgreSQL will go away in the next version.
+ </simpara>
+ </note>
+ Some of these modifications make small changes to how PostgreSQL stores
+ data on disk. As a result the modified PostgreSQL 9.4 used by &bdr; can't
+ load data directories from unmodified PostgreSQL and vice versa. Users
+ must dump and reload their database(s) to switch to a &bdr;-capable PostgreSQL,
+ or use &udr; for online-upgrade. See <xref linkend="installation">.
+ </para>
+
+ <para>
+ &udr; runs on standard PostgreSQL 9.4 and is installed like any other
+ extension. It is a cut-down version of BDR that can work with only
+ the features present in PostgreSQL 9.4; see <xref linkend="overview-udr">.
+ </para>
+
+ <para>
+ As of the version this documentation was written for PostgreSQL 9.5 is
+ not yet supported. Neither is Microsoft Windows. Both of these limits
+ will be removed by a later release so check the
+ <ulink url="http://2ndquadrant.com/BDR">&bdr; website</ulink> for
+ the latest information.
+ </para>
+
+ </sect1>
only option if there are no packages for your operating system yet.
</para>
<para>
- Before installing &bdr; make sure you satisfy the <xref linkend="bdr-requirements">.
+ Before installing &bdr; make sure you satisfy the <xref linkend="install-requirements">.
</para>
+ &install-requirements;
&install-packages;
&install-source;
<chapter id="overview" xreflabel="Overview">
<title>&bdr;/&udr; overview</title>
- <sect1 id="bdr-udr-concepts">
- <title>&bdr; & &udr; concepts</title>
-
- <para>
- The &bdr; (Bi-Directional Replication for PostgreSQL) project adds
- multi-master asynchronous logical replication to PostgreSQL 9.4 and
- above.
- </para>
-
- <para>
- This means that you can write to any server and the changes will, after they
- have been committed, be sent row-by-row to all the aother servers that are
- part of the same BDR group<footnote><simpara>We'd say "cluster", but
- PostgreSQL has historically used that term for a different and confusing
- purpose, to mean a particular PostgreSQL instance's collection of
+ <para>
+ The &bdr; (Bi-Directional Replication) project adds multi-master replication
+ to PostgreSQL 9.4. This chapter explains what BDR is, how it works, and where
+ to best apply it. See <xref linkend="bdr-concepts"> to learn about
+ what &bdr; does and how it does it.
+ </para>
+
+ <para>
+ Because &bdr; requires a modified PostgreSQL 9.4 there is also a &udr;
+ (unidirectional replication) variant available. This version doesn't
+ require a modified version of PostgreSQL but has some limitations
+ that don't apply to &bdr;. See <xref linkend="overview-udr">.
+ </para>
+
+ <sect1 id="bdr-concepts" xreflabel="Concepts">
+ <title>Concepts</title>
+
+ <para>
+ &bdr; provides asynchronous multi-master logical replication. This means
+ that you can write to any server and the changes will, after they have been
+ committed, be sent row-by-row to all the other servers that are part of the
+ same BDR group<footnote><simpara>We'd say "cluster", but PostgreSQL has
+ historically used that term for a different and confusing purpose, to mean a
+ particular PostgreSQL instance's collection of
databases.</simpara></footnote>.
</para>
<para>
Because &bdr; needs some features that didn't make it into PostgreSQL by the
time 9.4 was released, it needs a modified PostgreSQL to run. See <xref
- linkend="bdr-requirements">.
- </para>
-
- <para>
- That's why we've also released &udr; - Uni-Directional Replication for PostgreSQL.
- &udr; is just &bdr; with support for things that won't work on unmodified PostgreSQL
- removed. Most importantly it can only replicate in one direction, so it
- doesn't support multi-master, and it cannot replicate DDL (schema changes).
- &udr; is mainly useful for read-replicas and for performing minimal-downtime
- upgrades to new PostgreSQL versions (or to PostgreSQL 9.4 with &bdr;). You can
- get &udr; from the same download locations as &bdr; (and in fact it's the same
- source code, just with different options). See <xref linkend="how-bdr-works">
- for more on the differences between &bdr; and &udr;.
+ linkend="install-requirements">. The &udr; variant can run on an unmodified
+ PostgreSQL - see <xref linkend="overview-udr">.
</para>
</sect1>
<sect1 id="weak-coupled-multimaster"
xreflabel="BDR: Weakly coupled multi-master replication">
- <title>&bdr;: weakly coupled multi-master replication</title>
+ <title>BDR: Weakly coupled multi-master replication</title>
<para>
When considering multi-master clustering or replication (with &bdr;
to determine which node to find data on. There is generally no global lock
manager or transaction manager, so transactions on one node aren't affected
by locks taken on other nodes. Many loosely coupled systems are asynchronous
- and eventually consistent (see: <xref linkend="bdr-udr-concepts">) so changes
+ and eventually consistent (see: <xref linkend="bdr-concepts">) so changes
on one node aren't immediately visible on all other nodes at the same time.
This can make application development more difficult, but in exchange makes
the system very tolerant of latency between nodes, temporary network
</sect1>
- <sect1 id="how-bdr-works" xreflabel="How BDR and UDR work">
- <title>How &bdr; and &udr; work</title>
+ <sect1 id="overview-udr">
+ <title>UDR: Single-master logical replication</title>
- <sect2>
- <title>Differences between &bdr; and &udr;</title>
+ <para>
+ &udr; (Uni-Directional Replication for PostgreSQL) is a cut-down version of
+ &bdr; that will run on an unmodified version of PostgreSQL 9.4. It is &bdr;
+ with all the features that can't work on unmodified PostgreSQL 9.4 removed.
+ </para>
- <!-- NEEDS-REVIEW -->
+ <para>
+ Most importantly &udr; can only replicate in one direction, so it doesn't
+ support multi-master. It cannot replicate DDL (schema changes), so users
+ must manually synchronise database schema changes. Unlike &bdr;, there are
+ no row-conflict resolution features in &udr;.
+ </para>
+
+ <para>
+ &udr; is mainly useful for read-replicas and for performing minimal-downtime
+ upgrades to new PostgreSQL versions (or to PostgreSQL 9.4 with &bdr;). It
+ offers some significant advantages over streaming replication and over
+ trigger based solutions; see <xref linkend="logical-vs-physical"> and
+ <xref linkend="bdr-vs-trigger-based">.
+ </para>
- <para>
- The most important difference between &bdr; and &udr; is that
- with &bdr; changes can be made on both nodes; and that methods
- for resolving conflicts arising due to that exist.
- </para>
+ <para>
+ You can get &udr; from the same download locations as &bdr; (and in fact
+ it's the same source code, just with different options).
+ </para>
- <sect3>
- <title>Primary Usecases for &udr;</title>
-
- <para>
- If changes are only ever made on one node and the others are
- just used for read scalability (including temporary tables on
- standbys), seamless major version upgrades or combining data
- from different nodes &udr; is sufficient. These scenarios cover
- a large number of replication scenarios.
- </para>
-
- <para>
- Using &udr; can noticeably reduce the likelihood of application
- incompatibilities. Only one database will be written to, which prevents
- conflicts and such. On the other hand, a &bdr; setup can make failover
- much easier, because there is no need to change the setup.
- </para>
-
- </sect3>
-
- <sect3>
- <title>Primary Usecases for &udr;</title>
- <para>
- <!-- NEEDS-REVIEW -->
- </para>
- </sect3>
- </sect2>
</sect1>
- <sect1 id="bdr-requirements" xreflabel="BDR and UDR requirements">
- <title>&bdr; / &udr; requirements</title>
+ <sect1 id="usecases-bdr" xreflabel="Primary use-cases for BDR">
+ <title>Primary use-cases for &bdr;</title>
<para>
- To use logical replication via &bdr; or &udr; you will need PostgreSQL 9.4
- or newer. Earlier versions are not supported and will never be supported.
+ &bdr; excels in environments where users are distributed across
+ high-latency and/or unreliable network links where conventional
+ tightly-coupled clustering software does not work well.
</para>
<para>
- Currently &bdr; requires a modified version of PostgreSQL 9.4. This modified
- PostgreSQL adds functionality BDR needs to support DDL replication, multi-master
- last-update-wins conflict resolution, user-defined conflict handlers, etc. This
- modified version of PostgreSQL 9.4 is available from the &bdr; download page
- alongside the extension in both package and source form. This requirement
- means that <emphasis>you can't use &bdr; on unmodified PostgreSQL 9.4</emphasis>.
- <note>
- <simpara>
- All the new features required have been submitted for inclusion in
- PostgreSQL 9.5. Many have already been accepted and included. If all the
- functionality &bdr; requires is added to PostgreSQL 9.5 then the need for
- a modified PostgreSQL will go away in the next version.
- </simpara>
- </note>
- Some of these modifications make small changes to how PostgreSQL stores
- data on disk. As a result the modified PostgreSQL 9.4 used by &bdr; can't
- load data directories from unmodified PostgreSQL and vice versa. Users
- must dump and reload their database(s) to switch to a &bdr;-capable PostgreSQL,
- or use &udr; for online-upgrade. See <xref linkend="installation">.
+ It is a particularly good choice where the application writes
+ entirely, or almost entirely, to data that is clustered by
+ user group or location. For example, a department store will
+ write almost exclusively to tables relevant to its branch.
</para>
+ <!-- XXX FIXME needs more content -->
+
+ </sect1>
+
+ <sect1 id="usecases-udr" xreflabel="Primary use-cases for UDR">
+ <title>Primary use-cases for &udr;</title>
+
<para>
- &udr; runs on standard PostgreSQL 9.4 and is installed like any other
- extension. It is a cut-down version of BDR that can work with only
- the features present in PostgreSQL 9.4; see <xref linkend="bdr-udr-concepts">.
+ If changes are only ever made on one node and the others are just used for
+ read scalability (including temporary tables on standbys), seamless major
+ version upgrades or combining data from different nodes &udr; is sufficient.
+ These scenarios cover a large number of replication scenarios.
</para>
<para>
- As of the version this documentation was written for PostgreSQL 9.5 is
- not yet supported. Neither is Microsoft Windows. Both of these limits
- will be removed by a later release so check the
- <ulink url="http://2ndquadrant.com/BDR">&bdr; website</ulink> for
- the latest information.
+ Using &udr; can noticeably reduce the likelihood of application
+ incompatibilities as compared to &bdr;. Only one database will be written
+ to, which prevents conflicts and such. On the other hand, a &bdr; setup can
+ make failover much easier, because there is no need to change the setup.
</para>
+ <!-- XXX FIXME needs more content -->
+
</sect1>
</chapter>
+++ /dev/null
- <chapter id="quickstart-test">
- <title>Enabling and Testing &bdr Demo </title>
- <sect1 id="Creating">
- <title>Creating the demo databases</title>
- <para>
- Create the databases for this demo on each node/instance from the command line of your operating system:
- </para>
- <programlisting>
- createdb -p 5598 -U postgres bdrdemo
- createdb -p 5599 -U postgres bdrdemo
- </programlisting>
- </sect1>
-
- <sect1 id="Enabling">
- <title>Enabling BDR in SQL sessions for both of your nodes/instances</title>
- <para>
- On the first node/instance in database <quote>bdrdemo</quote> as postgreSQL superuser, create the extensions necessary for &bdr;:
- </para>
- <programlisting>
- psql -p 5598 -U postgres bdrdemo
-
- CREATE EXTENSION btree_gist;
- CREATE EXTENSION bdr;
- </programlisting>
- <para>
- Then you run a function that identifies a &bdr; group that delineates a connection string for other nodes to communicate with (for the first node, we will use port 5598) from the same SQL session as above on port 5598:
- </para>
- <programlisting>
- SELECT bdr.bdr_group_create(
- local_node_name := 'node1',
- node_external_dsn := 'port=5598 dbname=bdrdemo'
-);
- </programlisting>
- <para>
- To ensure that the node is ready to replicate, run this function from the same SQL session as above on port 5598:
- </para>
- <programlisting>
- SELECT bdr.bdr_node_join_wait_for_ready();
- </programlisting>
- <para>
- On the second node/instance on port 5599 in database <quote>bdrdemo</quote> as postgreSQL superuser, create the extensions necessary for &bdr;:
- </para>
- <programlisting>
- psql -p 5599 -U postgres bdrdemo
-
- CREATE EXTENSION btree_gist;
- CREATE EXTENSION bdr;
- </programlisting>
- <para>
- Then run a function that joins this node/instance to your &bdr; group you created above (for the second node, we will use port 5599) from the same SQL session as above on port 5599:
- </para>
- <programlisting>
- SELECT bdr.bdr_group_join(
- local_node_name := 'node2',
- node_external_dsn := 'port=5599 dbname=bdrdemo'
- join_using_dsn := 'port=5598 dbname=bdrdemo'
-);
- </programlisting>
- <para>
- To ensure that the node/instance is ready to replicate, run this function from the same SQL session as above on port 5599:
- </para>
- <programlisting>
- SELECT bdr.bdr_node_join_wait_for_ready();
- </programlisting>
-
- </sect1>
-
- <sect1 id="Testing">
- <title>Testing your BDR-enabled system</title>
- <para>
- Create a table and insert rows from your first node/instance:
- </para>
- <programlisting>
- psql -p 5598 -U postgres bdrdemo
-
- CREATE TABLE t1bdr (c1 INT, PRIMARY KEY (c1));
- INSERT INTO t1bdr VALUES (1);
- INSERT INTO t1bdr VALUES (2);
- -- you will see two rows
- SELECT * FROM t1bdr;
- </programlisting>
- <para>
- Check that the rows are there on your second node/instance. Now, delete a row:
- </para>
- <programlisting>
- psql -p 5599 -U postgres bdrdemo
-
- -- you will see two rows
- SELECT * FROM t1bdr;
- DELETE FROM t1bdr WHERE c1 = 2;
- -- you will see one row
- SELECT * FROM t1bdr;
- </programlisting>
- <para>
- Check that one row has been deleted from the first node/instance::
- </para>
- <programlisting>
- psql -p 5598 -U postgres bdrdemo
-
- -- you will see one row
- SELECT * FROM t1bdr;
- </programlisting>
-
- </sect1>
- </chapter>
- <chapter id="quickstart-install">
- <title>Installing and Configuring PostgreSQL for &bdr </title>
+<chapter id="quickstart" xreflabel="Quick-start guide">
+ <title>Quick-start guide</title>
+
+ <para>
+ This section gives a quick introduction to &bdr, including setting up a
+ sample &bdr; installation and a few simple examples to try.
+ </para>
+
+ <para>
+ These instructions are not suitable for a production install, as
+ they neglect security considerations, proper system administration
+ procedure, etc. If you're trying to set up a production &bdr;
+ install, read the rest of the &bdr; manual, starting with <xref
+ linkend="installation">.
+ </para>
+
+ <para>
+ For this Quick Start example, we are setting up a two node cluster with two
+ PostgreSQL instances on the same server. We are using the terms node and instance
+ interchangebly.
+ </para>
<para>
To try out BDR you'll need to install the BDR extension and the modified
configuration files to load BDR, and start them up.
</para>
- <sect1 id="Installing">
+ <sect1 id="quickstart-installing">
<title>Installing the patched PostgreSQL binaries</title>
<para>
Information about installing &bdr; from packages can be found in <xref linkend="installation-packages"> or installing from source
</para>
</sect1>
- <sect1 id="Instances">
+ <sect1 id="quickstart-instances">
<title>Creating BDR-enabled PostgreSQL nodes/instances</title>
<para>
Since we're creating two new PostgreSQL node/instances for this example, run:
</sect1>
- <sect1 id="Editing">
+ <sect1 id="quickstart-editing">
<title>Editing the configuration files to enable BDR</title>
<para>
</sect1>
- <sect1 id="Starting">
+ <sect1 id="quickstart-starting">
<title>Starting the BDR-enabled PostgreSQL nodes/instances</title>
<para>
</note>
</sect1>
- </chapter>
+
+ <sect1 id="quickstart-creating">
+ <title>Creating the demo databases</title>
+ <para>
+ Create the databases for this demo on each node/instance from the command line of your operating system:
+ </para>
+ <programlisting>
+ createdb -p 5598 -U postgres bdrdemo
+ createdb -p 5599 -U postgres bdrdemo
+ </programlisting>
+ </sect1>
+
+ <sect1 id="quickstart-enabling">
+ <title>Enabling BDR in SQL sessions for both of your nodes/instances</title>
+ <para>
+ On the first node/instance in database <quote>bdrdemo</quote> as postgreSQL superuser, create the extensions necessary for &bdr;:
+ </para>
+ <programlisting>
+ psql -p 5598 -U postgres bdrdemo
+
+ CREATE EXTENSION btree_gist;
+ CREATE EXTENSION bdr;
+ </programlisting>
+ <para>
+ Then you run a function that identifies a &bdr; group that delineates a connection string for other nodes to communicate with (for the first node, we will use port 5598) from the same SQL session as above on port 5598:
+ </para>
+ <programlisting>
+ SELECT bdr.bdr_group_create(
+ local_node_name := 'node1',
+ node_external_dsn := 'port=5598 dbname=bdrdemo'
+);
+ </programlisting>
+ <para>
+ To ensure that the node is ready to replicate, run this function from the same SQL session as above on port 5598:
+ </para>
+ <programlisting>
+ SELECT bdr.bdr_node_join_wait_for_ready();
+ </programlisting>
+ <para>
+ On the second node/instance on port 5599 in database <quote>bdrdemo</quote> as postgreSQL superuser, create the extensions necessary for &bdr;:
+ </para>
+ <programlisting>
+ psql -p 5599 -U postgres bdrdemo
+
+ CREATE EXTENSION btree_gist;
+ CREATE EXTENSION bdr;
+ </programlisting>
+ <para>
+ Then run a function that joins this node/instance to your &bdr; group you created above (for the second node, we will use port 5599) from the same SQL session as above on port 5599:
+ </para>
+ <programlisting>
+ SELECT bdr.bdr_group_join(
+ local_node_name := 'node2',
+ node_external_dsn := 'port=5599 dbname=bdrdemo'
+ join_using_dsn := 'port=5598 dbname=bdrdemo'
+);
+ </programlisting>
+ <para>
+ To ensure that the node/instance is ready to replicate, run this function from the same SQL session as above on port 5599:
+ </para>
+ <programlisting>
+ SELECT bdr.bdr_node_join_wait_for_ready();
+ </programlisting>
+
+ </sect1>
+
+ <sect1 id="quickstart-testing">
+ <title>Testing your BDR-enabled system</title>
+ <para>
+ Create a table and insert rows from your first node/instance:
+ </para>
+ <programlisting>
+ psql -p 5598 -U postgres bdrdemo
+
+ CREATE TABLE t1bdr (c1 INT, PRIMARY KEY (c1));
+ INSERT INTO t1bdr VALUES (1);
+ INSERT INTO t1bdr VALUES (2);
+ -- you will see two rows
+ SELECT * FROM t1bdr;
+ </programlisting>
+ <para>
+ Check that the rows are there on your second node/instance. Now, delete a row:
+ </para>
+ <programlisting>
+ psql -p 5599 -U postgres bdrdemo
+
+ -- you will see two rows
+ SELECT * FROM t1bdr;
+ DELETE FROM t1bdr WHERE c1 = 2;
+ -- you will see one row
+ SELECT * FROM t1bdr;
+ </programlisting>
+ <para>
+ Check that one row has been deleted from the first node/instance::
+ </para>
+ <programlisting>
+ psql -p 5598 -U postgres bdrdemo
+
+ -- you will see one row
+ SELECT * FROM t1bdr;
+ </programlisting>
+
+ </sect1>
+</chapter>
projects / 2ndquadrant_bdr.git / commitdiff