</partintro>
&install-packages;
+ &install-source;
- <chapter id="installation-source">
- <title>Installing &bdr; or &udr; from source</title>
-
- <sect1>
- <title>Prerequisites for installing from source</title>
- <para>
- To install either &bdr; or &udr; the prerequisites for compiling
- &postgres; must be installed. These are described in &postgres;'s
- documentation
- on <ulink url='http://www.postgresql.org/docs/current/install-requirements.html'>build requirements</ulink>
- and <ulink url='http://www.postgresql.org/docs/current/docguide-toolsets.html'>build requirements for documentation</ulink>.
- </para>
-
- <para>
- On several systems the prerequisites for compiling &postgres; and
- &bdr;/&udr; can be installed using simple commands.
-
- <itemizedlist spacing="compact" mark="bullet">
- <listitem>
- <para>
- <literal>Debian</literal> and <literal>Ubuntu</literal>: First
- add the <ulink
- url="http://apt.postgresql.org/">apt.postgresql.org</ulink>
- repository to your <filename>sources.list</filename> if you
- have not already done so. Then install the pre-requisites for
- building PostgreSQL with:
- <programlisting>
- sudo apt-get update
- sudo apt-get build-dep postgresql-9.4
- </programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>RHEL or CentOS 6.x or 7.x</literal>: install the appropriate repository RPM
- for your system from <ulink url="http://yum.postgresql.org/repopackages.php">
- yum.postgresql.org</ulink>. Then install the prerequisites for building
- PostgreSQL with:
- <programlisting>
- sudo yum check-update
- sudo yum groupinstall "Development Tools"
- sudo yum install yum-utils
- sudo yum-builddep postgresql94
- sudo yum install openjade docbook-dtds docbook-style-dsssl docbook-style-xsl
- </programlisting>
- </para>
- </listitem>
-
- </itemizedlist>
- </para>
- </sect1>
-
- <sect1 id="installation-bdr-source">
- <title>Installation of &bdr; from source</title>
- <para>
- Installing &bdr; from source consists out of two steps: First
- compile and install &postgres; with the &bdr; additions; secondly
- compile and install the &bdr; plugin.
- </para>
-
- <para>
- The patched PostgreSQL required for BDR can be compiled using the
- <ulink
- url="http://www.postgresql.org/docs/current/static/installation.html">normal
- documented procedures</ulink>. That will usually be something
- like:
- <programlisting>
- cd /path/to/bdr-pg-source/
- ./configure --prefix=/path/to/install --enable-debug --enable-openssl
- make -j4 -s install-world
- </programlisting>
- </para>
- <para>
- To then install &bdr; execute its configure script with the
- <application>pg_config</application> installed by the patched PostgreSQL
- in the <literal>PATH</literal> environment variable, e.g.:
- <programlisting>
- cd /path/to/bdr-plugin-source/
- PATH=/path/to/install:"$PATH" ./configure
- make -j4 -s all
- </programlisting>
- </para>
- </sect1>
-
- <sect1 id="installation-udr-source">
- <title>Installation of &udr; from source</title>
- <para>
- Installing &udr; is simpler than installing &bdr;. It compiles
- against a stock (unmodified) &postgres; 9.4 if the relevant
- headers are installed.
- </para>
-
- <para>
- Most Linux distributions put the required header files in a "dev"
- or "devel" package. Exactly what to install depends on how you
- installed PostgreSQL in the first place.
- <itemizedlist>
- <listitem>
- <para>
- If you installed from apt.postgresql.org packages on
- Debian/Ubuntu then run:
- <programlisting>
- sudo apt-get install postgresql-server-dev-9.4
- </programlisting>
- </para>
- </listitem>
- <listitem>
- <para>
- If you installed from yum.postgresql.org packages on
- RHEL or CentOS then run:
- <programlisting>
- sudo yum install postgresql94-dev
- </programlisting>
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para>
- To compile &udr; execute its configure script with &postgres;'s
- <application>pg_config</application> in the <literal>PATH</literal>.
- <programlisting>
- cd /path/to/bdr-plugin-source/
- PATH=/path/to/pg/install:"$PATH" ./configure
- make -j16 -s all
- </programlisting>
- On Debian/Ubuntu systems <application>pg_config</application> is on the default
- <literal>PATH</literal> so you can just run
- <programlisting>
- ./configure
- </programlisting>
- On RHEL/CentOS systems you will need to put
- <filename>/usr/pgsql-9.4/bin</filename> on the
- <literal>PATH</literal>, e.g.:
- <programlisting>
- PATH=/usr/pgsql-9.4/bin:$PATH ./configure
- </programlisting>
- </para>
- </sect1>
-
- </chapter>
</part>
- <part id="quickstart">
- <title>&bdr; Quick Start</title>
-
- <partintro>
- <para>
- This chapter gives a quick introduction into setting up a &bdr;
- installation.
- </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.
- </para>
- </partintro>
-
- <chapter id="quickstart-start">
- <title>Getting Started</title>
-
- <sect1 id="quickstart-overviev">
- <title>Overview</title>
- <para>
- To set up &bdr; you'll need to: ...
- </para>
- </sect1>
-
- </chapter>
- </part>
+ &quickstart;
<part id="manual">
<title>Main Manual</title>
</para>
</partintro>
- <chapter id="overview">
- <title>How do &bdr; and &udr; work</title>
-
- <para>
- &bdr;/&udr; use &postgres;'s logical decoding feature to implement
- a low overhead logical replication solution. This design choice
- means that individually configured replication connections will
- only ever replicate data on a database, or smaller, level. it is
- not possible to configure replication of all databases on a server.
- </para>
- <para>
- Both &bdr; and &udr; always allow temporary tables to be created
- on all nodes. There's no prohibition against doing so like it
- exists for &postgres;' builtin streaming replication feature.
- </para>
-
- <sect1>
- <title>Differences between &bdr; and &udr;</title>
-
- <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>
-
- <sect2>
- <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, because they 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>
- </sect2>
-
- <sect2>
- <title>Primary Usecases for &udr;</title>
- <para>
- </para>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="node-management">
- <title>Node Management</title>
- <indexterm>
- <primary>Node Management</primary>
- </indexterm>
- <para>
- How to control and setup replication differs between &bdr; and
- &udr; as the former has to establish replication in two
- directions.
- </para>
- <sect1>
- <title>Node Management for &udr;</title>
- <para>
- The <function>bdr.bdr_subscribe()</function> is used to receive
- changes from the database specified in the function parameters
- into the current database. Subscribing to another node using this
- function will automatically copy the existing data in that the
- database subscribed to.
- </para>
- <para>
- When subscribing to big databases (starting at tens of gigabytes)
- it can be desirable not to use a logical dump to clone the
- database. Instead a physical base backup can be used as the base
- for joining. The <application>bdr_init_copy</application> tool
- can be used to subscribe to an existing database with all its
- data. It will either take a new basebackup (by internally
- invoking <application>pg_basebackup</application>) or use a
- provided one. That basebackup will be brought online and receives
- all changes that have happend since it's creation.
- <note><para>
- Using <application>bdr_init_copy</application> will clone all
- databases from the origin server, but only connect one database
- as a subscriber.
- </para></note>
- </para>
- </sect1>
-
- <sect1>
- <title>Node Management for &bdr;</title>
- <para>
- For &bdr; every node has to have a connection to every other
- node. To make conifguration easy, every node addition
- automatically adds awareness of the new to all preexisting nodes.
- </para>
- <para>
- The <function>bdr.bdr_group_create()</function> is used on the
- first node of a bdr cluster. Doing so makes &bdr; active on that
- database and allows other nodes to join the &bdr; cluster (which
- consists out of one node at that point). Once the initial node is
- created every further node can join the &bdr; cluster using
- the <function>bdr.bdr_group_join()</function> function.
- </para>
- <para>
- When subscribing to big databases (starting at tens of gigabytes)
- it can be desirable not to use a logical dump to clone the
- database. Instead a physical base backup can be used as the base
- for joining. The <application>bdr_init_copy</application> tool
- can be used to subscribe to an existing database with all its
- data. It will either take a new basebackup (by internally
- invoking <application>pg_basebackup</application>) or use a
- provided one. That basebackup will be brought online and receives
- all changes that have happend since it's creation.
- <note><para>
- Using <application>bdr_init_copy</application> will clone all
- databases from the origin server, but only connect one database
- as a subscriber.
- </para></note>
- </para>
-
- </sect1>
- </chapter>
-
- <chapter id="ddl-replication">
- <title>DDL Replication</title>
- <indexterm>
- <primary>DDL Replication</primary>
- </indexterm>
-
- <para>
- &bdr; 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, &bdr; 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>
- <title>Statement specific DDL replication concerns</title>
-
- <para>
- Not all commands can be replicated automatically. Some are
- allowed regardless - generally ones that have affect on more
- than one database -, others are disallowed.
- </para>
-
- <sect2>
- <title>Not replicated DDL statements</title>
-
- <para>
- The following DDL statements are not replicated:
-
- <variablelist>
-
- <varlistentry id="ddl-create-database">
- <term><varname>CREATE DATABASE</varname>
- <indexterm>
- <primary><varname>CREATE DATABASE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE DATABASE</literal> cannot be
- replicated because &bdr;
- works on a per database level.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-role">
- <term><varname>CREATE ROLE/USER/GROUP</varname>
- <indexterm>
- <primary><varname>CREATE ROLE</varname></primary>
- </indexterm>
- <indexterm>
- <primary><varname>CREATE USER</varname></primary>
- </indexterm>
- <indexterm>
- <primary><varname>CREATE GROUP</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE ROLE</literal> cannot be replicated
- because &bdr; works on a
- per database level. It is possible that a workaround
- for this will be added.
- </para>
- <warning>
- <para>
- Not creating roles of the same name (not
- necessarily with the same access details otherwise
- though) on all systems can break replication when
- statements like <literal>ALTER TABLE ...
- OWNER TO</literal> are replicated.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-tablespace">
- <term><varname>CREATE TABLESPACE</varname>
- <indexterm>
- <primary><varname>CREATE TABLESPACE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE TABLESPACE</literal> cannot be
- replicated because &bdr;
- works on a per database level.
- </para>
- <warning>
- <para>
- Not creating tablespaces of the same name (not
- necessarily with the same location though) on all
- systems can break replication when statements
- like <literal>ALTER TABLE ... SET
- TABLESPACE</literal> are replicated.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-drop-database">
- <term><varname>DROP DATABASE</varname>
- <indexterm>
- <primary><varname>DROP DATABASE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>DROP DATABASE</literal> cannot be
- replicated because &bdr;
- works on a per database level.
- </para>
- <para>
- Note that a database that is configured for &bdr; cannot be
- dropped while that is the case.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-drop-tablespace">
- <term><varname>DROP TABLESPACE</varname>
- <indexterm>
- <primary><varname>DROP TABLESPACE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>DROP TABLESPACE</literal> cannot be
- replicated because &bdr;
- works on a per database level.
- </para>
- <warning>
- <para>
- Dropping tablespaces only on some nodes can cause
- problems when relations on other nodes are moved
- into the tablespace that does not exist locally
- anymore.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-drop-role">
- <term><varname>DROP ROLE/USER/GROUP</varname>
- <indexterm>
- <primary><varname>DROP ROLE</varname></primary>
- </indexterm>
- <indexterm>
- <primary><varname>DROP USER</varname></primary>
- </indexterm>
- <indexterm>
- <primary><varname>DROP GROUP</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>DROP ROLE</literal> cannot be replicated
- because &bdr; works on a
- per database level. It is possible that a workaround
- for this will be added.
- </para>
- <warning>
- <para>
- Dropping role only on some nodes can cause
- problems when objects on other nodes are assigned
- to roles that do not exist locally anymore.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-role">
- <term><varname>ALTER ROLE/USER/GROUP</varname>
- <indexterm>
- <primary><varname>ALTER ROLE</varname></primary>
- </indexterm>
- <indexterm>
- <primary><varname>ALTER USER</varname></primary>
- </indexterm>
- <indexterm>
- <primary><varname>ALTER GROUP</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER ROLE</literal> cannot be replicated
- because &bdr; works on a
- per database level. It is possible that a workaround
- for this will be added.
- </para>
- <para>
- Normally all commands but <literal>ALTER ROLE
- ... RENAME TO ...</literal> should be safe to
- execute in the sense that doing so won't cause
- replication to break.
- </para>
- <warning>
- <para>
- Renaming a role only on some nodes can lead to
- problems due to replicated DDL statmeents not
- being able to execute anymore.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-database">
- <term><varname>ALTER DATABASE</varname>
- <indexterm>
- <primary><varname>ALTER DATABASE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER DATABASE</literal> cannot be replicated
- because &bdr; works on a
- per database level.
- </para>
- <para>
- In practice the primary problematic case is when trying to
- change settings on a per database basis using <literal>ALTER
- DATABASE ... SET ...</literal>, these have to be executed on
- every database for now.
- </para>
- <warning>
- <para>
- Renaming a database can lead to the connection
- information stored on some of the nodes not being
- valid anymore.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-tablespace">
- <term><varname>ALTER TABLESPACE</varname>
- <indexterm>
- <primary><varname>ALTER TABLESPACE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER TABLSPACE</literal> cannot be replicated
- because &bdr; works on a per
- database level. It is safe to execute on the individual
- nodes though.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- </sect2>
-
- <sect2>
- <title>Prohibited DDL statements</title>
-
- <para>
-
- <variablelist>
-
- <varlistentry id="ddl-create-table-as">
- <term><varname>CREATE TABLE AS/SELECT INTO</varname>
- <indexterm>
- <primary><varname>CREATE TABLE AS</varname></primary>
- </indexterm>
- <indexterm>
- <primary><varname>SELECT INTO</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE TABLE AS/SELECT INTO</literal> are
- prohibited unless <literal>UNLOGGED</literal>
- or <literal>UNLOGGED</literal> temporary is specified.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-table-of-type">
- <term><varname>CREATE TABLE ... OF TYPE</varname>
- <indexterm>
- <primary><varname>CREATE TABLE ... OF TYPE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE TABLE ... OF TYPE</literal> is prohibited
- unless <literal>UNLOGGED</literal>
- or <literal>UNLOGGED</literal> temporary is specified.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-text-search-parser">
- <term><varname>CREATE TEXT SEARCH PARSER</varname>
- <indexterm>
- <primary><varname>CREATE TEXT SEARCH PARSER</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE TEXT SEARCH PARSER</literal> is prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-text-search-dictionary">
- <term><varname>CREATE TEXT SEARCH DICTIONARY</varname>
- <indexterm>
- <primary><varname>CREATE TEXT SEARCH DICTIONARY</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE TEXT SEARCH DICTIONARY</literal> is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-text-search-dictionary">
- <term><varname>ALTER TEXT SEARCH DICTIONARY</varname>
- <indexterm>
- <primary><varname>ALTER TEXT SEARCH DICTIONARY</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER TEXT SEARCH DICTIONARY</literal> is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-text-search-template">
- <term><varname>CREATE TEXT SEARCH TEMPLATE</varname>
- <indexterm>
- <primary><varname>CREATE TEXT SEARCH TEMPLATE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE TEXT SEARCH TEMPLATE</literal> is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-text-search-configuration">
- <term><varname>CREATE TEXT SEARCH CONFIGURATION</varname>
- <indexterm>
- <primary><varname>CREATE TEXT SEARCH CONFIGURATION</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE TEXT SEARCH template</literal> is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-text-search-configuration">
- <term><varname>ALTER TEXT SEARCH CONFIGURATION</varname>
- <indexterm>
- <primary><varname>ALTER TEXT SEARCH CONFIGURATION</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER TEXT SEARCH template</literal> is prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-collation">
- <term><varname>CREATE COLLATION</varname>
- <indexterm>
- <primary><varname>CREATE COLLATION</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE CREATE COLLATION</literal> is prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-extension">
- <term><varname>ALTER EXTENSION</varname>
- <indexterm>
- <primary><varname>ALTER INDEX</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER EXTENSION</literal> currently is prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-foreign-data-wrapper">
- <term><varname>CREATE FOREIGN DATA WRAPPER</varname>
- <indexterm>
- <primary><varname>CREATE FOREIGN DATA WRAPPER</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE FOREIGN DATA WRAPPER</literal> currently is prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-foreign-data-wrapper">
- <term><varname>ALTER FOREIGN DATA WRAPPER</varname>
- <indexterm>
- <primary><varname>ALTER FOREIGN DATA WRAPPER</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER FOREIGN DATA WRAPPER</literal> currently is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-server">
- <term><varname>CREATE SERVER</varname>
- <indexterm>
- <primary><varname>CREATE SERVER</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE SERVER</literal> currently is prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-server">
- <term><varname>ALTER SERVER</varname>
- <indexterm>
- <primary><varname>ALTER SERVER</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER SERVER</literal> currently is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-user-mapping">
- <term><varname>CREATE USER MAPPING</varname>
- <indexterm>
- <primary><varname>CREATE USER MAPPING</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE USER MAPPING</literal> currently is prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-user-mapping">
- <term><varname>ALTER USER MAPPING</varname>
- <indexterm>
- <primary><varname>ALTER USER MAPPING</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER USER MAPPING</literal> currently is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-drop-user-mapping">
- <term><varname>DROP USER MAPPING</varname>
- <indexterm>
- <primary><varname>DROP USER MAPPING</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>DROP USER MAPPING</literal> currently is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-refresh-materialized-view">
- <term><varname>REFRESH MATERIALIZED VIEW</varname>
- <indexterm>
- <primary><varname>REFRESH MATERIALIZED VIEW</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>REFRESH MATERIALIZED VIEW</literal> currently is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-language">
- <term><varname>CREATE LANGUAGE</varname>
- <indexterm>
- <primary><varname>CREATE LANGUAGE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE LANGUAGE</literal> currently is
- prohibited. Note that nearly all procedual languages are
- available as an extension and <literal>CREATE
- EXTENSION</literal> is supported.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-conversion">
- <term><varname>CREATE CONVERSION</varname>
- <indexterm>
- <primary><varname>CREATE CONVERSION</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE CONVERSION</literal> currently is
- prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-cast">
- <term><varname>CREATE CAST</varname>
- <indexterm>
- <primary><varname>CREATE CAST</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <note><para>
- <literal>CREATE CAST</literal> currently is prohibited. Note
- that <literal>CREATE CAST</literal> inside an extension is
- supported.
- </para></note>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-operator-family">
- <term><varname>CREATE OPERATOR FAMILY</varname>
- <indexterm>
- <primary><varname>CREATE OPERATOR FAMILY</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <note><para>
- <literal>CREATE OPERATOR FAMILY</literal> currently is prohibited. Note
- that <literal>CREATE OPERATOR FAMILY</literal> inside an extension is
- supported.
- </para></note>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-operator-family">
- <term><varname>ALTER OPERATOR FAMILY</varname>
- <indexterm>
- <primary><varname>ALTER OPERATOR FAMILY</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>ALTER OPERATOR FAMILY</literal> currently is
- prohibited.
- <note><para>
- Note that <literal>ALTER OPERATOR FAMILY</literal> inside an extension is supported.
- </para></note>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-operator-class">
- <term><varname>CREATE OPERATOR CLASS</varname>
- <indexterm>
- <primary><varname>CREATE OPERATOR CLASS</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>CREATE OPERATOR CLASS</literal> currently is
- prohibited.
- <note><para>
- Note that <literal>CREATE OPERATOR CLASS</literal> inside
- an extension is supported.
- </para></note>
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-drop-owned">
- <term><varname>DROP OWNED</varname>
- <indexterm>
- <primary><varname>DROP OWNED</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- <literal>DROP OWNED</literal> is prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-security-label">
- <term><varname>SECURITY LABEL</varname>
- <indexterm>
- <primary><varname>SECURITY LABEL</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- Except for some &bdr; internal use <literal>SECURITY
- LABEL</literal> is prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- </sect2>
-
- <sect2>
- <title>DDL statements with restrictions</title>
-
- <para>
- Generally unsupported statements are prevented from being
- executed, raising a 0A000/feature_not_supported error.
-
- <variablelist>
-
- <varlistentry id="ddl-create-table">
- <term><varname>CREATE TABLE</varname>
- <indexterm>
- <primary><varname>CREATE TABLE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- Generally <literal>CREATE TABLE</literal> is allowed. There
- are a few options/subcommands that are not supported.
-
- Not supported commands are:
- <itemizedlist spacing="compact" mark="bullet">
- <listitem>
- <para>
- <literal>WITH OIDS</literal> - outdated option, not deemed worth to add support for
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>OF TYPE</literal> - not supported yet
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>CONSTRAINT ... EXCLUDE</literal> - not supported yet
- </para>
- </listitem>
- </itemizedlist>
-
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-table">
- <term><varname>ALTER TABLE</varname>
- <indexterm>
- <primary><varname>ALTER TABLE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- Generally <literal>ALTER TABLE</literal> commands are
- allowed. There are a however several subcommands that are
- not supported.
-
- Not supported commands are:
- <itemizedlist spacing="compact" mark="bullet">
- <listitem>
- <para>
- <literal>ADD COLUMN ... DEFAULT</literal> - this option
- can unfortunately not be supported. It is however often
- possible to rewrite this into several, supported,
- commands:
- <programlisting>
- BEGIN;
- ALTER TABLE mtab ADD COLUMN newcol;
- UPDATE mtab SET newcol = default_value;
- ALTER TABLE mtab ALTER COLUMN newcal SET DEFAULT default_value;
- </programlisting>
- If preexisiting rows do not need the default value, the
- UPDATE can obviously be avoided. In that case doing
- separate <literal>ADD COLUMN</literal> and <literal>ALTER
- COLUMN ... SET DEFAULT</literal> commands are
- advantageous anyway as they don't rewrite the whole
- table.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>ADD CONSTRAINT ... EXCLUDE</literal> - exclusion
- are not supported for now.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>ALTER CONSTRAINT</literal> - changing constraint
- settings is not supported for now.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>ALTER COLUMN ... TYPE</literal> - changing a
- column's type is not supported. Chaning a column in a way
- that doesn't require table rewrites may be suppported at
- some point.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>ENABLE .. RULE</literal> - is not supported.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>DISABLE .. RULE</literal> - is not supported.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>[NO] INHERIT</literal> - is not supported.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>[NOT] OF TYPE</literal> - is not supported.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>ALTER COLUMN ... SET (..)</literal> - is not
- supported at the moment.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>SET (..)</literal> - is not supported at the
- moment.
- </para>
- </listitem>
-
- </itemizedlist>
-
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-index">
- <term><varname>CREATE INDEX</varname>
- <indexterm>
- <primary><varname>CREATE INDEX</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- Generally <literal>CREATE INDEX</literal> is supported,
- but <literal>CREATE UNIQUE INDEX ... WHERE</literal>,
- i.e. partial unique indexecs are not allowed.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-create-sequence">
- <term><varname>CREATE SEQUENCE</varname>
- <indexterm>
- <primary><varname>CREATE SEQUENCE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- Generally <literal>CREATE SEQUENCE</literal> is supported,
- but when using &bdr;'s distributed sequences, some options
- are prohibited.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="ddl-alter-sequence">
- <term><varname>ALTER SEQUENCE</varname>
- <indexterm>
- <primary><varname>ALTER SEQUENCE</varname></primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- Generally <literal>ALTER SEQUENCE</literal> is supported,
- but when using &bdr;'s distributed sequences, some options
- like <literal>START</literal> are prohibited. Several of
- them, like the aforementioned <literal>START</literal> can
- be specified during <literal>CREATE SEQUENCE</literal>.
- </para>
- </listitem>
- </varlistentry>
-
-
- </variablelist>
- </para>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="replication-sets">
- <title>Replication Sets</title>
- <indexterm>
- <primary>Replication Sets</primary>
- </indexterm>
- <para>
- Sometimes it is not desirable to replicate all changes that happen
- in a database. E.g. it might not be convenient and efficient to
- replicate a table containing session data.
- </para>
- </chapter>
-
-
-
- <chapter id="distributed-sequences">
- <title>Distributed Sequences</title>
- <indexterm>
- <primary>Distributed Sequences</primary>
- </indexterm>
- <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>
- &bdr; 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>
- </chapter>
-
- <chapter id="monitoring">
- <title>Monitoring</title>
- <indexterm>
- <primary>Monitoring</primary>
- </indexterm>
- <para>
- Monitoring replication setups is important.
- </para>
- </chapter>
-
- <chapter id="settings">
- <title>Configuration Settings</title>
-
- <indexterm>
- <primary>Configuration Settings</primary>
- <secondary>of the server</secondary>
- </indexterm>
-
- <sect1 id="settings-prerequisite">
- <title>Prerequisite postgres parameters</title>
-
- <para>
- &bdr; and &udr; require a couple of postgres settings to be set to
- specific values.
- </para>
-
- <para>
- <variablelist>
-
- <varlistentry id="guc-max-worker-processes" xreflabel="max_worker_processes">
- <term><varname>max_worker_processes</varname> (<type>integer</type>)
- <indexterm>
- <primary><varname>max_worker_processes</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- For both &bdr;
- and &udr; this has to be set to a big
- enough value to have one worker per configured database, and
- one worker per connection.
- </para>
- <para>
- For more detailed information about this parameter consult
- the &postgres;
- <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES'>documentation</ulink>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-max-replication-slots" xreflabel="max_replication_slots">
- <term><varname>max_replication_slots</varname> (<type>integer</type>)
- <indexterm>
- <primary><varname>max_replication_slots</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- For both &bdr;
- and &udr; this needs to be set big
- enough so that every connection to this node has a free
- replication slot.
- </para>
- <para>
- For more detailed information about this parameter consult
- the &postgres;
- <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-replication.html#GUC-MAX-REPLICATION-SLOTS'>documentation</ulink>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-max-wal-senders" xreflabel="max_wal_senders">
- <term><varname>max_wal_senders</varname> (<type>integer</type>)
- <indexterm>
- <primary><varname>max_wal_senders</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- For both &bdr;
- and &udr; this needs to be set big
- enough so that every connection to this node has a free wal
- sender process.
- </para>
- <para>
- If a node also does streaming base backups and/or base
- backups using <application>pg_basebackup</application>, the
- value needs to be big enough to accomodate both that
- and &bdr;/&udr;.
- </para>
-
- <para>
- For more detailed information about this parameter consult
- the &postgres;
- <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-replication.html#GUC-MAX-WAL-SENDERS'>documentation</ulink>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-shared-preload-libraries" xreflabel="shared_preload_libraries">
- <term><varname>shared_preload_libraries</varname> (<type>string</type>)
- <indexterm>
- <primary><varname>shared_preload_libraries</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- For both &bdr;
- and &udr; this parameter has to to
- include <literal>bdr</literal> as one of the comma separated
- values. The parameter can only be changed at server start.
- </para>
- <para>
- For more detailed information about this parameter consult
- the &postgres;
- <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES'>documentation</ulink>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-track-commit-timestamp" xreflabel="track_commit_timestamp">
- <term><varname>track_commit_timestamp</varname> (<type>bool</type>)
- <indexterm>
- <primary><varname>track_commit_timestamp</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- To use &bdr; this parameter has to
- be set to <literal>true</literal>, it can
- be <literal>false</literal>
- for &udr;
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-wal-level" xreflabel="wal_level">
- <term><varname>wal_level</varname> (<type>enum</type>)
- <indexterm>
- <primary><varname>wal_level</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- For both &bdr;
- and &udr; this parameter has to be
- set to <literal>logical</literal>.
- </para>
-
- <para>
- For more detailed information about this parameter consult
- the &postgres;
- <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-wal.html#GUC-WAL-LEVEL'>documentation</ulink>.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- </sect1>
-
- <sect1>
- <title>&bdr;/&bdr; specific configuration variables</title>
-
-
- <para>
- <variablelist>
-
- <varlistentry id="guc-bdr-conflict-logging-include-tuples" xreflabel="bdr.conflict_logging_include_tuples">
- <term><varname>bdr.conflict_logging_include_tuples</varname> (<type>boolean</type>)
- <indexterm>
- <primary><varname>bdr.conflict_logging_include_tuples</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- Log whole tuples when logging &bdr;
- tuples.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-bdr-log-conflicts-to-table" xreflabel="bdr.log_conflicts_to_table">
- <term><varname>bdr.log_conflicts_to_table</varname> (<type>boolean</type>)
- <indexterm>
- <primary><varname>bdr.log_conflicts_to_table</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- This boolean option controls whether
- detected &bdr; conflicts get logged
- to the bdr.bdr_conflict_history table. See Conflict logging
- for details. <!-- FIXME: Add link to not yet existing
- conflict logging chapter-->
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-bdr-synchronous-commit" xreflabel="bdr.synchronous_commit">
- <term><varname>bdr.synchronous_commit</varname> (<type>boolean</type>)
- <indexterm>
- <primary><varname>bdr.synchronous_commit</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- This boolean option controls whether
- the <varname>synchronous_commit</varname> setting
- in &bdr;/&udr;
- apply workers is enabled. It defaults
- to <literal>off</literal>. If set to <literal>off</literal>,
- &bdr; apply workers will perform
- asynchronous commits,
- allowing &postgres; to
- considerably improve throughput.
- </para>
- <para>
- It it always is safe to set in the sense that it'll never
- cause transactions to not be replayed. If a minimal data loss
- window is desirable it's adviseable to set it
- to <literal>on</literal> and
- configure &postgres;'s synchronous
- replication.
- </para>
- <para>
- Using synchronous replication in combination
- with <varname>bdr.synchronous_commit</varname> disabled, is
- not generally adviseable, as it will noticeably increase the
- time until a transaction is confirmed to have been
- replicated. That's because it can only be reported as having
- safely committed once the <acronym>WAL</acronym> is flushed
- on the receiving side.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-temp-dump-directory" xreflabel="bdr.temp_dump_directory">
- <term><varname>bdr.temp_dump_directory</varname> (<type>string</type>)
- <indexterm>
- <primary><varname>bdr.temp_dump_directory</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- Specifies the path to a temporary storage location, writable
- by the postgres user, that needs to have enough storage space
- to contain a complete dump of the a potentially cloned
- database.
- </para>
- <para>
- Only used during initial bringup.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- </para>
-
- <sect2>
- <title>Less common or internal configuration variables</title>
- <para>
- <variablelist>
-
- <varlistentry id="guc-bdr-default-apply-delay" xreflabel="bdr.default_apply_delay">
- <term><varname>bdr.default_apply_delay</varname> (<type>integer</type>)
- <indexterm>
- <primary><varname>bdr.default_apply_delay</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- Sets a default apply delay for all configured connections
- that don't have a explicitly configured apply delay.
- </para>
- <para>
- This is primarily useful to simulate a high latency network
- in a low latency testing environment.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-bdr-skip-ddl-locking" xreflabel="bdr.skip_ddl_locking">
- <term><varname>bdr.skip_ddl_locking</varname> (<type>boolean</type>)
- <indexterm>
- <primary><varname>bdr.skip_ddl_locking</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- For &bdr; don't acquire the global
- schema lock when executing DDL statement. This primarily is
- used internally, but can also be used in other cases. This
- option can be set at any time, but only by superusers.
- </para>
- <warning>
- <para>
- Inconsiderate usage of this option easily allows to break
- replication setups.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- <varlistentry id="guc-bdr-permit-unsafe-ddl-commands" xreflabel="bdr.permit_unsafe_ddl_commands">
- <term><varname>bdr.permit_unsafe_ddl_commands</varname> (<type>boolean</type>)
- <indexterm>
- <primary><varname>bdr.permit_unsafe_ddl_commands</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- For &bdr; allow to execute schema
- changes that cannot safely be replicated. This primarily is
- used internally, but can also be used in other cases. This
- option can be set at any time, but only by superusers.
- </para>
- <warning>
- <para>
- Inconsiderate usage of this option easily allows to break
- replication setups.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
-
- <varlistentry id="guc-bdr-skip-ddl-replication" xreflabel="bdr.skip_ddl_replication">
- <term><varname>bdr.skip_ddl_replication</varname> (<type>boolean</type>)
- <indexterm>
- <primary><varname>bdr.skip_ddl_replication</varname> configuration parameter</primary>
- </indexterm>
- </term>
- <listitem>
- <para>
- For &bdr; don't replicate schema
- changes to other systems. This is primarily useful
- for &bdr; internal use, but also can
- be used for some intentional schema changes like adding a
- index only on some nodes. This option can be set at any time,
- but only by superusers.
- </para>
- <warning>
- <para>
- Inconsiderate usage of this option easily allows to break
- replication setups.
- </para>
- </warning>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- </sect2>
- </sect1>
- </chapter>
-
- <chapter id="functions">
- <title>Functions</title>
- <indexterm>
- <primary>Functions</primary>
- </indexterm>
-
- <sect1 id="functions-node-mgmt">
- <title>Node management functions</title>
- <para>
- The following functions exist to manage nodes:
-
- <table>
- <title>Node management 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>&udr;</entry>
- <entry>
- <indexterm>
- <primary>bdr.bdr_subscribe_node</primary>
- </indexterm>
- <literal><function>bdr.bdr_subscribe_node(<replaceable>local_node_name</replaceable>, <replaceable>subscribe_to_dsn</replaceable>, <replaceable>node_local_dsn</replaceable>, <replaceable>apply_delay integer DEFAULT NULL</replaceable>, <replaceable>replication_sets text[] DEFAULT ARRAY['default']</replaceable>)</function></literal>
- </entry>
- <entry>void</entry>
- <entry>Subscribes to changes made on another node</entry>
- </row>
-
- <row>
- <entry>&bdr;</entry>
- <entry>
- <indexterm>
- <primary>bdr.bdr_group_create</primary>
- </indexterm>
- <literal><function>bdr.bdr_group_create(<replaceable>local_node_name</replaceable>, <replaceable>node_external_dsn</replaceable>, <replaceable>node_local_dsn DEFAULT NULL</replaceable>, <replaceable>apply_delay integer DEFAULT NULL</replaceable>, <replaceable>replication_sets text[] DEFAULT ARRAY['default']</replaceable>)</function></literal>
- </entry>
- <entry>void</entry>
- <entry>
- Create the first node in a future cluster of bdr nodes.
- </entry>
- </row>
-
- <row>
- <entry>&bdr;</entry>
- <entry>
- <indexterm>
- <primary>bdr.bdr_group_join</primary>
- </indexterm>
- <literal><function>bdr.bdr_group_join(<replaceable>local_node_name</replaceable>, <replaceable>node_external_dsn</replaceable>, <replaceable>join_using_dsn</replaceable>, <replaceable>node_local_dsn DEFAULT NULL</replaceable>, <replaceable>apply_delay integer DEFAULT NULL</replaceable>, <replaceable>replication_sets text[] DEFAULT ARRAY['default']</replaceable>)</function></literal>
- </entry>
- <entry>void</entry>
- <entry>
- Join this database to a cluster of existing bdr nodes. This
- will initiate connections to and from all nother nodes.
- </entry>
- </row>
-
- <row>
- <entry>&bdr;</entry>
- <entry>
- <indexterm>
- <primary>bdr.bdr_part_by_node_names</primary>
- </indexterm>
- <literal><function>bdr.bdr_part_by_node_names(<replaceable>p_nodes text[]</replaceable>)</function></literal>
- </entry>
- <entry>void</entry>
- <entry>
- Removes all the nodes - identified by the node names in the
- array. All the remaining nodes in the cluster have to be
- reachable for this to succeed.
- </entry>
- </row>
-
- <row>
- <entry>&bdr;/&udr;</entry>
- <entry>
- <indexterm>
- <primary>bdr.bdr_node_join_wait_for_ready</primary>
- </indexterm>
- <literal><function>bdr.bdr_node_join_wait_for_ready()</function></literal>
- </entry>
- <entry>void</entry>
- <entry>
- Wait till all in-progress node joins have completed.
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
+ &manual-overview;
+ &manual-node-management;
+ &manual-ddl-replication;
+ &manual-replication-sets;
+ &manual-monitoring;
+ &manual-settings;
+ &manual-functions;
- </para>
- </sect1>
- </chapter>
</part>
<![%include-index;[&bookindex;]]>
Include external documentation sections
-->
<!ENTITY install-packages SYSTEM "install-packages.sgml">
+<!ENTITY install-source SYSTEM "install-source.sgml">
+<!ENTITY quickstart SYSTEM "quickstart.sgml">
+<!ENTITY manual-overview SYSTEM "manual-overview.sgml">
+<!ENTITY manual-node-management SYSTEM "manual-node-management.sgml">
+<!ENTITY manual-ddl-replication SYSTEM "manual-ddl-replication.sgml">
+<!ENTITY manual-replication-sets SYSTEM "manual-replication-sets.sgml">
+<!ENTITY manual-distributed-sequences SYSTEM "manual-distributed-sequences.sgml">
+<!ENTITY manual-monitoring SYSTEM "manual-monitoring.sgml">
+<!ENTITY manual-settings SYSTEM "manual-settings.sgml">
+<!ENTITY manual-functions SYSTEM "manual-functions.sgml">
--- /dev/null
+<chapter id="installation-source">
+ <title>Installing &bdr; or &udr; from source</title>
+
+ <sect1>
+ <title>Prerequisites for installing from source</title>
+ <para>
+ To install either &bdr; or &udr; the prerequisites for compiling
+ &postgres; must be installed. These are described in &postgres;'s
+ documentation
+ on <ulink url='http://www.postgresql.org/docs/current/install-requirements.html'>build requirements</ulink>
+ and <ulink url='http://www.postgresql.org/docs/current/docguide-toolsets.html'>build requirements for documentation</ulink>.
+ </para>
+
+ <para>
+ On several systems the prerequisites for compiling &postgres; and
+ &bdr;/&udr; can be installed using simple commands.
+
+ <itemizedlist spacing="compact" mark="bullet">
+ <listitem>
+ <para>
+ <literal>Debian</literal> and <literal>Ubuntu</literal>: First
+ add the <ulink
+ url="http://apt.postgresql.org/">apt.postgresql.org</ulink>
+ repository to your <filename>sources.list</filename> if you
+ have not already done so. Then install the pre-requisites for
+ building PostgreSQL with:
+ <programlisting>
+ sudo apt-get update
+ sudo apt-get build-dep postgresql-9.4
+ </programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>RHEL or CentOS 6.x or 7.x</literal>: install the appropriate repository RPM
+ for your system from <ulink url="http://yum.postgresql.org/repopackages.php">
+ yum.postgresql.org</ulink>. Then install the prerequisites for building
+ PostgreSQL with:
+ <programlisting>
+ sudo yum check-update
+ sudo yum groupinstall "Development Tools"
+ sudo yum install yum-utils openjade docbook-dtds docbook-style-dsssl docbook-style-xsl
+ sudo yum-builddep postgresql94
+ </programlisting>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1 id="installation-bdr-source">
+ <title>Installation of &bdr; from source</title>
+ <para>
+ Installing &bdr; from source consists out of two steps: First
+ compile and install &postgres; with the &bdr; additions; secondly
+ compile and install the &bdr; plugin.
+ </para>
+
+ <para>
+ The patched PostgreSQL required for BDR can be compiled using the
+ <ulink
+ url="http://www.postgresql.org/docs/current/static/installation.html">normal
+ documented procedures</ulink>. That will usually be something
+ like:
+ <programlisting>
+ cd /path/to/bdr-pg-source/
+ ./configure --prefix=/path/to/install --enable-debug --enable-openssl
+ make -j4 -s install-world
+ </programlisting>
+ </para>
+ <para>
+ To then install &bdr; execute its configure script with the
+ <application>pg_config</application> installed by the patched PostgreSQL
+ in the <literal>PATH</literal> environment variable, e.g.:
+ <programlisting>
+ cd /path/to/bdr-plugin-source/
+ PATH=/path/to/install:"$PATH" ./configure
+ make -j4 -s all
+ </programlisting>
+ </para>
+ </sect1>
+
+ <sect1 id="installation-udr-source">
+ <title>Installation of &udr; from source</title>
+ <para>
+ Installing &udr; is simpler than installing &bdr;. It compiles
+ against a stock (unmodified) &postgres; 9.4 if the relevant
+ headers are installed.
+ </para>
+
+ <para>
+ Most Linux distributions put the required header files in a "dev"
+ or "devel" package. Exactly what to install depends on how you
+ installed PostgreSQL in the first place.
+ <itemizedlist>
+ <listitem>
+ <para>
+ If you installed from apt.postgresql.org packages on
+ Debian/Ubuntu then run:
+ <programlisting>
+ sudo apt-get install postgresql-server-dev-9.4
+ </programlisting>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If you installed from yum.postgresql.org packages on
+ RHEL or CentOS then run:
+ <programlisting>
+ sudo yum install postgresql94-dev
+ </programlisting>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ To compile &udr; execute its configure script with &postgres;'s
+ <application>pg_config</application> in the <literal>PATH</literal>.
+ <programlisting>
+ cd /path/to/bdr-plugin-source/
+ PATH=/path/to/pg/install:"$PATH" ./configure
+ make -j16 -s all
+ </programlisting>
+ On Debian/Ubuntu systems <application>pg_config</application> is on the default
+ <literal>PATH</literal> so you can just run
+ <programlisting>
+ ./configure
+ </programlisting>
+ On RHEL/CentOS systems you will need to put
+ <filename>/usr/pgsql-9.4/bin</filename> on the
+ <literal>PATH</literal>, e.g.:
+ <programlisting>
+ PATH=/usr/pgsql-9.4/bin:$PATH ./configure
+ </programlisting>
+ </para>
+ </sect1>
+
+</chapter>
--- /dev/null
+<chapter id="ddl-replication">
+ <title>DDL Replication</title>
+ <indexterm>
+ <primary>DDL Replication</primary>
+ </indexterm>
+
+ <para>
+ &bdr; 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, &bdr; 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>
+ <title>Statement specific DDL replication concerns</title>
+
+ <para>
+ Not all commands can be replicated automatically. Some are
+ allowed regardless - generally ones that have affect on more
+ than one database -, others are disallowed.
+ </para>
+
+ <sect2>
+ <title>Not replicated DDL statements</title>
+
+ <para>
+ The following DDL statements are not replicated:
+
+ <variablelist>
+
+ <varlistentry id="ddl-create-database">
+ <term><varname>CREATE DATABASE</varname>
+ <indexterm>
+ <primary><varname>CREATE DATABASE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE DATABASE</literal> cannot be
+ replicated because &bdr;
+ works on a per database level.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-role">
+ <term><varname>CREATE ROLE/USER/GROUP</varname>
+ <indexterm>
+ <primary><varname>CREATE ROLE</varname></primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>CREATE USER</varname></primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>CREATE GROUP</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE ROLE</literal> cannot be replicated
+ because &bdr; works on a
+ per database level. It is possible that a workaround
+ for this will be added.
+ </para>
+ <warning>
+ <para>
+ Not creating roles of the same name (not
+ necessarily with the same access details otherwise
+ though) on all systems can break replication when
+ statements like <literal>ALTER TABLE ...
+ OWNER TO</literal> are replicated.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-tablespace">
+ <term><varname>CREATE TABLESPACE</varname>
+ <indexterm>
+ <primary><varname>CREATE TABLESPACE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE TABLESPACE</literal> cannot be
+ replicated because &bdr;
+ works on a per database level.
+ </para>
+ <warning>
+ <para>
+ Not creating tablespaces of the same name (not
+ necessarily with the same location though) on all
+ systems can break replication when statements
+ like <literal>ALTER TABLE ... SET
+ TABLESPACE</literal> are replicated.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-drop-database">
+ <term><varname>DROP DATABASE</varname>
+ <indexterm>
+ <primary><varname>DROP DATABASE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>DROP DATABASE</literal> cannot be
+ replicated because &bdr;
+ works on a per database level.
+ </para>
+ <para>
+ Note that a database that is configured for &bdr; cannot be
+ dropped while that is the case.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-drop-tablespace">
+ <term><varname>DROP TABLESPACE</varname>
+ <indexterm>
+ <primary><varname>DROP TABLESPACE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>DROP TABLESPACE</literal> cannot be
+ replicated because &bdr;
+ works on a per database level.
+ </para>
+ <warning>
+ <para>
+ Dropping tablespaces only on some nodes can cause
+ problems when relations on other nodes are moved
+ into the tablespace that does not exist locally
+ anymore.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-drop-role">
+ <term><varname>DROP ROLE/USER/GROUP</varname>
+ <indexterm>
+ <primary><varname>DROP ROLE</varname></primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>DROP USER</varname></primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>DROP GROUP</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>DROP ROLE</literal> cannot be replicated
+ because &bdr; works on a
+ per database level. It is possible that a workaround
+ for this will be added.
+ </para>
+ <warning>
+ <para>
+ Dropping role only on some nodes can cause
+ problems when objects on other nodes are assigned
+ to roles that do not exist locally anymore.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-role">
+ <term><varname>ALTER ROLE/USER/GROUP</varname>
+ <indexterm>
+ <primary><varname>ALTER ROLE</varname></primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>ALTER USER</varname></primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>ALTER GROUP</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER ROLE</literal> cannot be replicated
+ because &bdr; works on a
+ per database level. It is possible that a workaround
+ for this will be added.
+ </para>
+ <para>
+ Normally all commands but <literal>ALTER ROLE
+ ... RENAME TO ...</literal> should be safe to
+ execute in the sense that doing so won't cause
+ replication to break.
+ </para>
+ <warning>
+ <para>
+ Renaming a role only on some nodes can lead to
+ problems due to replicated DDL statmeents not
+ being able to execute anymore.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-database">
+ <term><varname>ALTER DATABASE</varname>
+ <indexterm>
+ <primary><varname>ALTER DATABASE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER DATABASE</literal> cannot be replicated
+ because &bdr; works on a
+ per database level.
+ </para>
+ <para>
+ In practice the primary problematic case is when trying to
+ change settings on a per database basis using <literal>ALTER
+ DATABASE ... SET ...</literal>, these have to be executed on
+ every database for now.
+ </para>
+ <warning>
+ <para>
+ Renaming a database can lead to the connection
+ information stored on some of the nodes not being
+ valid anymore.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-tablespace">
+ <term><varname>ALTER TABLESPACE</varname>
+ <indexterm>
+ <primary><varname>ALTER TABLESPACE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER TABLSPACE</literal> cannot be replicated
+ because &bdr; works on a per
+ database level. It is safe to execute on the individual
+ nodes though.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Prohibited DDL statements</title>
+
+ <para>
+
+ <variablelist>
+
+ <varlistentry id="ddl-create-table-as">
+ <term><varname>CREATE TABLE AS/SELECT INTO</varname>
+ <indexterm>
+ <primary><varname>CREATE TABLE AS</varname></primary>
+ </indexterm>
+ <indexterm>
+ <primary><varname>SELECT INTO</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE TABLE AS/SELECT INTO</literal> are
+ prohibited unless <literal>UNLOGGED</literal>
+ or <literal>UNLOGGED</literal> temporary is specified.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-table-of-type">
+ <term><varname>CREATE TABLE ... OF TYPE</varname>
+ <indexterm>
+ <primary><varname>CREATE TABLE ... OF TYPE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE TABLE ... OF TYPE</literal> is prohibited
+ unless <literal>UNLOGGED</literal>
+ or <literal>UNLOGGED</literal> temporary is specified.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-text-search-parser">
+ <term><varname>CREATE TEXT SEARCH PARSER</varname>
+ <indexterm>
+ <primary><varname>CREATE TEXT SEARCH PARSER</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE TEXT SEARCH PARSER</literal> is prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-text-search-dictionary">
+ <term><varname>CREATE TEXT SEARCH DICTIONARY</varname>
+ <indexterm>
+ <primary><varname>CREATE TEXT SEARCH DICTIONARY</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE TEXT SEARCH DICTIONARY</literal> is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-text-search-dictionary">
+ <term><varname>ALTER TEXT SEARCH DICTIONARY</varname>
+ <indexterm>
+ <primary><varname>ALTER TEXT SEARCH DICTIONARY</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER TEXT SEARCH DICTIONARY</literal> is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-text-search-template">
+ <term><varname>CREATE TEXT SEARCH TEMPLATE</varname>
+ <indexterm>
+ <primary><varname>CREATE TEXT SEARCH TEMPLATE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE TEXT SEARCH TEMPLATE</literal> is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-text-search-configuration">
+ <term><varname>CREATE TEXT SEARCH CONFIGURATION</varname>
+ <indexterm>
+ <primary><varname>CREATE TEXT SEARCH CONFIGURATION</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE TEXT SEARCH template</literal> is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-text-search-configuration">
+ <term><varname>ALTER TEXT SEARCH CONFIGURATION</varname>
+ <indexterm>
+ <primary><varname>ALTER TEXT SEARCH CONFIGURATION</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER TEXT SEARCH template</literal> is prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-collation">
+ <term><varname>CREATE COLLATION</varname>
+ <indexterm>
+ <primary><varname>CREATE COLLATION</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE CREATE COLLATION</literal> is prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-extension">
+ <term><varname>ALTER EXTENSION</varname>
+ <indexterm>
+ <primary><varname>ALTER INDEX</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER EXTENSION</literal> currently is prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-foreign-data-wrapper">
+ <term><varname>CREATE FOREIGN DATA WRAPPER</varname>
+ <indexterm>
+ <primary><varname>CREATE FOREIGN DATA WRAPPER</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE FOREIGN DATA WRAPPER</literal> currently is prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-foreign-data-wrapper">
+ <term><varname>ALTER FOREIGN DATA WRAPPER</varname>
+ <indexterm>
+ <primary><varname>ALTER FOREIGN DATA WRAPPER</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER FOREIGN DATA WRAPPER</literal> currently is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-server">
+ <term><varname>CREATE SERVER</varname>
+ <indexterm>
+ <primary><varname>CREATE SERVER</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE SERVER</literal> currently is prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-server">
+ <term><varname>ALTER SERVER</varname>
+ <indexterm>
+ <primary><varname>ALTER SERVER</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER SERVER</literal> currently is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-user-mapping">
+ <term><varname>CREATE USER MAPPING</varname>
+ <indexterm>
+ <primary><varname>CREATE USER MAPPING</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE USER MAPPING</literal> currently is prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-user-mapping">
+ <term><varname>ALTER USER MAPPING</varname>
+ <indexterm>
+ <primary><varname>ALTER USER MAPPING</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER USER MAPPING</literal> currently is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-drop-user-mapping">
+ <term><varname>DROP USER MAPPING</varname>
+ <indexterm>
+ <primary><varname>DROP USER MAPPING</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>DROP USER MAPPING</literal> currently is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-refresh-materialized-view">
+ <term><varname>REFRESH MATERIALIZED VIEW</varname>
+ <indexterm>
+ <primary><varname>REFRESH MATERIALIZED VIEW</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>REFRESH MATERIALIZED VIEW</literal> currently is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-language">
+ <term><varname>CREATE LANGUAGE</varname>
+ <indexterm>
+ <primary><varname>CREATE LANGUAGE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE LANGUAGE</literal> currently is
+ prohibited. Note that nearly all procedual languages are
+ available as an extension and <literal>CREATE
+ EXTENSION</literal> is supported.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-conversion">
+ <term><varname>CREATE CONVERSION</varname>
+ <indexterm>
+ <primary><varname>CREATE CONVERSION</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE CONVERSION</literal> currently is
+ prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-cast">
+ <term><varname>CREATE CAST</varname>
+ <indexterm>
+ <primary><varname>CREATE CAST</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <note><para>
+ <literal>CREATE CAST</literal> currently is prohibited. Note
+ that <literal>CREATE CAST</literal> inside an extension is
+ supported.
+ </para></note>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-operator-family">
+ <term><varname>CREATE OPERATOR FAMILY</varname>
+ <indexterm>
+ <primary><varname>CREATE OPERATOR FAMILY</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <note><para>
+ <literal>CREATE OPERATOR FAMILY</literal> currently is prohibited. Note
+ that <literal>CREATE OPERATOR FAMILY</literal> inside an extension is
+ supported.
+ </para></note>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-operator-family">
+ <term><varname>ALTER OPERATOR FAMILY</varname>
+ <indexterm>
+ <primary><varname>ALTER OPERATOR FAMILY</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>ALTER OPERATOR FAMILY</literal> currently is
+ prohibited.
+ <note><para>
+ Note that <literal>ALTER OPERATOR FAMILY</literal> inside an extension is supported.
+ </para></note>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-operator-class">
+ <term><varname>CREATE OPERATOR CLASS</varname>
+ <indexterm>
+ <primary><varname>CREATE OPERATOR CLASS</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>CREATE OPERATOR CLASS</literal> currently is
+ prohibited.
+ <note><para>
+ Note that <literal>CREATE OPERATOR CLASS</literal> inside
+ an extension is supported.
+ </para></note>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-drop-owned">
+ <term><varname>DROP OWNED</varname>
+ <indexterm>
+ <primary><varname>DROP OWNED</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ <literal>DROP OWNED</literal> is prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-security-label">
+ <term><varname>SECURITY LABEL</varname>
+ <indexterm>
+ <primary><varname>SECURITY LABEL</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Except for some &bdr; internal use <literal>SECURITY
+ LABEL</literal> is prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>DDL statements with restrictions</title>
+
+ <para>
+ Generally unsupported statements are prevented from being
+ executed, raising a 0A000/feature_not_supported error.
+
+ <variablelist>
+
+ <varlistentry id="ddl-create-table">
+ <term><varname>CREATE TABLE</varname>
+ <indexterm>
+ <primary><varname>CREATE TABLE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Generally <literal>CREATE TABLE</literal> is allowed. There
+ are a few options/subcommands that are not supported.
+
+ Not supported commands are:
+ <itemizedlist spacing="compact" mark="bullet">
+ <listitem>
+ <para>
+ <literal>WITH OIDS</literal> - outdated option, not deemed worth to add support for
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>OF TYPE</literal> - not supported yet
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>CONSTRAINT ... EXCLUDE</literal> - not supported yet
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-table">
+ <term><varname>ALTER TABLE</varname>
+ <indexterm>
+ <primary><varname>ALTER TABLE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Generally <literal>ALTER TABLE</literal> commands are
+ allowed. There are a however several subcommands that are
+ not supported.
+
+ Not supported commands are:
+ <itemizedlist spacing="compact" mark="bullet">
+ <listitem>
+ <para>
+ <literal>ADD COLUMN ... DEFAULT</literal> - this option
+ can unfortunately not be supported. It is however often
+ possible to rewrite this into several, supported,
+ commands:
+ <programlisting>
+ BEGIN;
+ ALTER TABLE mtab ADD COLUMN newcol;
+ UPDATE mtab SET newcol = default_value;
+ ALTER TABLE mtab ALTER COLUMN newcal SET DEFAULT default_value;
+ </programlisting>
+ If preexisiting rows do not need the default value, the
+ UPDATE can obviously be avoided. In that case doing
+ separate <literal>ADD COLUMN</literal> and <literal>ALTER
+ COLUMN ... SET DEFAULT</literal> commands are
+ advantageous anyway as they don't rewrite the whole
+ table.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>ADD CONSTRAINT ... EXCLUDE</literal> - exclusion
+ are not supported for now.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>ALTER CONSTRAINT</literal> - changing constraint
+ settings is not supported for now.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>ALTER COLUMN ... TYPE</literal> - changing a
+ column's type is not supported. Chaning a column in a way
+ that doesn't require table rewrites may be suppported at
+ some point.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>ENABLE .. RULE</literal> - is not supported.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>DISABLE .. RULE</literal> - is not supported.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>[NO] INHERIT</literal> - is not supported.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>[NOT] OF TYPE</literal> - is not supported.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>ALTER COLUMN ... SET (..)</literal> - is not
+ supported at the moment.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>SET (..)</literal> - is not supported at the
+ moment.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-index">
+ <term><varname>CREATE INDEX</varname>
+ <indexterm>
+ <primary><varname>CREATE INDEX</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Generally <literal>CREATE INDEX</literal> is supported,
+ but <literal>CREATE UNIQUE INDEX ... WHERE</literal>,
+ i.e. partial unique indexecs are not allowed.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-create-sequence">
+ <term><varname>CREATE SEQUENCE</varname>
+ <indexterm>
+ <primary><varname>CREATE SEQUENCE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Generally <literal>CREATE SEQUENCE</literal> is supported,
+ but when using &bdr;'s distributed sequences, some options
+ are prohibited.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="ddl-alter-sequence">
+ <term><varname>ALTER SEQUENCE</varname>
+ <indexterm>
+ <primary><varname>ALTER SEQUENCE</varname></primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Generally <literal>ALTER SEQUENCE</literal> is supported,
+ but when using &bdr;'s distributed sequences, some options
+ like <literal>START</literal> are prohibited. Several of
+ them, like the aforementioned <literal>START</literal> can
+ be specified during <literal>CREATE SEQUENCE</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ </variablelist>
+ </para>
+ </sect2>
+ </sect1>
+</chapter>
--- /dev/null
+<chapter id="distributed-sequences">
+ <title>Distributed Sequences</title>
+ <indexterm>
+ <primary>Distributed Sequences</primary>
+ </indexterm>
+ <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>
+ &bdr; 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>
+</chapter>
--- /dev/null
+<chapter id="functions">
+ <title>Functions</title>
+ <indexterm>
+ <primary>Functions</primary>
+ </indexterm>
+
+ <sect1 id="functions-node-mgmt">
+ <title>Node management functions</title>
+ <para>
+ The following functions exist to manage nodes:
+
+ <table>
+ <title>Node management 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>&udr;</entry>
+ <entry>
+ <indexterm>
+ <primary>bdr.bdr_subscribe_node</primary>
+ </indexterm>
+ <literal><function>bdr.bdr_subscribe_node(<replaceable>local_node_name</replaceable>, <replaceable>subscribe_to_dsn</replaceable>, <replaceable>node_local_dsn</replaceable>, <replaceable>apply_delay integer DEFAULT NULL</replaceable>, <replaceable>replication_sets text[] DEFAULT ARRAY['default']</replaceable>)</function></literal>
+ </entry>
+ <entry>void</entry>
+ <entry>Subscribes to changes made on another node</entry>
+ </row>
+
+ <row>
+ <entry>&bdr;</entry>
+ <entry>
+ <indexterm>
+ <primary>bdr.bdr_group_create</primary>
+ </indexterm>
+ <literal><function>bdr.bdr_group_create(<replaceable>local_node_name</replaceable>, <replaceable>node_external_dsn</replaceable>, <replaceable>node_local_dsn DEFAULT NULL</replaceable>, <replaceable>apply_delay integer DEFAULT NULL</replaceable>, <replaceable>replication_sets text[] DEFAULT ARRAY['default']</replaceable>)</function></literal>
+ </entry>
+ <entry>void</entry>
+ <entry>
+ Create the first node in a future cluster of bdr nodes.
+ </entry>
+ </row>
+
+ <row>
+ <entry>&bdr;</entry>
+ <entry>
+ <indexterm>
+ <primary>bdr.bdr_group_join</primary>
+ </indexterm>
+ <literal><function>bdr.bdr_group_join(<replaceable>local_node_name</replaceable>, <replaceable>node_external_dsn</replaceable>, <replaceable>join_using_dsn</replaceable>, <replaceable>node_local_dsn DEFAULT NULL</replaceable>, <replaceable>apply_delay integer DEFAULT NULL</replaceable>, <replaceable>replication_sets text[] DEFAULT ARRAY['default']</replaceable>)</function></literal>
+ </entry>
+ <entry>void</entry>
+ <entry>
+ Join this database to a cluster of existing bdr nodes. This
+ will initiate connections to and from all nother nodes.
+ </entry>
+ </row>
+
+ <row>
+ <entry>&bdr;</entry>
+ <entry>
+ <indexterm>
+ <primary>bdr.bdr_part_by_node_names</primary>
+ </indexterm>
+ <literal><function>bdr.bdr_part_by_node_names(<replaceable>p_nodes text[]</replaceable>)</function></literal>
+ </entry>
+ <entry>void</entry>
+ <entry>
+ Removes all the nodes - identified by the node names in the
+ array. All the remaining nodes in the cluster have to be
+ reachable for this to succeed.
+ </entry>
+ </row>
+
+ <row>
+ <entry>&bdr;/&udr;</entry>
+ <entry>
+ <indexterm>
+ <primary>bdr.bdr_node_join_wait_for_ready</primary>
+ </indexterm>
+ <literal><function>bdr.bdr_node_join_wait_for_ready()</function></literal>
+ </entry>
+ <entry>void</entry>
+ <entry>
+ Wait till all in-progress node joins have completed.
+ </entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+
+ </para>
+ </sect1>
+</chapter>
--- /dev/null
+<chapter id="monitoring">
+ <title>Monitoring</title>
+ <indexterm>
+ <primary>Monitoring</primary>
+ </indexterm>
+ <para>
+ Monitoring replication setups is important.
+ </para>
+</chapter>
--- /dev/null
+<chapter id="node-management">
+ <title>Node Management</title>
+ <indexterm>
+ <primary>Node Management</primary>
+ </indexterm>
+ <para>
+ How to control and setup replication differs between &bdr; and
+ &udr; as the former has to establish replication in two
+ directions.
+ </para>
+ <sect1>
+ <title>Node Management for &udr;</title>
+ <para>
+ The <function>bdr.bdr_subscribe()</function> is used to receive
+ changes from the database specified in the function parameters
+ into the current database. Subscribing to another node using this
+ function will automatically copy the existing data in that the
+ database subscribed to.
+ </para>
+ <para>
+ When subscribing to big databases (starting at tens of gigabytes)
+ it can be desirable not to use a logical dump to clone the
+ database. Instead a physical base backup can be used as the base
+ for joining. The <application>bdr_init_copy</application> tool
+ can be used to subscribe to an existing database with all its
+ data. It will either take a new basebackup (by internally
+ invoking <application>pg_basebackup</application>) or use a
+ provided one. That basebackup will be brought online and receives
+ all changes that have happend since it's creation.
+ <note><para>
+ Using <application>bdr_init_copy</application> will clone all
+ databases from the origin server, but only connect one database
+ as a subscriber.
+ </para></note>
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Node Management for &bdr;</title>
+ <para>
+ For &bdr; every node has to have a connection to every other
+ node. To make conifguration easy, every node addition
+ automatically adds awareness of the new to all preexisting nodes.
+ </para>
+ <para>
+ The <function>bdr.bdr_group_create()</function> is used on the
+ first node of a bdr cluster. Doing so makes &bdr; active on that
+ database and allows other nodes to join the &bdr; cluster (which
+ consists out of one node at that point). Once the initial node is
+ created every further node can join the &bdr; cluster using
+ the <function>bdr.bdr_group_join()</function> function.
+ </para>
+ <para>
+ When subscribing to big databases (starting at tens of gigabytes)
+ it can be desirable not to use a logical dump to clone the
+ database. Instead a physical base backup can be used as the base
+ for joining. The <application>bdr_init_copy</application> tool
+ can be used to subscribe to an existing database with all its
+ data. It will either take a new basebackup (by internally
+ invoking <application>pg_basebackup</application>) or use a
+ provided one. That basebackup will be brought online and receives
+ all changes that have happend since it's creation.
+ <note><para>
+ Using <application>bdr_init_copy</application> will clone all
+ databases from the origin server, but only connect one database
+ as a subscriber.
+ </para></note>
+ </para>
+
+ </sect1>
+</chapter>
--- /dev/null
+<chapter id="overview">
+ <title>How do &bdr; and &udr; work</title>
+
+ <para>
+ &bdr;/&udr; use &postgres;'s logical decoding feature to implement
+ a low overhead logical replication solution. This design choice
+ means that individually configured replication connections will
+ only ever replicate data on a database, or smaller, level. it is
+ not possible to configure replication of all databases on a server.
+ </para>
+ <para>
+ Both &bdr; and &udr; always allow temporary tables to be created
+ on all nodes. There's no prohibition against doing so like it
+ exists for &postgres;' builtin streaming replication feature.
+ </para>
+
+ <sect1>
+ <title>Differences between &bdr; and &udr;</title>
+
+ <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>
+
+ <sect2>
+ <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, because they 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>
+ </sect2>
+
+ <sect2>
+ <title>Primary Usecases for &udr;</title>
+ <para>
+ </para>
+ </sect2>
+ </sect1>
+</chapter>
--- /dev/null
+<chapter id="replication-sets">
+ <title>Replication Sets</title>
+ <indexterm>
+ <primary>Replication Sets</primary>
+ </indexterm>
+ <para>
+ Sometimes it is not desirable to replicate all changes that happen
+ in a database. E.g. it might not be convenient and efficient to
+ replicate a table containing session data.
+ </para>
+</chapter>
--- /dev/null
+<chapter id="settings">
+ <title>Configuration Settings</title>
+
+ <indexterm>
+ <primary>Configuration Settings</primary>
+ <secondary>of the server</secondary>
+ </indexterm>
+
+ <sect1 id="settings-prerequisite">
+ <title>Prerequisite postgres parameters</title>
+
+ <para>
+ &bdr; and &udr; require a couple of postgres settings to be set to
+ specific values.
+ </para>
+
+ <para>
+ <variablelist>
+
+ <varlistentry id="guc-max-worker-processes" xreflabel="max_worker_processes">
+ <term><varname>max_worker_processes</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>max_worker_processes</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ For both &bdr;
+ and &udr; this has to be set to a big
+ enough value to have one worker per configured database, and
+ one worker per connection.
+ </para>
+ <para>
+ For more detailed information about this parameter consult
+ the &postgres;
+ <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES'>documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-max-replication-slots" xreflabel="max_replication_slots">
+ <term><varname>max_replication_slots</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>max_replication_slots</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ For both &bdr;
+ and &udr; this needs to be set big
+ enough so that every connection to this node has a free
+ replication slot.
+ </para>
+ <para>
+ For more detailed information about this parameter consult
+ the &postgres;
+ <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-replication.html#GUC-MAX-REPLICATION-SLOTS'>documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-max-wal-senders" xreflabel="max_wal_senders">
+ <term><varname>max_wal_senders</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>max_wal_senders</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ For both &bdr;
+ and &udr; this needs to be set big
+ enough so that every connection to this node has a free wal
+ sender process.
+ </para>
+ <para>
+ If a node also does streaming base backups and/or base
+ backups using <application>pg_basebackup</application>, the
+ value needs to be big enough to accomodate both that
+ and &bdr;/&udr;.
+ </para>
+
+ <para>
+ For more detailed information about this parameter consult
+ the &postgres;
+ <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-replication.html#GUC-MAX-WAL-SENDERS'>documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-shared-preload-libraries" xreflabel="shared_preload_libraries">
+ <term><varname>shared_preload_libraries</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>shared_preload_libraries</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ For both &bdr;
+ and &udr; this parameter has to to
+ include <literal>bdr</literal> as one of the comma separated
+ values. The parameter can only be changed at server start.
+ </para>
+ <para>
+ For more detailed information about this parameter consult
+ the &postgres;
+ <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES'>documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-track-commit-timestamp" xreflabel="track_commit_timestamp">
+ <term><varname>track_commit_timestamp</varname> (<type>bool</type>)
+ <indexterm>
+ <primary><varname>track_commit_timestamp</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ To use &bdr; this parameter has to
+ be set to <literal>true</literal>, it can
+ be <literal>false</literal>
+ for &udr;
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-wal-level" xreflabel="wal_level">
+ <term><varname>wal_level</varname> (<type>enum</type>)
+ <indexterm>
+ <primary><varname>wal_level</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ For both &bdr;
+ and &udr; this parameter has to be
+ set to <literal>logical</literal>.
+ </para>
+
+ <para>
+ For more detailed information about this parameter consult
+ the &postgres;
+ <ulink url='http://www.postgresql.org/docs/current/interactive/runtime-config-wal.html#GUC-WAL-LEVEL'>documentation</ulink>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>&bdr;/&bdr; specific configuration variables</title>
+
+
+ <para>
+ <variablelist>
+
+ <varlistentry id="guc-bdr-conflict-logging-include-tuples" xreflabel="bdr.conflict_logging_include_tuples">
+ <term><varname>bdr.conflict_logging_include_tuples</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>bdr.conflict_logging_include_tuples</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Log whole tuples when logging &bdr;
+ tuples.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-bdr-log-conflicts-to-table" xreflabel="bdr.log_conflicts_to_table">
+ <term><varname>bdr.log_conflicts_to_table</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>bdr.log_conflicts_to_table</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ This boolean option controls whether
+ detected &bdr; conflicts get logged
+ to the bdr.bdr_conflict_history table. See Conflict logging
+ for details. <!-- FIXME: Add link to not yet existing
+ conflict logging chapter-->
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-bdr-synchronous-commit" xreflabel="bdr.synchronous_commit">
+ <term><varname>bdr.synchronous_commit</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>bdr.synchronous_commit</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ This boolean option controls whether
+ the <varname>synchronous_commit</varname> setting
+ in &bdr;/&udr;
+ apply workers is enabled. It defaults
+ to <literal>off</literal>. If set to <literal>off</literal>,
+ &bdr; apply workers will perform
+ asynchronous commits,
+ allowing &postgres; to
+ considerably improve throughput.
+ </para>
+ <para>
+ It it always is safe to set in the sense that it'll never
+ cause transactions to not be replayed. If a minimal data loss
+ window is desirable it's adviseable to set it
+ to <literal>on</literal> and
+ configure &postgres;'s synchronous
+ replication.
+ </para>
+ <para>
+ Using synchronous replication in combination
+ with <varname>bdr.synchronous_commit</varname> disabled, is
+ not generally adviseable, as it will noticeably increase the
+ time until a transaction is confirmed to have been
+ replicated. That's because it can only be reported as having
+ safely committed once the <acronym>WAL</acronym> is flushed
+ on the receiving side.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-temp-dump-directory" xreflabel="bdr.temp_dump_directory">
+ <term><varname>bdr.temp_dump_directory</varname> (<type>string</type>)
+ <indexterm>
+ <primary><varname>bdr.temp_dump_directory</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Specifies the path to a temporary storage location, writable
+ by the postgres user, that needs to have enough storage space
+ to contain a complete dump of the a potentially cloned
+ database.
+ </para>
+ <para>
+ Only used during initial bringup.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+
+ </para>
+
+ <sect2>
+ <title>Less common or internal configuration variables</title>
+ <para>
+ <variablelist>
+
+ <varlistentry id="guc-bdr-default-apply-delay" xreflabel="bdr.default_apply_delay">
+ <term><varname>bdr.default_apply_delay</varname> (<type>integer</type>)
+ <indexterm>
+ <primary><varname>bdr.default_apply_delay</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ Sets a default apply delay for all configured connections
+ that don't have a explicitly configured apply delay.
+ </para>
+ <para>
+ This is primarily useful to simulate a high latency network
+ in a low latency testing environment.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-bdr-skip-ddl-locking" xreflabel="bdr.skip_ddl_locking">
+ <term><varname>bdr.skip_ddl_locking</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>bdr.skip_ddl_locking</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ For &bdr; don't acquire the global
+ schema lock when executing DDL statement. This primarily is
+ used internally, but can also be used in other cases. This
+ option can be set at any time, but only by superusers.
+ </para>
+ <warning>
+ <para>
+ Inconsiderate usage of this option easily allows to break
+ replication setups.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry id="guc-bdr-permit-unsafe-ddl-commands" xreflabel="bdr.permit_unsafe_ddl_commands">
+ <term><varname>bdr.permit_unsafe_ddl_commands</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>bdr.permit_unsafe_ddl_commands</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ For &bdr; allow to execute schema
+ changes that cannot safely be replicated. This primarily is
+ used internally, but can also be used in other cases. This
+ option can be set at any time, but only by superusers.
+ </para>
+ <warning>
+ <para>
+ Inconsiderate usage of this option easily allows to break
+ replication setups.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry id="guc-bdr-skip-ddl-replication" xreflabel="bdr.skip_ddl_replication">
+ <term><varname>bdr.skip_ddl_replication</varname> (<type>boolean</type>)
+ <indexterm>
+ <primary><varname>bdr.skip_ddl_replication</varname> configuration parameter</primary>
+ </indexterm>
+ </term>
+ <listitem>
+ <para>
+ For &bdr; don't replicate schema
+ changes to other systems. This is primarily useful
+ for &bdr; internal use, but also can
+ be used for some intentional schema changes like adding a
+ index only on some nodes. This option can be set at any time,
+ but only by superusers.
+ </para>
+ <warning>
+ <para>
+ Inconsiderate usage of this option easily allows to break
+ replication setups.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </para>
+ </sect2>
+ </sect1>
+</chapter>
--- /dev/null
+<part id="quickstart">
+ <title>&bdr; Quick Start</title>
+
+ <partintro>
+ <para>
+ This chapter gives a quick introduction into setting up a &bdr;
+ installation.
+ </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.
+ </para>
+ </partintro>
+
+ <chapter id="quickstart-start">
+ <title>Getting Started</title>
+
+ <sect1 id="quickstart-overviev">
+ <title>Overview</title>
+ <para>
+ To set up &bdr; you'll need to: ...
+ </para>
+ </sect1>
+
+ </chapter>
+</part>
projects / 2ndquadrant_bdr.git / commitdiff