From aca3b510ca4b6a1c1cc35f8916d4f8d04098844e Mon Sep 17 00:00:00 2001 From: Craig Ringer Date: Wed, 18 Feb 2015 15:01:06 +1300 Subject: [PATCH] bdr: doc: Split the docs up by part/chapter like the Pg docs --- doc/bdr.sgml | 1671 +------------------------ doc/filelist.sgml | 10 + doc/install-source.sgml | 140 +++ doc/manual-ddl-replication.sgml | 870 +++++++++++++ doc/manual-distributed-sequences.sgml | 24 + doc/manual-functions.sgml | 102 ++ doc/manual-monitoring.sgml | 9 + doc/manual-node-management.sgml | 71 ++ doc/manual-overview.sgml | 51 + doc/manual-replication-sets.sgml | 11 + doc/manual-settings.sgml | 347 +++++ doc/quickstart.sgml | 28 + 12 files changed, 1672 insertions(+), 1662 deletions(-) create mode 100644 doc/install-source.sgml create mode 100644 doc/manual-ddl-replication.sgml create mode 100644 doc/manual-distributed-sequences.sgml create mode 100644 doc/manual-functions.sgml create mode 100644 doc/manual-monitoring.sgml create mode 100644 doc/manual-node-management.sgml create mode 100644 doc/manual-overview.sgml create mode 100644 doc/manual-replication-sets.sgml create mode 100644 doc/manual-settings.sgml create mode 100644 doc/quickstart.sgml diff --git a/doc/bdr.sgml b/doc/bdr.sgml index ae7a8afb20..f7253f042f 100644 --- a/doc/bdr.sgml +++ b/doc/bdr.sgml @@ -46,178 +46,11 @@ &install-packages; + &install-source; - - Installing &bdr; or &udr; from source - - - Prerequisites for installing from source - - To install either &bdr; or &udr; the prerequisites for compiling - &postgres; must be installed. These are described in &postgres;'s - documentation - on build requirements - and build requirements for documentation. - - - - On several systems the prerequisites for compiling &postgres; and - &bdr;/&udr; can be installed using simple commands. - - - - - Debian and Ubuntu: First - add the apt.postgresql.org - repository to your sources.list if you - have not already done so. Then install the pre-requisites for - building PostgreSQL with: - - sudo apt-get update - sudo apt-get build-dep postgresql-9.4 - - - - - - RHEL or CentOS 6.x or 7.x: install the appropriate repository RPM - for your system from - yum.postgresql.org. Then install the prerequisites for building - PostgreSQL with: - - 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 - - - - - - - - - - Installation of &bdr; from source - - 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. - - - - The patched PostgreSQL required for BDR can be compiled using the - normal - documented procedures. That will usually be something - like: - - cd /path/to/bdr-pg-source/ - ./configure --prefix=/path/to/install --enable-debug --enable-openssl - make -j4 -s install-world - - - - To then install &bdr; execute its configure script with the - pg_config installed by the patched PostgreSQL - in the PATH environment variable, e.g.: - - cd /path/to/bdr-plugin-source/ - PATH=/path/to/install:"$PATH" ./configure - make -j4 -s all - - - - - - Installation of &udr; from source - - Installing &udr; is simpler than installing &bdr;. It compiles - against a stock (unmodified) &postgres; 9.4 if the relevant - headers are installed. - - - - 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. - - - - If you installed from apt.postgresql.org packages on - Debian/Ubuntu then run: - - sudo apt-get install postgresql-server-dev-9.4 - - - - - - If you installed from yum.postgresql.org packages on - RHEL or CentOS then run: - - sudo yum install postgresql94-dev - - - - - - - - To compile &udr; execute its configure script with &postgres;'s - pg_config in the PATH. - - cd /path/to/bdr-plugin-source/ - PATH=/path/to/pg/install:"$PATH" ./configure - make -j16 -s all - - On Debian/Ubuntu systems pg_config is on the default - PATH so you can just run - - ./configure - - On RHEL/CentOS systems you will need to put - /usr/pgsql-9.4/bin on the - PATH, e.g.: - - PATH=/usr/pgsql-9.4/bin:$PATH ./configure - - - - - - - &bdr; Quick Start - - - - This chapter gives a quick introduction into setting up a &bdr; - installation. - - - These instructions are not suitable for a production install, as - they neglect security considerations, proper system administration - procedure, etc. If you're trying to set up a production &bdr; - install, read the rest of the &bdr; manual. - - - - - Getting Started - - - Overview - - To set up &bdr; you'll need to: ... - - - - - + &quickstart; Main Manual @@ -227,1500 +60,14 @@ - - How do &bdr; and &udr; work - - - &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. - - - 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. - - - - Differences between &bdr; and &udr; - - - 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. - - - - - Primary Usecases for &udr; - - 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. - - - 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. - - - - - Primary Usecases for &udr; - - - - - - - - Node Management - - Node Management - - - How to control and setup replication differs between &bdr; and - &udr; as the former has to establish replication in two - directions. - - - Node Management for &udr; - - The bdr.bdr_subscribe() 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. - - - 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 bdr_init_copy tool - can be used to subscribe to an existing database with all its - data. It will either take a new basebackup (by internally - invoking pg_basebackup) or use a - provided one. That basebackup will be brought online and receives - all changes that have happend since it's creation. - - Using bdr_init_copy will clone all - databases from the origin server, but only connect one database - as a subscriber. - - - - - - Node Management for &bdr; - - 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. - - - The bdr.bdr_group_create() 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 bdr.bdr_group_join() function. - - - 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 bdr_init_copy tool - can be used to subscribe to an existing database with all its - data. It will either take a new basebackup (by internally - invoking pg_basebackup) or use a - provided one. That basebackup will be brought online and receives - all changes that have happend since it's creation. - - Using bdr_init_copy will clone all - databases from the origin server, but only connect one database - as a subscriber. - - - - - - - - DDL Replication - - DDL Replication - - - - &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). - - - - 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. - - - - 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. - - - - 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 ) first. - - - - Statement specific DDL replication concerns - - - Not all commands can be replicated automatically. Some are - allowed regardless - generally ones that have affect on more - than one database -, others are disallowed. - - - - Not replicated DDL statements - - - The following DDL statements are not replicated: - - - - - CREATE DATABASE - - CREATE DATABASE - - - - - CREATE DATABASE cannot be - replicated because &bdr; - works on a per database level. - - - - - - CREATE ROLE/USER/GROUP - - CREATE ROLE - - - CREATE USER - - - CREATE GROUP - - - - - CREATE ROLE cannot be replicated - because &bdr; works on a - per database level. It is possible that a workaround - for this will be added. - - - - 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 ALTER TABLE ... - OWNER TO are replicated. - - - - - - - CREATE TABLESPACE - - CREATE TABLESPACE - - - - - CREATE TABLESPACE cannot be - replicated because &bdr; - works on a per database level. - - - - Not creating tablespaces of the same name (not - necessarily with the same location though) on all - systems can break replication when statements - like ALTER TABLE ... SET - TABLESPACE are replicated. - - - - - - - DROP DATABASE - - DROP DATABASE - - - - - DROP DATABASE cannot be - replicated because &bdr; - works on a per database level. - - - Note that a database that is configured for &bdr; cannot be - dropped while that is the case. - - - - - - DROP TABLESPACE - - DROP TABLESPACE - - - - - DROP TABLESPACE cannot be - replicated because &bdr; - works on a per database level. - - - - 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. - - - - - - - DROP ROLE/USER/GROUP - - DROP ROLE - - - DROP USER - - - DROP GROUP - - - - - DROP ROLE cannot be replicated - because &bdr; works on a - per database level. It is possible that a workaround - for this will be added. - - - - Dropping role only on some nodes can cause - problems when objects on other nodes are assigned - to roles that do not exist locally anymore. - - - - - - - ALTER ROLE/USER/GROUP - - ALTER ROLE - - - ALTER USER - - - ALTER GROUP - - - - - ALTER ROLE cannot be replicated - because &bdr; works on a - per database level. It is possible that a workaround - for this will be added. - - - Normally all commands but ALTER ROLE - ... RENAME TO ... should be safe to - execute in the sense that doing so won't cause - replication to break. - - - - Renaming a role only on some nodes can lead to - problems due to replicated DDL statmeents not - being able to execute anymore. - - - - - - - ALTER DATABASE - - ALTER DATABASE - - - - - ALTER DATABASE cannot be replicated - because &bdr; works on a - per database level. - - - In practice the primary problematic case is when trying to - change settings on a per database basis using ALTER - DATABASE ... SET ..., these have to be executed on - every database for now. - - - - Renaming a database can lead to the connection - information stored on some of the nodes not being - valid anymore. - - - - - - - ALTER TABLESPACE - - ALTER TABLESPACE - - - - - ALTER TABLSPACE cannot be replicated - because &bdr; works on a per - database level. It is safe to execute on the individual - nodes though. - - - - - - - - - - Prohibited DDL statements - - - - - - - CREATE TABLE AS/SELECT INTO - - CREATE TABLE AS - - - SELECT INTO - - - - - CREATE TABLE AS/SELECT INTO are - prohibited unless UNLOGGED - or UNLOGGED temporary is specified. - - - - - - CREATE TABLE ... OF TYPE - - CREATE TABLE ... OF TYPE - - - - - CREATE TABLE ... OF TYPE is prohibited - unless UNLOGGED - or UNLOGGED temporary is specified. - - - - - - CREATE TEXT SEARCH PARSER - - CREATE TEXT SEARCH PARSER - - - - - CREATE TEXT SEARCH PARSER is prohibited. - - - - - - CREATE TEXT SEARCH DICTIONARY - - CREATE TEXT SEARCH DICTIONARY - - - - - CREATE TEXT SEARCH DICTIONARY is - prohibited. - - - - - - ALTER TEXT SEARCH DICTIONARY - - ALTER TEXT SEARCH DICTIONARY - - - - - ALTER TEXT SEARCH DICTIONARY is - prohibited. - - - - - - CREATE TEXT SEARCH TEMPLATE - - CREATE TEXT SEARCH TEMPLATE - - - - - CREATE TEXT SEARCH TEMPLATE is - prohibited. - - - - - - CREATE TEXT SEARCH CONFIGURATION - - CREATE TEXT SEARCH CONFIGURATION - - - - - CREATE TEXT SEARCH template is - prohibited. - - - - - - ALTER TEXT SEARCH CONFIGURATION - - ALTER TEXT SEARCH CONFIGURATION - - - - - ALTER TEXT SEARCH template is prohibited. - - - - - - CREATE COLLATION - - CREATE COLLATION - - - - - CREATE CREATE COLLATION is prohibited. - - - - - - ALTER EXTENSION - - ALTER INDEX - - - - - ALTER EXTENSION currently is prohibited. - - - - - - CREATE FOREIGN DATA WRAPPER - - CREATE FOREIGN DATA WRAPPER - - - - - CREATE FOREIGN DATA WRAPPER currently is prohibited. - - - - - - ALTER FOREIGN DATA WRAPPER - - ALTER FOREIGN DATA WRAPPER - - - - - ALTER FOREIGN DATA WRAPPER currently is - prohibited. - - - - - - CREATE SERVER - - CREATE SERVER - - - - - CREATE SERVER currently is prohibited. - - - - - - ALTER SERVER - - ALTER SERVER - - - - - ALTER SERVER currently is - prohibited. - - - - - - CREATE USER MAPPING - - CREATE USER MAPPING - - - - - CREATE USER MAPPING currently is prohibited. - - - - - - ALTER USER MAPPING - - ALTER USER MAPPING - - - - - ALTER USER MAPPING currently is - prohibited. - - - - - - DROP USER MAPPING - - DROP USER MAPPING - - - - - DROP USER MAPPING currently is - prohibited. - - - - - - REFRESH MATERIALIZED VIEW - - REFRESH MATERIALIZED VIEW - - - - - REFRESH MATERIALIZED VIEW currently is - prohibited. - - - - - - CREATE LANGUAGE - - CREATE LANGUAGE - - - - - CREATE LANGUAGE currently is - prohibited. Note that nearly all procedual languages are - available as an extension and CREATE - EXTENSION is supported. - - - - - - CREATE CONVERSION - - CREATE CONVERSION - - - - - CREATE CONVERSION currently is - prohibited. - - - - - - CREATE CAST - - CREATE CAST - - - - - - CREATE CAST currently is prohibited. Note - that CREATE CAST inside an extension is - supported. - - - - - - - CREATE OPERATOR FAMILY - - CREATE OPERATOR FAMILY - - - - - - CREATE OPERATOR FAMILY currently is prohibited. Note - that CREATE OPERATOR FAMILY inside an extension is - supported. - - - - - - - ALTER OPERATOR FAMILY - - ALTER OPERATOR FAMILY - - - - - ALTER OPERATOR FAMILY currently is - prohibited. - - Note that ALTER OPERATOR FAMILY inside an extension is supported. - - - - - - - CREATE OPERATOR CLASS - - CREATE OPERATOR CLASS - - - - - CREATE OPERATOR CLASS currently is - prohibited. - - Note that CREATE OPERATOR CLASS inside - an extension is supported. - - - - - - - DROP OWNED - - DROP OWNED - - - - - DROP OWNED is prohibited. - - - - - - SECURITY LABEL - - SECURITY LABEL - - - - - Except for some &bdr; internal use SECURITY - LABEL is prohibited. - - - - - - - - - - DDL statements with restrictions - - - Generally unsupported statements are prevented from being - executed, raising a 0A000/feature_not_supported error. - - - - - CREATE TABLE - - CREATE TABLE - - - - - Generally CREATE TABLE is allowed. There - are a few options/subcommands that are not supported. - - Not supported commands are: - - - - WITH OIDS - outdated option, not deemed worth to add support for - - - - - - OF TYPE - not supported yet - - - - - - CONSTRAINT ... EXCLUDE - not supported yet - - - - - - - - - - ALTER TABLE - - ALTER TABLE - - - - - Generally ALTER TABLE commands are - allowed. There are a however several subcommands that are - not supported. - - Not supported commands are: - - - - ADD COLUMN ... DEFAULT - this option - can unfortunately not be supported. It is however often - possible to rewrite this into several, supported, - commands: - - BEGIN; - ALTER TABLE mtab ADD COLUMN newcol; - UPDATE mtab SET newcol = default_value; - ALTER TABLE mtab ALTER COLUMN newcal SET DEFAULT default_value; - - If preexisiting rows do not need the default value, the - UPDATE can obviously be avoided. In that case doing - separate ADD COLUMN and ALTER - COLUMN ... SET DEFAULT commands are - advantageous anyway as they don't rewrite the whole - table. - - - - - - ADD CONSTRAINT ... EXCLUDE - exclusion - are not supported for now. - - - - - - ALTER CONSTRAINT - changing constraint - settings is not supported for now. - - - - - - ALTER COLUMN ... TYPE - 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. - - - - - - ENABLE .. RULE - is not supported. - - - - - - DISABLE .. RULE - is not supported. - - - - - - [NO] INHERIT - is not supported. - - - - - - [NOT] OF TYPE - is not supported. - - - - - - ALTER COLUMN ... SET (..) - is not - supported at the moment. - - - - - - SET (..) - is not supported at the - moment. - - - - - - - - - - - CREATE INDEX - - CREATE INDEX - - - - - Generally CREATE INDEX is supported, - but CREATE UNIQUE INDEX ... WHERE, - i.e. partial unique indexecs are not allowed. - - - - - - CREATE SEQUENCE - - CREATE SEQUENCE - - - - - Generally CREATE SEQUENCE is supported, - but when using &bdr;'s distributed sequences, some options - are prohibited. - - - - - - ALTER SEQUENCE - - ALTER SEQUENCE - - - - - Generally ALTER SEQUENCE is supported, - but when using &bdr;'s distributed sequences, some options - like START are prohibited. Several of - them, like the aforementioned START can - be specified during CREATE SEQUENCE. - - - - - - - - - - - - - Replication Sets - - Replication Sets - - - 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. - - - - - - - Distributed Sequences - - Distributed Sequences - - - 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. - - - - &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 USING bdr - option when creating a sequence. - - - - - Monitoring - - Monitoring - - - Monitoring replication setups is important. - - - - - Configuration Settings - - - Configuration Settings - of the server - - - - Prerequisite postgres parameters - - - &bdr; and &udr; require a couple of postgres settings to be set to - specific values. - - - - - - - max_worker_processes (integer) - - max_worker_processes configuration parameter - - - - - 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. - - - For more detailed information about this parameter consult - the &postgres; - documentation. - - - - - - max_replication_slots (integer) - - max_replication_slots configuration parameter - - - - - For both &bdr; - and &udr; this needs to be set big - enough so that every connection to this node has a free - replication slot. - - - For more detailed information about this parameter consult - the &postgres; - documentation. - - - - - - max_wal_senders (integer) - - max_wal_senders configuration parameter - - - - - 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. - - - If a node also does streaming base backups and/or base - backups using pg_basebackup, the - value needs to be big enough to accomodate both that - and &bdr;/&udr;. - - - - For more detailed information about this parameter consult - the &postgres; - documentation. - - - - - - shared_preload_libraries (string) - - shared_preload_libraries configuration parameter - - - - - For both &bdr; - and &udr; this parameter has to to - include bdr as one of the comma separated - values. The parameter can only be changed at server start. - - - For more detailed information about this parameter consult - the &postgres; - documentation. - - - - - - track_commit_timestamp (bool) - - track_commit_timestamp configuration parameter - - - - - To use &bdr; this parameter has to - be set to true, it can - be false - for &udr; - - - - - - wal_level (enum) - - wal_level configuration parameter - - - - - For both &bdr; - and &udr; this parameter has to be - set to logical. - - - - For more detailed information about this parameter consult - the &postgres; - documentation. - - - - - - - - - - &bdr;/&bdr; specific configuration variables - - - - - - - bdr.conflict_logging_include_tuples (boolean) - - bdr.conflict_logging_include_tuples configuration parameter - - - - - Log whole tuples when logging &bdr; - tuples. - - - - - - bdr.log_conflicts_to_table (boolean) - - bdr.log_conflicts_to_table configuration parameter - - - - - This boolean option controls whether - detected &bdr; conflicts get logged - to the bdr.bdr_conflict_history table. See Conflict logging - for details. - - - - - - bdr.synchronous_commit (boolean) - - bdr.synchronous_commit configuration parameter - - - - - This boolean option controls whether - the synchronous_commit setting - in &bdr;/&udr; - apply workers is enabled. It defaults - to off. If set to off, - &bdr; apply workers will perform - asynchronous commits, - allowing &postgres; to - considerably improve throughput. - - - 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 on and - configure &postgres;'s synchronous - replication. - - - Using synchronous replication in combination - with bdr.synchronous_commit 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 WAL is flushed - on the receiving side. - - - - - - bdr.temp_dump_directory (string) - - bdr.temp_dump_directory configuration parameter - - - - - 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. - - - Only used during initial bringup. - - - - - - - - - - Less common or internal configuration variables - - - - - bdr.default_apply_delay (integer) - - bdr.default_apply_delay configuration parameter - - - - - Sets a default apply delay for all configured connections - that don't have a explicitly configured apply delay. - - - This is primarily useful to simulate a high latency network - in a low latency testing environment. - - - - - - bdr.skip_ddl_locking (boolean) - - bdr.skip_ddl_locking configuration parameter - - - - - 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. - - - - Inconsiderate usage of this option easily allows to break - replication setups. - - - - - - - bdr.permit_unsafe_ddl_commands (boolean) - - bdr.permit_unsafe_ddl_commands configuration parameter - - - - - 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. - - - - Inconsiderate usage of this option easily allows to break - replication setups. - - - - - - - - bdr.skip_ddl_replication (boolean) - - bdr.skip_ddl_replication configuration parameter - - - - - 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. - - - - Inconsiderate usage of this option easily allows to break - replication setups. - - - - - - - - - - - - - Functions - - Functions - - - - Node management functions - - The following functions exist to manage nodes: - - - Node management functions - - - - &udr;/&bdr; - Function - Return Type - Description - - - - - - &udr; - - - bdr.bdr_subscribe_node - - bdr.bdr_subscribe_node(local_node_name, subscribe_to_dsn, node_local_dsn, apply_delay integer DEFAULT NULL, replication_sets text[] DEFAULT ARRAY['default']) - - void - Subscribes to changes made on another node - - - - &bdr; - - - bdr.bdr_group_create - - bdr.bdr_group_create(local_node_name, node_external_dsn, node_local_dsn DEFAULT NULL, apply_delay integer DEFAULT NULL, replication_sets text[] DEFAULT ARRAY['default']) - - void - - Create the first node in a future cluster of bdr nodes. - - - - - &bdr; - - - bdr.bdr_group_join - - bdr.bdr_group_join(local_node_name, node_external_dsn, join_using_dsn, node_local_dsn DEFAULT NULL, apply_delay integer DEFAULT NULL, replication_sets text[] DEFAULT ARRAY['default']) - - void - - Join this database to a cluster of existing bdr nodes. This - will initiate connections to and from all nother nodes. - - - - - &bdr; - - - bdr.bdr_part_by_node_names - - bdr.bdr_part_by_node_names(p_nodes text[]) - - void - - 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. - - - - - &bdr;/&udr; - - - bdr.bdr_node_join_wait_for_ready - - bdr.bdr_node_join_wait_for_ready() - - void - - Wait till all in-progress node joins have completed. - - - - - -
+ &manual-overview; + &manual-node-management; + &manual-ddl-replication; + &manual-replication-sets; + &manual-monitoring; + &manual-settings; + &manual-functions; - - - diff --git a/doc/filelist.sgml b/doc/filelist.sgml index 78d313818e..3379c93307 100644 --- a/doc/filelist.sgml +++ b/doc/filelist.sgml @@ -30,3 +30,13 @@ Include external documentation sections --> + + + + + + + + + + diff --git a/doc/install-source.sgml b/doc/install-source.sgml new file mode 100644 index 0000000000..8d3995ff8f --- /dev/null +++ b/doc/install-source.sgml @@ -0,0 +1,140 @@ + + Installing &bdr; or &udr; from source + + + Prerequisites for installing from source + + To install either &bdr; or &udr; the prerequisites for compiling + &postgres; must be installed. These are described in &postgres;'s + documentation + on build requirements + and build requirements for documentation. + + + + On several systems the prerequisites for compiling &postgres; and + &bdr;/&udr; can be installed using simple commands. + + + + + Debian and Ubuntu: First + add the apt.postgresql.org + repository to your sources.list if you + have not already done so. Then install the pre-requisites for + building PostgreSQL with: + + sudo apt-get update + sudo apt-get build-dep postgresql-9.4 + + + + + + RHEL or CentOS 6.x or 7.x: install the appropriate repository RPM + for your system from + yum.postgresql.org. Then install the prerequisites for building + PostgreSQL with: + + 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 + + + + + + + + + + Installation of &bdr; from source + + 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. + + + + The patched PostgreSQL required for BDR can be compiled using the + normal + documented procedures. That will usually be something + like: + + cd /path/to/bdr-pg-source/ + ./configure --prefix=/path/to/install --enable-debug --enable-openssl + make -j4 -s install-world + + + + To then install &bdr; execute its configure script with the + pg_config installed by the patched PostgreSQL + in the PATH environment variable, e.g.: + + cd /path/to/bdr-plugin-source/ + PATH=/path/to/install:"$PATH" ./configure + make -j4 -s all + + + + + + Installation of &udr; from source + + Installing &udr; is simpler than installing &bdr;. It compiles + against a stock (unmodified) &postgres; 9.4 if the relevant + headers are installed. + + + + 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. + + + + If you installed from apt.postgresql.org packages on + Debian/Ubuntu then run: + + sudo apt-get install postgresql-server-dev-9.4 + + + + + + If you installed from yum.postgresql.org packages on + RHEL or CentOS then run: + + sudo yum install postgresql94-dev + + + + + + + + To compile &udr; execute its configure script with &postgres;'s + pg_config in the PATH. + + cd /path/to/bdr-plugin-source/ + PATH=/path/to/pg/install:"$PATH" ./configure + make -j16 -s all + + On Debian/Ubuntu systems pg_config is on the default + PATH so you can just run + + ./configure + + On RHEL/CentOS systems you will need to put + /usr/pgsql-9.4/bin on the + PATH, e.g.: + + PATH=/usr/pgsql-9.4/bin:$PATH ./configure + + + + + diff --git a/doc/manual-ddl-replication.sgml b/doc/manual-ddl-replication.sgml new file mode 100644 index 0000000000..27592ffedf --- /dev/null +++ b/doc/manual-ddl-replication.sgml @@ -0,0 +1,870 @@ + + DDL Replication + + DDL Replication + + + + &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). + + + + 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. + + + + 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. + + + + 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 ) first. + + + + Statement specific DDL replication concerns + + + Not all commands can be replicated automatically. Some are + allowed regardless - generally ones that have affect on more + than one database -, others are disallowed. + + + + Not replicated DDL statements + + + The following DDL statements are not replicated: + + + + + CREATE DATABASE + + CREATE DATABASE + + + + + CREATE DATABASE cannot be + replicated because &bdr; + works on a per database level. + + + + + + CREATE ROLE/USER/GROUP + + CREATE ROLE + + + CREATE USER + + + CREATE GROUP + + + + + CREATE ROLE cannot be replicated + because &bdr; works on a + per database level. It is possible that a workaround + for this will be added. + + + + 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 ALTER TABLE ... + OWNER TO are replicated. + + + + + + + CREATE TABLESPACE + + CREATE TABLESPACE + + + + + CREATE TABLESPACE cannot be + replicated because &bdr; + works on a per database level. + + + + Not creating tablespaces of the same name (not + necessarily with the same location though) on all + systems can break replication when statements + like ALTER TABLE ... SET + TABLESPACE are replicated. + + + + + + + DROP DATABASE + + DROP DATABASE + + + + + DROP DATABASE cannot be + replicated because &bdr; + works on a per database level. + + + Note that a database that is configured for &bdr; cannot be + dropped while that is the case. + + + + + + DROP TABLESPACE + + DROP TABLESPACE + + + + + DROP TABLESPACE cannot be + replicated because &bdr; + works on a per database level. + + + + 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. + + + + + + + DROP ROLE/USER/GROUP + + DROP ROLE + + + DROP USER + + + DROP GROUP + + + + + DROP ROLE cannot be replicated + because &bdr; works on a + per database level. It is possible that a workaround + for this will be added. + + + + Dropping role only on some nodes can cause + problems when objects on other nodes are assigned + to roles that do not exist locally anymore. + + + + + + + ALTER ROLE/USER/GROUP + + ALTER ROLE + + + ALTER USER + + + ALTER GROUP + + + + + ALTER ROLE cannot be replicated + because &bdr; works on a + per database level. It is possible that a workaround + for this will be added. + + + Normally all commands but ALTER ROLE + ... RENAME TO ... should be safe to + execute in the sense that doing so won't cause + replication to break. + + + + Renaming a role only on some nodes can lead to + problems due to replicated DDL statmeents not + being able to execute anymore. + + + + + + + ALTER DATABASE + + ALTER DATABASE + + + + + ALTER DATABASE cannot be replicated + because &bdr; works on a + per database level. + + + In practice the primary problematic case is when trying to + change settings on a per database basis using ALTER + DATABASE ... SET ..., these have to be executed on + every database for now. + + + + Renaming a database can lead to the connection + information stored on some of the nodes not being + valid anymore. + + + + + + + ALTER TABLESPACE + + ALTER TABLESPACE + + + + + ALTER TABLSPACE cannot be replicated + because &bdr; works on a per + database level. It is safe to execute on the individual + nodes though. + + + + + + + + + + Prohibited DDL statements + + + + + + + CREATE TABLE AS/SELECT INTO + + CREATE TABLE AS + + + SELECT INTO + + + + + CREATE TABLE AS/SELECT INTO are + prohibited unless UNLOGGED + or UNLOGGED temporary is specified. + + + + + + CREATE TABLE ... OF TYPE + + CREATE TABLE ... OF TYPE + + + + + CREATE TABLE ... OF TYPE is prohibited + unless UNLOGGED + or UNLOGGED temporary is specified. + + + + + + CREATE TEXT SEARCH PARSER + + CREATE TEXT SEARCH PARSER + + + + + CREATE TEXT SEARCH PARSER is prohibited. + + + + + + CREATE TEXT SEARCH DICTIONARY + + CREATE TEXT SEARCH DICTIONARY + + + + + CREATE TEXT SEARCH DICTIONARY is + prohibited. + + + + + + ALTER TEXT SEARCH DICTIONARY + + ALTER TEXT SEARCH DICTIONARY + + + + + ALTER TEXT SEARCH DICTIONARY is + prohibited. + + + + + + CREATE TEXT SEARCH TEMPLATE + + CREATE TEXT SEARCH TEMPLATE + + + + + CREATE TEXT SEARCH TEMPLATE is + prohibited. + + + + + + CREATE TEXT SEARCH CONFIGURATION + + CREATE TEXT SEARCH CONFIGURATION + + + + + CREATE TEXT SEARCH template is + prohibited. + + + + + + ALTER TEXT SEARCH CONFIGURATION + + ALTER TEXT SEARCH CONFIGURATION + + + + + ALTER TEXT SEARCH template is prohibited. + + + + + + CREATE COLLATION + + CREATE COLLATION + + + + + CREATE CREATE COLLATION is prohibited. + + + + + + ALTER EXTENSION + + ALTER INDEX + + + + + ALTER EXTENSION currently is prohibited. + + + + + + CREATE FOREIGN DATA WRAPPER + + CREATE FOREIGN DATA WRAPPER + + + + + CREATE FOREIGN DATA WRAPPER currently is prohibited. + + + + + + ALTER FOREIGN DATA WRAPPER + + ALTER FOREIGN DATA WRAPPER + + + + + ALTER FOREIGN DATA WRAPPER currently is + prohibited. + + + + + + CREATE SERVER + + CREATE SERVER + + + + + CREATE SERVER currently is prohibited. + + + + + + ALTER SERVER + + ALTER SERVER + + + + + ALTER SERVER currently is + prohibited. + + + + + + CREATE USER MAPPING + + CREATE USER MAPPING + + + + + CREATE USER MAPPING currently is prohibited. + + + + + + ALTER USER MAPPING + + ALTER USER MAPPING + + + + + ALTER USER MAPPING currently is + prohibited. + + + + + + DROP USER MAPPING + + DROP USER MAPPING + + + + + DROP USER MAPPING currently is + prohibited. + + + + + + REFRESH MATERIALIZED VIEW + + REFRESH MATERIALIZED VIEW + + + + + REFRESH MATERIALIZED VIEW currently is + prohibited. + + + + + + CREATE LANGUAGE + + CREATE LANGUAGE + + + + + CREATE LANGUAGE currently is + prohibited. Note that nearly all procedual languages are + available as an extension and CREATE + EXTENSION is supported. + + + + + + CREATE CONVERSION + + CREATE CONVERSION + + + + + CREATE CONVERSION currently is + prohibited. + + + + + + CREATE CAST + + CREATE CAST + + + + + + CREATE CAST currently is prohibited. Note + that CREATE CAST inside an extension is + supported. + + + + + + + CREATE OPERATOR FAMILY + + CREATE OPERATOR FAMILY + + + + + + CREATE OPERATOR FAMILY currently is prohibited. Note + that CREATE OPERATOR FAMILY inside an extension is + supported. + + + + + + + ALTER OPERATOR FAMILY + + ALTER OPERATOR FAMILY + + + + + ALTER OPERATOR FAMILY currently is + prohibited. + + Note that ALTER OPERATOR FAMILY inside an extension is supported. + + + + + + + CREATE OPERATOR CLASS + + CREATE OPERATOR CLASS + + + + + CREATE OPERATOR CLASS currently is + prohibited. + + Note that CREATE OPERATOR CLASS inside + an extension is supported. + + + + + + + DROP OWNED + + DROP OWNED + + + + + DROP OWNED is prohibited. + + + + + + SECURITY LABEL + + SECURITY LABEL + + + + + Except for some &bdr; internal use SECURITY + LABEL is prohibited. + + + + + + + + + + DDL statements with restrictions + + + Generally unsupported statements are prevented from being + executed, raising a 0A000/feature_not_supported error. + + + + + CREATE TABLE + + CREATE TABLE + + + + + Generally CREATE TABLE is allowed. There + are a few options/subcommands that are not supported. + + Not supported commands are: + + + + WITH OIDS - outdated option, not deemed worth to add support for + + + + + + OF TYPE - not supported yet + + + + + + CONSTRAINT ... EXCLUDE - not supported yet + + + + + + + + + + ALTER TABLE + + ALTER TABLE + + + + + Generally ALTER TABLE commands are + allowed. There are a however several subcommands that are + not supported. + + Not supported commands are: + + + + ADD COLUMN ... DEFAULT - this option + can unfortunately not be supported. It is however often + possible to rewrite this into several, supported, + commands: + + BEGIN; + ALTER TABLE mtab ADD COLUMN newcol; + UPDATE mtab SET newcol = default_value; + ALTER TABLE mtab ALTER COLUMN newcal SET DEFAULT default_value; + + If preexisiting rows do not need the default value, the + UPDATE can obviously be avoided. In that case doing + separate ADD COLUMN and ALTER + COLUMN ... SET DEFAULT commands are + advantageous anyway as they don't rewrite the whole + table. + + + + + + ADD CONSTRAINT ... EXCLUDE - exclusion + are not supported for now. + + + + + + ALTER CONSTRAINT - changing constraint + settings is not supported for now. + + + + + + ALTER COLUMN ... TYPE - 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. + + + + + + ENABLE .. RULE - is not supported. + + + + + + DISABLE .. RULE - is not supported. + + + + + + [NO] INHERIT - is not supported. + + + + + + [NOT] OF TYPE - is not supported. + + + + + + ALTER COLUMN ... SET (..) - is not + supported at the moment. + + + + + + SET (..) - is not supported at the + moment. + + + + + + + + + + + CREATE INDEX + + CREATE INDEX + + + + + Generally CREATE INDEX is supported, + but CREATE UNIQUE INDEX ... WHERE, + i.e. partial unique indexecs are not allowed. + + + + + + CREATE SEQUENCE + + CREATE SEQUENCE + + + + + Generally CREATE SEQUENCE is supported, + but when using &bdr;'s distributed sequences, some options + are prohibited. + + + + + + ALTER SEQUENCE + + ALTER SEQUENCE + + + + + Generally ALTER SEQUENCE is supported, + but when using &bdr;'s distributed sequences, some options + like START are prohibited. Several of + them, like the aforementioned START can + be specified during CREATE SEQUENCE. + + + + + + + + + + diff --git a/doc/manual-distributed-sequences.sgml b/doc/manual-distributed-sequences.sgml new file mode 100644 index 0000000000..31f525d879 --- /dev/null +++ b/doc/manual-distributed-sequences.sgml @@ -0,0 +1,24 @@ + + Distributed Sequences + + Distributed Sequences + + + 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. + + + + &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 USING bdr + option when creating a sequence. + + diff --git a/doc/manual-functions.sgml b/doc/manual-functions.sgml new file mode 100644 index 0000000000..ffd29e0d84 --- /dev/null +++ b/doc/manual-functions.sgml @@ -0,0 +1,102 @@ + + Functions + + Functions + + + + Node management functions + + The following functions exist to manage nodes: + + + Node management functions + + + + &udr;/&bdr; + Function + Return Type + Description + + + + + + &udr; + + + bdr.bdr_subscribe_node + + bdr.bdr_subscribe_node(local_node_name, subscribe_to_dsn, node_local_dsn, apply_delay integer DEFAULT NULL, replication_sets text[] DEFAULT ARRAY['default']) + + void + Subscribes to changes made on another node + + + + &bdr; + + + bdr.bdr_group_create + + bdr.bdr_group_create(local_node_name, node_external_dsn, node_local_dsn DEFAULT NULL, apply_delay integer DEFAULT NULL, replication_sets text[] DEFAULT ARRAY['default']) + + void + + Create the first node in a future cluster of bdr nodes. + + + + + &bdr; + + + bdr.bdr_group_join + + bdr.bdr_group_join(local_node_name, node_external_dsn, join_using_dsn, node_local_dsn DEFAULT NULL, apply_delay integer DEFAULT NULL, replication_sets text[] DEFAULT ARRAY['default']) + + void + + Join this database to a cluster of existing bdr nodes. This + will initiate connections to and from all nother nodes. + + + + + &bdr; + + + bdr.bdr_part_by_node_names + + bdr.bdr_part_by_node_names(p_nodes text[]) + + void + + 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. + + + + + &bdr;/&udr; + + + bdr.bdr_node_join_wait_for_ready + + bdr.bdr_node_join_wait_for_ready() + + void + + Wait till all in-progress node joins have completed. + + + + + +
+ + + + diff --git a/doc/manual-monitoring.sgml b/doc/manual-monitoring.sgml new file mode 100644 index 0000000000..1b5d6ba8fa --- /dev/null +++ b/doc/manual-monitoring.sgml @@ -0,0 +1,9 @@ + + Monitoring + + Monitoring + + + Monitoring replication setups is important. + + diff --git a/doc/manual-node-management.sgml b/doc/manual-node-management.sgml new file mode 100644 index 0000000000..53e210eece --- /dev/null +++ b/doc/manual-node-management.sgml @@ -0,0 +1,71 @@ + + Node Management + + Node Management + + + How to control and setup replication differs between &bdr; and + &udr; as the former has to establish replication in two + directions. + + + Node Management for &udr; + + The bdr.bdr_subscribe() 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. + + + 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 bdr_init_copy tool + can be used to subscribe to an existing database with all its + data. It will either take a new basebackup (by internally + invoking pg_basebackup) or use a + provided one. That basebackup will be brought online and receives + all changes that have happend since it's creation. + + Using bdr_init_copy will clone all + databases from the origin server, but only connect one database + as a subscriber. + + + + + + Node Management for &bdr; + + 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. + + + The bdr.bdr_group_create() 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 bdr.bdr_group_join() function. + + + 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 bdr_init_copy tool + can be used to subscribe to an existing database with all its + data. It will either take a new basebackup (by internally + invoking pg_basebackup) or use a + provided one. That basebackup will be brought online and receives + all changes that have happend since it's creation. + + Using bdr_init_copy will clone all + databases from the origin server, but only connect one database + as a subscriber. + + + + + diff --git a/doc/manual-overview.sgml b/doc/manual-overview.sgml new file mode 100644 index 0000000000..20b8b1cdd5 --- /dev/null +++ b/doc/manual-overview.sgml @@ -0,0 +1,51 @@ + + How do &bdr; and &udr; work + + + &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. + + + 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. + + + + Differences between &bdr; and &udr; + + + 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. + + + + + Primary Usecases for &udr; + + 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. + + + 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. + + + + + Primary Usecases for &udr; + + + + + diff --git a/doc/manual-replication-sets.sgml b/doc/manual-replication-sets.sgml new file mode 100644 index 0000000000..b48388fe9c --- /dev/null +++ b/doc/manual-replication-sets.sgml @@ -0,0 +1,11 @@ + + Replication Sets + + Replication Sets + + + 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. + + diff --git a/doc/manual-settings.sgml b/doc/manual-settings.sgml new file mode 100644 index 0000000000..7f4aab9811 --- /dev/null +++ b/doc/manual-settings.sgml @@ -0,0 +1,347 @@ + + Configuration Settings + + + Configuration Settings + of the server + + + + Prerequisite postgres parameters + + + &bdr; and &udr; require a couple of postgres settings to be set to + specific values. + + + + + + + max_worker_processes (integer) + + max_worker_processes configuration parameter + + + + + 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. + + + For more detailed information about this parameter consult + the &postgres; + documentation. + + + + + + max_replication_slots (integer) + + max_replication_slots configuration parameter + + + + + For both &bdr; + and &udr; this needs to be set big + enough so that every connection to this node has a free + replication slot. + + + For more detailed information about this parameter consult + the &postgres; + documentation. + + + + + + max_wal_senders (integer) + + max_wal_senders configuration parameter + + + + + 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. + + + If a node also does streaming base backups and/or base + backups using pg_basebackup, the + value needs to be big enough to accomodate both that + and &bdr;/&udr;. + + + + For more detailed information about this parameter consult + the &postgres; + documentation. + + + + + + shared_preload_libraries (string) + + shared_preload_libraries configuration parameter + + + + + For both &bdr; + and &udr; this parameter has to to + include bdr as one of the comma separated + values. The parameter can only be changed at server start. + + + For more detailed information about this parameter consult + the &postgres; + documentation. + + + + + + track_commit_timestamp (bool) + + track_commit_timestamp configuration parameter + + + + + To use &bdr; this parameter has to + be set to true, it can + be false + for &udr; + + + + + + wal_level (enum) + + wal_level configuration parameter + + + + + For both &bdr; + and &udr; this parameter has to be + set to logical. + + + + For more detailed information about this parameter consult + the &postgres; + documentation. + + + + + + + + + + &bdr;/&bdr; specific configuration variables + + + + + + + bdr.conflict_logging_include_tuples (boolean) + + bdr.conflict_logging_include_tuples configuration parameter + + + + + Log whole tuples when logging &bdr; + tuples. + + + + + + bdr.log_conflicts_to_table (boolean) + + bdr.log_conflicts_to_table configuration parameter + + + + + This boolean option controls whether + detected &bdr; conflicts get logged + to the bdr.bdr_conflict_history table. See Conflict logging + for details. + + + + + + bdr.synchronous_commit (boolean) + + bdr.synchronous_commit configuration parameter + + + + + This boolean option controls whether + the synchronous_commit setting + in &bdr;/&udr; + apply workers is enabled. It defaults + to off. If set to off, + &bdr; apply workers will perform + asynchronous commits, + allowing &postgres; to + considerably improve throughput. + + + 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 on and + configure &postgres;'s synchronous + replication. + + + Using synchronous replication in combination + with bdr.synchronous_commit 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 WAL is flushed + on the receiving side. + + + + + + bdr.temp_dump_directory (string) + + bdr.temp_dump_directory configuration parameter + + + + + 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. + + + Only used during initial bringup. + + + + + + + + + + Less common or internal configuration variables + + + + + bdr.default_apply_delay (integer) + + bdr.default_apply_delay configuration parameter + + + + + Sets a default apply delay for all configured connections + that don't have a explicitly configured apply delay. + + + This is primarily useful to simulate a high latency network + in a low latency testing environment. + + + + + + bdr.skip_ddl_locking (boolean) + + bdr.skip_ddl_locking configuration parameter + + + + + 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. + + + + Inconsiderate usage of this option easily allows to break + replication setups. + + + + + + + bdr.permit_unsafe_ddl_commands (boolean) + + bdr.permit_unsafe_ddl_commands configuration parameter + + + + + 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. + + + + Inconsiderate usage of this option easily allows to break + replication setups. + + + + + + + + bdr.skip_ddl_replication (boolean) + + bdr.skip_ddl_replication configuration parameter + + + + + 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. + + + + Inconsiderate usage of this option easily allows to break + replication setups. + + + + + + + + + + diff --git a/doc/quickstart.sgml b/doc/quickstart.sgml new file mode 100644 index 0000000000..e067f84c20 --- /dev/null +++ b/doc/quickstart.sgml @@ -0,0 +1,28 @@ + + &bdr; Quick Start + + + + This chapter gives a quick introduction into setting up a &bdr; + installation. + + + These instructions are not suitable for a production install, as + they neglect security considerations, proper system administration + procedure, etc. If you're trying to set up a production &bdr; + install, read the rest of the &bdr; manual. + + + + + Getting Started + + + Overview + + To set up &bdr; you'll need to: ... + + + + + -- 2.39.5