</part>
- &quickstart;
+<part id="quickstart">
+ <title>Quick Start</title>
+
+ <partintro>
+ <para>
+ This section gives a quick introduction into setting up a sample &bdr;
+ installation.
+ These instructions are not suitable for a production install, as
+ they neglect security considerations, proper system administration
+ procedure, etc. If you're trying to set up a production &bdr;
+ install, read the rest of the &bdr; manual.
+ For this Quick Start example, we are setting up a two node cluster with two
+ PostgreSQL instances on the same server. We are using the terms node and instance
+ interchangebly.
+ </para>
+ </partintro>
+
+ &quickstart-install;
+ &quickstart-test;
+
+ </part>
<part id="manual">
<title>Main Manual</title>
-->
<!ENTITY install-packages SYSTEM "install-packages.sgml">
<!ENTITY install-source SYSTEM "install-source.sgml">
-<!ENTITY quickstart SYSTEM "quickstart.sgml">
+<!ENTITY quickstart-install SYSTEM "quickstart-install.sgml">
+<!ENTITY quickstart-test SYSTEM "quickstart-test.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">
--- /dev/null
+ <chapter id="quickstart-install">
+ <title>Installing and Configuring PostgreSQL for &bdr </title>
+ <sect1 id="Installing">
+ <title>Installing the patched PostgreSQL binaries</title>
+ <para>
+ The information about installing &bdr; from packages can be found in <xref linkend="installation-packages"> or installing from source
+ can be found in <xref linkend="installation-source"> .
+ </para>
+ <para>
+ When the install finishes, the script prints:
+ </para>
+ <programlisting>
+ ---------------------------
+ BDR compiled and installed.
+
+ Sources at /home/myuser/2ndquadrant_bdr/bdr-src
+ Installed to /home/myuser/2ndquadrant_bdr/bdr
+
+ Now add it to your PATH:
+ export PATH=/home/myuser/2ndquadrant_bdr/bdr/bin:$PATH
+ and carry on with the quickstart at https://wiki.postgresql.org/wiki/BDR_Quick_Start
+ ---------------------------
+ </programlisting>
+
+ <para>
+ To use these new binaries, set your path to point to them:
+ </para>
+ <programlisting>
+ export PATH=$HOME/2ndquadrant_bdr/bdr/bin:$PATH
+ </programlisting>
+ <para>
+ or, if you installed from RPMs, run:
+ </para>
+ <programlisting>
+ export PATH=/usr/pgsql-9.4/bin:$PATH
+ </programlisting>
+ <para>
+ This only affects the terminal you ran the install from and makes no permanent changes. You can change your path in your .bash_profile file so you can run the test of the demo.
+
+ </para>
+ </sect1>
+
+ <sect1 id="Instances">
+ <title>Creating BDR-enabled PostgreSQL nodes/instances</title>
+ <para>
+ Since we're creating two new PostgreSQL node/instances for this example, run:
+ </para>
+ <programlisting>
+ initdb -D $HOME/2ndquadrant_bdr/bdr5598 -A trust -U postgres
+ </programlisting>
+ <programlisting>
+ initdb -D $HOME/2ndquadrant_bdr/bdr5599 -A trust -U postgres
+ </programlisting>
+ </sect1>
+
+ <sect1 id="Editing">
+ <title>Editing the configuration files to enable BDR</title>
+ <para>
+ Edit the postgresql.conf file for both nodes/instances:
+ </para>
+ <programlisting>
+ shared_preload_libraries = 'bdr'
+ wal_level = 'logical'
+ track_commit_timestamp = on
+ max_connections = 100
+ max_wal_senders = 10
+ max_replication_slots = 10
+ # Make sure there are enough background worker slots for BDR to run
+ max_worker_processes = 10
+
+ # These aren't required, but are useful for diagnosing problems
+ #log_error_verbosity = verbose
+ #log_min_messages = debug1
+ #log_line_prefix = 'd=%d p=%p a=%a%q '
+
+ # Useful options for playing with conflicts
+ #bdr.default_apply_delay=2000 # milliseconds
+ #bdr.log_conflicts_to_table=on
+ </programlisting>
+ <para>
+ Edit or uncomment authentication parameters to allow replication in the pg_hba.conf file for both nodes/instances:
+ </para>
+ <programlisting>
+ local replication postgres trust
+ host replication postgres 127.0.0.1/32 trust
+ </programlisting>
+ </sect1>
+
+ <sect1 id="Starting">
+ <title>Starting the BDR-enabled PostgreSQL nodes/instances</title>
+ <para>
+ Start your nodes/instances from the command line of your operating system:
+ </para>
+ <programlisting>
+ pg_ctl -l $HOME/2ndquadrant_bdr/bdr5598.log -D $HOME/2ndquadrant_bdr/bdr5598 -o "-p 5598" -w start
+ pg_ctl -l $HOME/2ndquadrant_bdr/bdr5599.log -D $HOME/2ndquadrant_bdr/bdr5599 -o "-p 5599" -w start
+ </programlisting>
+ <para>
+ Each node/instance will start up and then will run in the background. You'll see the following:
+ </para>
+ <programlisting>
+ waiting for server to start.... done
+ server started
+ </programlisting>
+ <para>
+ If you see an issue with starting your nodes/instances:
+ </para>
+ <programlisting>
+ waiting for server to start........ stopped waiting
+ pg_ctl: could not start server
+ </programlisting>
+ <para>
+ Then take a look at the log files (the bdr5598.log or the bdr5599.log) depending on which one failed to start. Most likely you already have a PostgreSQL instance running on the target port.
+ These nodes/instances won't start automatically on re-boot.
+ </para>
+ </sect1>
+ </chapter>
--- /dev/null
+ <chapter id="quickstart-test">
+ <title>Enabling and Testing &bdr Demo </title>
+ <sect1 id="Creating">
+ <title>Creating the demo databases</title>
+ <para>
+ Create the databases for this demo on each node/instance from the command line of your operating system:
+ </para>
+ <programlisting>
+ createdb -p 5598 -U postgres bdrdemo
+ createdb -p 5599 -U postgres bdrdemo
+ </programlisting>
+ </sect1>
+
+ <sect1 id="Enabling">
+ <title>Enabling BDR in SQL sessions for both of your nodes/instances</title>
+ <para>
+ On the first node/instance in database <quote>bdrdemo</quote> as postgreSQL superuser, create the extensions necessary for &bdr;:
+ </para>
+ <programlisting>
+ psql -p 5598 -U postgres bdrdemo
+
+ CREATE EXTENSION btree_gist;
+ CREATE EXTENSION bdr;
+ </programlisting>
+ <para>
+ Then you run a function that identifies a &bdr; group that delineates a connection string for other nodes to communicate with (for the first node, we will use port 5598) from the same SQL session as above on port 5598:
+ </para>
+ <programlisting>
+ SELECT bdr.bdr_group_create(
+ local_node_name := 'node1',
+ node_external_dsn := 'port=5598 dbname=bdrdemo'
+);
+ </programlisting>
+ <para>
+ To ensure that the node is ready to replicate, run this function from the same SQL session as above on port 5598:
+ </para>
+ <programlisting>
+ SELECT bdr.bdr_node_join_wait_for_ready();
+ </programlisting>
+ <para>
+ On the second node/instance on port 5599 in database <quote>bdrdemo</quote> as postgreSQL superuser, create the extensions necessary for &bdr;:
+ </para>
+ <programlisting>
+ psql -p 5599 -U postgres bdrdemo
+
+ CREATE EXTENSION btree_gist;
+ CREATE EXTENSION bdr;
+ </programlisting>
+ <para>
+ Then run a function that joins this node/instance to your &bdr; group you created above (for the second node, we will use port 5599) from the same SQL session as above on port 5599:
+ </para>
+ <programlisting>
+ SELECT bdr.bdr_group_join(
+ local_node_name := 'node2',
+ node_external_dsn := 'port=5599 dbname=bdrdemo'
+ join_using_dsn := 'port=5598 dbname=bdrdemo'
+);
+ </programlisting>
+ <para>
+ To ensure that the node/instance is ready to replicate, run this function from the same SQL session as above on port 5599:
+ </para>
+ <programlisting>
+ SELECT bdr.bdr_node_join_wait_for_ready();
+ </programlisting>
+
+ </sect1>
+
+ <sect1 id="Testing">
+ <title>Testing your BDR-enabled system</title>
+ <para>
+ Create a table and insert rows from your first node/instance:
+ </para>
+ <programlisting>
+ psql -p 5598 -U postgres bdrdemo
+
+ CREATE TABLE t1bdr (c1 INT, PRIMARY KEY (c1));
+ INSERT INTO t1bdr VALUES (1);
+ INSERT INTO t1bdr VALUES (2);
+ -- you will see two rows
+ SELECT * FROM t1bdr;
+ </programlisting>
+ <para>
+ Check that the rows are there on your second node/instance. Now, delete a row:
+ </para>
+ <programlisting>
+ psql -p 5599 -U postgres bdrdemo
+
+ -- you will see two rows
+ SELECT * FROM t1bdr;
+ DELETE FROM t1bdr WHERE c1 = 2;
+ -- you will see one row
+ SELECT * FROM t1bdr;
+ </programlisting>
+ <para>
+ Check that one row has been deleted from the first node/instance::
+ </para>
+ <programlisting>
+ psql -p 5598 -U postgres bdrdemo
+
+ -- you will see one row
+ SELECT * FROM t1bdr;
+ </programlisting>
+
+ </sect1>
+ </chapter>
projects / 2ndquadrant_bdr.git / commitdiff