Review and update docs with the recent PRs. (#744)

hapostgres · Jun 30, 2021 · a88ded0 · a88ded0
1 parent 2eb2197
commit a88ded0
Show file tree

Hide file tree

Showing 3 changed files with 98 additions and 56 deletions.
diff --git a/docs/operations.rst b/docs/operations.rst
@@ -149,6 +149,19 @@ secondary nodes in maintenance. The procedure then looks like the following:
 
 		pg_autoctl disable maintenance
 
+Extension dependencies when upgrading the monitor
+-------------------------------------------------
+
+Since version 1.4.0 the ``pgautofailover`` extension requires the Postgres
+contrib extension ``btree_gist``. The ``pg_autoctl`` command arranges for
+the creation of this dependency, and has been buggy in some releases.
+
+As a result, you might have trouble upgrade the pg_auto_failover monitor to
+a recent version. It is possible to fix the error by connecting to the
+monitor Postgres database and running the ``create extension`` command
+manually::
+
+  # create extension btree_gist;
 
 Cluster Management and Operations
 ---------------------------------
@@ -388,11 +401,11 @@ the following commands.
      a primary still, for each group in your formation(s), enable the
      monitor online again::
 
-	   $ pg_autoctl enable monitor --monitor postgresql://...
+	   $ pg_autoctl enable monitor postgresql://autoctl_node@.../pg_auto_failover
 
   5. On every other (secondary) node, enable the monitor online again::
 
-	   $ pg_autoctl enable monitor --monitor postgresql://...
+	   $ pg_autoctl enable monitor postgresql://autoctl_node@.../pg_auto_failover
 
 See :ref:`pg_autoctl_disable_monitor` and :ref:`pg_autoctl_enable_monitor`
 for details about those commands.

diff --git a/docs/ref/pg_autoctl_config_set.rst b/docs/ref/pg_autoctl_config_set.rst
@@ -168,6 +168,25 @@ replication.backup_directory
   Can be changed online with a reload, will not affect already running
   ``pg_basebackup`` sub-processes.
 
+replication.password
+
+  Used as a parameter in the connection string to the upstream Postgres
+  node. The "replication" connection uses the password set-up in the
+  pg_autoctl configuration file.
+
+  Changing the ``replication.password`` of a pg_autoctl configuration has no
+  effect on the Postgres database itself. The password must match what the
+  Postgres upstream node expects, which can be set with the following SQL
+  command run on the upstream server (primary or other standby node)::
+
+	alter user pgautofailover_replicator password 'h4ckm3m0r3';
+
+  The ``replication.password`` can be changed online with a reload, but
+  requires restarting the Postgres service to be activated. Postgres only
+  reads the ``primary_conninfo`` connection string at start-up, up to and
+  including Postgres 12. With Postgres 13 and following, it is possible to
+  *reload* this Postgres paramater.
+
 timeout.network_partition_timeout
 
   Timeout (in seconds) that pg_autoctl waits before deciding that it is on

diff --git a/docs/ref/pg_autoctl_show_state.rst b/docs/ref/pg_autoctl_show_state.rst
@@ -77,14 +77,21 @@ The ``pg_autoctl show state`` outputs includes the following columns:
 
 	Hostname and port number used to connect to the node.
 
-  - LSN
+  - TLI: LSN
 
-	Postgres Log Sequence Number, which is the current position in the WAL
-	stream. This is a hexadecimal number. See `pg_lsn`__ for more
-	information.
+	Timeline identifier (TLI) and Postgres Log Sequence Number (LSN).
+
+	The LSN is the current position in the Postgres WAL stream. This is a
+	hexadecimal number. See `pg_lsn`__ for more information.
 
 	__ https://www.postgresql.org/docs/current/datatype-pg-lsn.html
 
+	The current `timeline`__ is incremented each time a failover happens, or
+	when doing Point In Time Recovery. A node can only reach the secondary
+	state when it is on the same timeline as its primary node.
+
+	__ https://www.postgresql.org/docs/current/continuous-archiving.html#BACKUP-TIMELINES
+
   - Connection
 
 	This output field contains two bits of information. First, the Postgres
@@ -112,59 +119,62 @@ Examples
 ::
 
    $ pg_autoctl show state
-    Name |  Node |      Host:Port |       LSN |   Connection |       Current State |      Assigned State
-   ------+-------+----------------+-----------+--------------+---------------------+--------------------
-   node1 |     1 | localhost:5501 | 0/4000760 |   read-write |             primary |             primary
-   node2 |     2 | localhost:5502 | 0/4000760 |    read-only |           secondary |           secondary
-   node3 |     3 | localhost:5503 | 0/4000760 |    read-only |           secondary |           secondary
+    Name |  Node |      Host:Port |       TLI: LSN |   Connection |       Current State |      Assigned State
+   ------+-------+----------------+----------------+--------------+---------------------+--------------------
+   node1 |     1 | localhost:5501 |   1: 0/4000678 |   read-write |             primary |             primary
+   node2 |     2 | localhost:5502 |   1: 0/4000678 |    read-only |           secondary |           secondary
+   node3 |     3 | localhost:5503 |   1: 0/4000678 |    read-only |           secondary |           secondary
 
    $ pg_autoctl show state --local
-    Name |  Node |      Host:Port |       LSN |   Connection |       Current State |      Assigned State
-   ------+-------+----------------+-----------+--------------+---------------------+--------------------
-   node1 |     1 | localhost:5501 | 0/4000760 | read-write ? |             primary |             primary
+    Name |  Node |      Host:Port |       TLI: LSN |   Connection |       Current State |      Assigned State
+   ------+-------+----------------+----------------+--------------+---------------------+--------------------
+   node1 |     1 | localhost:5501 |   1: 0/4000678 | read-write ? |             primary |             primary
 
    $ pg_autoctl show state --json
    [
-    {
-        "health": 1,
-        "node_id": 1,
-        "group_id": 0,
-        "nodehost": "localhost",
-        "nodename": "node1",
-        "nodeport": 5501,
-        "reported_lsn": "0/4000760",
-        "formation_kind": "pgsql",
-        "candidate_priority": 50,
-        "replication_quorum": true,
-        "current_group_state": "primary",
-        "assigned_group_state": "primary"
-    },
-    {
-        "health": 1,
-        "node_id": 2,
-        "group_id": 0,
-        "nodehost": "localhost",
-        "nodename": "node2",
-        "nodeport": 5502,
-        "reported_lsn": "0/4000760",
-        "formation_kind": "pgsql",
-        "candidate_priority": 50,
-        "replication_quorum": true,
-        "current_group_state": "secondary",
-        "assigned_group_state": "secondary"
-    },
-    {
-        "health": 1,
-        "node_id": 3,
-        "group_id": 0,
-        "nodehost": "localhost",
-        "nodename": "node3",
-        "nodeport": 5503,
-        "reported_lsn": "0/4000760",
-        "formation_kind": "pgsql",
-        "candidate_priority": 50,
-        "replication_quorum": true,
-        "current_group_state": "secondary",
-        "assigned_group_state": "secondary"
-    }
+       {
+           "health": 1,
+           "node_id": 1,
+           "group_id": 0,
+           "nodehost": "localhost",
+           "nodename": "node1",
+           "nodeport": 5501,
+           "reported_lsn": "0/4000678",
+           "reported_tli": 1,
+           "formation_kind": "pgsql",
+           "candidate_priority": 50,
+           "replication_quorum": true,
+           "current_group_state": "primary",
+           "assigned_group_state": "primary"
+       },
+       {
+           "health": 1,
+           "node_id": 2,
+           "group_id": 0,
+           "nodehost": "localhost",
+           "nodename": "node2",
+           "nodeport": 5502,
+           "reported_lsn": "0/4000678",
+           "reported_tli": 1,
+           "formation_kind": "pgsql",
+           "candidate_priority": 50,
+           "replication_quorum": true,
+           "current_group_state": "secondary",
+           "assigned_group_state": "secondary"
+       },
+       {
+           "health": 1,
+           "node_id": 3,
+           "group_id": 0,
+           "nodehost": "localhost",
+           "nodename": "node3",
+           "nodeport": 5503,
+           "reported_lsn": "0/4000678",
+           "reported_tli": 1,
+           "formation_kind": "pgsql",
+           "candidate_priority": 50,
+           "replication_quorum": true,
+           "current_group_state": "secondary",
+           "assigned_group_state": "secondary"
+       }
    ]