Merge branch 'PGPROEE10' of gitlab.postgrespro.ru:pgpro-dev/postgrespro into PGPROEE10

Author: vbwagner

doc/src/sgml/in-memory.sgml

@@ -16,23 +16,22 @@
         <para>
          Fast random access on the primary key.
          This can result in significant performance benefits when
-         working with data that has to be moved to RAM and requires
-         a very high read and write access rate,
-         especially on multi-core systems.
+         working with data that requires a very high read and write
+         access rate, especially on multi-core systems.
         </para>
       </listitem>
       <listitem>
         <para>
-         Saving disk space: there is no primary key
-         duplication as all data is stored directly in the index.
+         Effective space usage.
+         There is no primary key duplication as all data
+         is stored directly in the index.
         </para>
       </listitem>
     </itemizedlist>
   </para>
 
   <para>
-    Just like regular heap-organized tables,
-    in-memory tables support transactions, including savepoints.
+    In-memory tables support transactions, including savepoints.
     However, the data in such tables is stored only while the server is running.
     Once the server is shut down, all in-memory data gets truncated.
     When using in-memory tables, you should also take into account the following
@@ -202,20 +201,20 @@ OPTIONS (INDICES '(id, author COLLATE "ru_RU" ASC)');
      Fill the <structname>blog_views</structname>
      table with initial zero values for initial ten blog posts:
     <programlisting>
-# INSERT INTO blog_views (SELECT id, 0 FROM generate_series(1, 10) AS id);
+postgres=# INSERT INTO blog_views (SELECT id, 0 FROM generate_series(1, 10) AS id);
 </programlisting>
 </para>
 
 <para>Increment the view count for a couple of posts
 and display the result:
 <programlisting>
-# UPDATE blog_views SET views = views + 1 WHERE id = 1;
+postgres=# UPDATE blog_views SET views = views + 1 WHERE id = 1;
 UPDATE 1
-# UPDATE blog_views SET views = views + 1 WHERE id = 1;
+postgres=# UPDATE blog_views SET views = views + 1 WHERE id = 1;
 UPDATE 2
-# UPDATE blog_views SET views = views + 1 WHERE id = 2;
+postgres=# UPDATE blog_views SET views = views + 1 WHERE id = 2;
 UPDATE 1
-# SELECT * FROM blog_views WHERE id = 1 OR id = 2;
+postgres=# SELECT * FROM blog_views WHERE id = 1 OR id = 2;
  id | views
 ----+-------
   1 |  2
@@ -227,7 +226,7 @@ UPDATE 1
       Check planning and execution costs for a query that
       only requires a primary key lookup:
     <programlisting>
-# EXPLAIN ANALYZE SELECT * FROM blog_views WHERE id = 1;
+postgres=# EXPLAIN ANALYZE SELECT * FROM blog_views WHERE id = 1;
                        QUERY PLAN
 -------------------------------------------------------------------
 Foreign Scan on blog_views  (cost=0.02..0.03 rows=1 width=16)
@@ -242,7 +241,7 @@ Execution time: 0.035 ms
       Check the costs of calculating the sum of all views, which requires
       a full index scan:
     <programlisting>
-# EXPLAIN ANALYZE SELECT SUM(views) FROM blog_views;
+postgres=# EXPLAIN ANALYZE SELECT SUM(views) FROM blog_views;
                          QUERY PLAN
 --------------------------------------------------------------------
 Aggregate  (cost=1.62..1.63 rows=1 width=32)
@@ -319,7 +318,7 @@ Execution time: 0.353 ms
       as well as the total number of pages allocated for in-memory tables.
       For example:
     <screen>
-# SELECT * FROM in_memory.in_memory_page_stats();
+postgres=# SELECT * FROM in_memory.in_memory_page_stats();
  used_pages | free_pages | all_pages
 ------------+------------+-----------
         576 |       7616 |      8192

doc/src/sgml/multimaster.sgml

@@ -74,7 +74,7 @@
       <listitem>
         <para>
           <filename>multimaster</filename> can only replicate one database
-          per cluster, which is specified in the <varname>multimaster.conn_strings</varname> variable. If you connect to a different database,
+          per cluster. This database must be specified in the <varname>multimaster.conn_strings</varname> variable. If you connect to a different database,
           all operations will fail with the corresponding error message.
         </para>
       </listitem>
@@ -375,6 +375,16 @@ where <replaceable>datadir</> is the directory containing the database cluster.
       cluster node:
     </para>
     <orderedlist>
+      <listitem>
+        <para>
+          Allow replication of the <literal>mydb</literal> database
+          to each cluster node on behalf of <literal>myuser</literal>,
+          as explained in <xref linkend="auth-pg-hba-conf">.
+          Make sure to use the
+          <link linkend="auth-methods">authentication method</link> that
+          satisfies your security requirements.
+        </para>
+      </listitem>
       <listitem>
         <para>
           Modify the <filename>postgresql.conf</filename> configuration
@@ -460,7 +470,6 @@ multimaster.conn_strings = 'dbname=mydb user=myuser host=node1,dbname=mydb user=
 </para>
 <para>In most cases, three cluster nodes are enough to ensure high availability. Since the data on all cluster nodes is the same, you do not typically need more than five cluster nodes.
 </para>
-<para>If you would like to change the default connection settings for a cluster node, you can add other <link linkend="libpq-paramkeywords"> connection parameters</link> to the corresponding connection string in the <varname>multimaster.conn_strings</varname> variable. If you change the default port on which the arbiter process listens for connections, you must specify this port in the <literal>arbiter_port</literal> parameter. For details, see <xref linkend="multimaster-arbiter-port"> and <xref linkend="multimaster-conn-strings">.</para>
                 <important><para>The
                 <literal>multimaster.node_id</literal> variable takes natural
                 numbers starting from 1, without any gaps in numbering.
@@ -470,8 +479,30 @@ multimaster.conn_strings = 'dbname=mydb user=myuser host=node1,dbname=mydb user=
                 list the nodes in the order of their IDs. The
                 <literal>multimaster.conn_strings</literal> variable must be the
                 same on all nodes.</para></important>
-
-          </listitem>
+  <para>
+    You can customize connection parameters by adding other
+    <link linkend="libpq-paramkeywords">libpq connection options</link>
+    to connection strings in the <varname>multimaster.conn_strings</varname>
+    variable. By default, <filename>multimaster</filename> uses ports 5432
+    and 5433 to establish connections between the nodes and for the arbiter
+    process to listen for connections, respectively. If these ports are
+    already in use, you must specify other ports by adding
+    <literal>port</literal> and <literal>arbiter_port</literal> options
+    to each connection string in the <varname>multimaster.conn_strings</varname>
+    variable. To check whether the default ports are available, you can run with the following command:
+    <programlisting>
+netstat -ln | grep -E '5432|5433'
+</programlisting>
+    Make sure these ports are not blocked by firewall.
+  </para>
+  <para>
+    If you change the <literal>arbiter_port</literal>
+    option, you must also specify this port in the
+    <literal>multimaster.arbiter_port</literal> variable. For details,
+    see <xref linkend="multimaster-arbiter-port"> and
+    <xref linkend="multimaster-conn-strings">.
+  </para>
+        </listitem>
         </itemizedlist>
         <para>
           Depending on your network environment and usage patterns, you
@@ -480,11 +511,6 @@ multimaster.conn_strings = 'dbname=mydb user=myuser host=node1,dbname=mydb user=
           <xref linkend="multimaster-tuning-configuration-parameters">.
         </para>
       </listitem>
-      <listitem>
-        <para>
-          Modify the <filename>pg_hba.conf</filename> file to allow replication to each cluster node on behalf of <literal>myuser</literal>.
-        </para>
-      </listitem>
       <listitem>
         <para>
           Restart <productname>PostgreSQL</productname>:
@@ -515,6 +541,76 @@ SELECT mtm.get_cluster_state();
       <para><emphasis role="strong">See Also</emphasis></para>
       <para><link linkend="multimaster-tuning-configuration-parameters">Tuning
       Configuration Parameters</link></para>
+    <sect4>
+      <title>Sample Cluster Configuration</title>
+    <para>
+      This section shows a sample configuration of a three-node cluster for the
+      <literal>myuser</literal> user and <literal>mydb</literal> database.
+    </para>
+    <para>
+      First, run the following commands on all cluster nodes:
+      <programlisting>
+# Switch to the 'postgres' user
+sudo su - postgres
+
+# Set up environment variables
+export PGHOME=/usr/pgproee-&majorversion;
+export PATH=$PGHOME/bin:$PATH
+export MANPATH=$PGHOME/share/man:$MANPATH
+export PGDATA=/var/lib/pgproee/&majorversion;/data
+
+# Create a new user 'myuser' with superuser priviledges
+psql --dbname=postgres --username=postgres -c "CREATE USER myuser WITH SUPERUSER ENCRYPTED PASSWORD 'myuserpassword'"
+
+# Create a new database 'mydb'
+psql --dbname=postgres --username=myuser --host=127.0.0.1 -c "CREATE DATABASE mydb"
+
+# Enable replication on all cluster nodes.
+# The 'trust' method in this example is only provided for
+# illustration purposes and is not recommended on production systems.
+sed -i '/md5$/s|host|#host|' $PGDATA/pg_hba.conf
+echo "host replication myuser samenet trust" >> $PGDATA/pg_hba.conf
+echo "host all all 0.0.0.0/0 md5" >> $PGDATA/pg_hba.conf
+
+# Configure postgresql.conf settings
+echo "multimaster.max_nodes = 3" >> $PGDATA/postgresql.conf
+echo "multimaster.node_id = 'hostname | '{ print substr($1,5,1) }''" >> $PGDATA/postgresql.conf
+echo "multimaster.conn_strings = 'dbname=mydb user=myuser host=node1,dbname=mydb user=myuser host=node2,dbname=mydb user=myuser host=node3'" >> $PGDATA/postgresql.conf
+psql --dbname=mydb --username=myuser --host=127.0.0.1 -c "ALTER SYSTEM SET default_transaction_isolation TO 'read committed'"
+psql --dbname=mydb --username=myuser --host=127.0.0.1 -c "ALTER SYSTEM SET wal_level TO logical"
+psql --dbname=mydb --username=myuser --host=127.0.0.1 -c "ALTER SYSTEM SET max_connections TO 100"
+psql --dbname=mydb --username=myuser --host=127.0.0.1 -c "ALTER SYSTEM SET max_prepared_transactions to 300"
+psql --dbname=mydb --username=myuser --host=127.0.0.1 -c "ALTER SYSTEM SET max_wal_senders TO 10"
+psql --dbname=mydb --username=myuser --host=127.0.0.1 -c "ALTER SYSTEM SET max_replication_slots TO 10"
+psql --dbname=mydb --username=myuser --host=127.0.0.1 -c "ALTER SYSTEM SET max_worker_processes TO 250"
+psql --dbname=mydb --username=myuser --host=127.0.0.1 -c "ALTER SYSTEM SET shared_preload_libraries TO multimaster"
+psql --exit
+
+# Restart &productname;
+sudo systemctl restart postgrespro-enterprise-&majorversion;.service
+</programlisting>
+</para>
+  <para>
+    Now create the <filename>multimaster</filename> extension on one of the nodes.
+    It will be replicated to all the other cluster nodes automatically.
+<programlisting>
+# Switch to the 'postgres' user
+sudo su - postgres
+
+# Set up environment variables
+export PGHOME=/usr/pgproee-&majorversion;
+export PATH=$PGHOME/bin:$PATH
+export MANPATH=$PGHOME/share/man:$MANPATH
+export PGDATA=/var/lib/pgproee/&majorversion;/data
+
+# Create multimaster extension on one of the nodes
+psql --dbname=mydb --username=myuser --host=127.0.0.1 -c "CREATE EXTENSION IF NOT EXISTS multimaster"
+</programlisting>
+  </para>
+  <para>
+    The cluster is set up and ready to use.
+  </para>
+   </sect4>
   </sect3>
     <sect3 id="multimaster-tuning-configuration-parameters">
     <title>Tuning Configuration Parameters</title>