Skip to content

Commit a88ded0

Browse files
DimCitusDimCitus
authored
Review and update docs with the recent PRs. (#744)
1 parent 2eb2197 commit a88ded0

3 files changed

Lines changed: 98 additions & 56 deletions

File tree

‎docs/operations.rst‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,19 @@ secondary nodes in maintenance. The procedure then looks like the following:
149149

150150
pg_autoctl disable maintenance
151151

152+
Extension dependencies when upgrading the monitor
153+
-------------------------------------------------
154+
155+
Since version 1.4.0 the ``pgautofailover`` extension requires the Postgres
156+
contrib extension ``btree_gist``. The ``pg_autoctl`` command arranges for
157+
the creation of this dependency, and has been buggy in some releases.
158+
159+
As a result, you might have trouble upgrade the pg_auto_failover monitor to
160+
a recent version. It is possible to fix the error by connecting to the
161+
monitor Postgres database and running the ``create extension`` command
162+
manually::
163+
164+
# create extension btree_gist;
152165

153166
Cluster Management and Operations
154167
---------------------------------
@@ -388,11 +401,11 @@ the following commands.
388401
a primary still, for each group in your formation(s), enable the
389402
monitor online again::
390403

391-
$ pg_autoctl enable monitor --monitor postgresql://...
404+
$ pg_autoctl enable monitor postgresql://autoctl_node@.../pg_auto_failover
392405

393406
5. On every other (secondary) node, enable the monitor online again::
394407

395-
$ pg_autoctl enable monitor --monitor postgresql://...
408+
$ pg_autoctl enable monitor postgresql://autoctl_node@.../pg_auto_failover
396409

397410
See :ref:`pg_autoctl_disable_monitor` and :ref:`pg_autoctl_enable_monitor`
398411
for details about those commands.

‎docs/ref/pg_autoctl_config_set.rst‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,25 @@ replication.backup_directory
168168
Can be changed online with a reload, will not affect already running
169169
``pg_basebackup`` sub-processes.
170170

171+
replication.password
172+
173+
Used as a parameter in the connection string to the upstream Postgres
174+
node. The "replication" connection uses the password set-up in the
175+
pg_autoctl configuration file.
176+
177+
Changing the ``replication.password`` of a pg_autoctl configuration has no
178+
effect on the Postgres database itself. The password must match what the
179+
Postgres upstream node expects, which can be set with the following SQL
180+
command run on the upstream server (primary or other standby node)::
181+
182+
alter user pgautofailover_replicator password 'h4ckm3m0r3';
183+
184+
The ``replication.password`` can be changed online with a reload, but
185+
requires restarting the Postgres service to be activated. Postgres only
186+
reads the ``primary_conninfo`` connection string at start-up, up to and
187+
including Postgres 12. With Postgres 13 and following, it is possible to
188+
*reload* this Postgres paramater.
189+
171190
timeout.network_partition_timeout
172191

173192
Timeout (in seconds) that pg_autoctl waits before deciding that it is on

‎docs/ref/pg_autoctl_show_state.rst‎

Lines changed: 64 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -77,14 +77,21 @@ The ``pg_autoctl show state`` outputs includes the following columns:
7777

7878
Hostname and port number used to connect to the node.
7979

80-
- LSN
80+
- TLI: LSN
8181

82-
Postgres Log Sequence Number, which is the current position in the WAL
83-
stream. This is a hexadecimal number. See `pg_lsn`__ for more
84-
information.
82+
Timeline identifier (TLI) and Postgres Log Sequence Number (LSN).
83+
84+
The LSN is the current position in the Postgres WAL stream. This is a
85+
hexadecimal number. See `pg_lsn`__ for more information.
8586

8687
__ https://www.postgresql.org/docs/current/datatype-pg-lsn.html
8788

89+
The current `timeline`__ is incremented each time a failover happens, or
90+
when doing Point In Time Recovery. A node can only reach the secondary
91+
state when it is on the same timeline as its primary node.
92+
93+
__ https://www.postgresql.org/docs/current/continuous-archiving.html#BACKUP-TIMELINES
94+
8895
- Connection
8996

9097
This output field contains two bits of information. First, the Postgres
@@ -112,59 +119,62 @@ Examples
112119
::
113120

114121
$ pg_autoctl show state
115-
Name | Node | Host:Port | LSN | Connection | Current State | Assigned State
116-
------+-------+----------------+-----------+--------------+---------------------+--------------------
117-
node1 | 1 | localhost:5501 | 0/4000760 | read-write | primary | primary
118-
node2 | 2 | localhost:5502 | 0/4000760 | read-only | secondary | secondary
119-
node3 | 3 | localhost:5503 | 0/4000760 | read-only | secondary | secondary
122+
Name | Node | Host:Port | TLI: LSN | Connection | Current State | Assigned State
123+
------+-------+----------------+----------------+--------------+---------------------+--------------------
124+
node1 | 1 | localhost:5501 | 1: 0/4000678 | read-write | primary | primary
125+
node2 | 2 | localhost:5502 | 1: 0/4000678 | read-only | secondary | secondary
126+
node3 | 3 | localhost:5503 | 1: 0/4000678 | read-only | secondary | secondary
120127

121128
$ pg_autoctl show state --local
122-
Name | Node | Host:Port | LSN | Connection | Current State | Assigned State
123-
------+-------+----------------+-----------+--------------+---------------------+--------------------
124-
node1 | 1 | localhost:5501 | 0/4000760 | read-write ? | primary | primary
129+
Name | Node | Host:Port | TLI: LSN | Connection | Current State | Assigned State
130+
------+-------+----------------+----------------+--------------+---------------------+--------------------
131+
node1 | 1 | localhost:5501 | 1: 0/4000678 | read-write ? | primary | primary
125132

126133
$ pg_autoctl show state --json
127134
[
128-
{
129-
"health": 1,
130-
"node_id": 1,
131-
"group_id": 0,
132-
"nodehost": "localhost",
133-
"nodename": "node1",
134-
"nodeport": 5501,
135-
"reported_lsn": "0/4000760",
136-
"formation_kind": "pgsql",
137-
"candidate_priority": 50,
138-
"replication_quorum": true,
139-
"current_group_state": "primary",
140-
"assigned_group_state": "primary"
141-
},
142-
{
143-
"health": 1,
144-
"node_id": 2,
145-
"group_id": 0,
146-
"nodehost": "localhost",
147-
"nodename": "node2",
148-
"nodeport": 5502,
149-
"reported_lsn": "0/4000760",
150-
"formation_kind": "pgsql",
151-
"candidate_priority": 50,
152-
"replication_quorum": true,
153-
"current_group_state": "secondary",
154-
"assigned_group_state": "secondary"
155-
},
156-
{
157-
"health": 1,
158-
"node_id": 3,
159-
"group_id": 0,
160-
"nodehost": "localhost",
161-
"nodename": "node3",
162-
"nodeport": 5503,
163-
"reported_lsn": "0/4000760",
164-
"formation_kind": "pgsql",
165-
"candidate_priority": 50,
166-
"replication_quorum": true,
167-
"current_group_state": "secondary",
168-
"assigned_group_state": "secondary"
169-
}
135+
{
136+
"health": 1,
137+
"node_id": 1,
138+
"group_id": 0,
139+
"nodehost": "localhost",
140+
"nodename": "node1",
141+
"nodeport": 5501,
142+
"reported_lsn": "0/4000678",
143+
"reported_tli": 1,
144+
"formation_kind": "pgsql",
145+
"candidate_priority": 50,
146+
"replication_quorum": true,
147+
"current_group_state": "primary",
148+
"assigned_group_state": "primary"
149+
},
150+
{
151+
"health": 1,
152+
"node_id": 2,
153+
"group_id": 0,
154+
"nodehost": "localhost",
155+
"nodename": "node2",
156+
"nodeport": 5502,
157+
"reported_lsn": "0/4000678",
158+
"reported_tli": 1,
159+
"formation_kind": "pgsql",
160+
"candidate_priority": 50,
161+
"replication_quorum": true,
162+
"current_group_state": "secondary",
163+
"assigned_group_state": "secondary"
164+
},
165+
{
166+
"health": 1,
167+
"node_id": 3,
168+
"group_id": 0,
169+
"nodehost": "localhost",
170+
"nodename": "node3",
171+
"nodeport": 5503,
172+
"reported_lsn": "0/4000678",
173+
"reported_tli": 1,
174+
"formation_kind": "pgsql",
175+
"candidate_priority": 50,
176+
"replication_quorum": true,
177+
"current_group_state": "secondary",
178+
"assigned_group_state": "secondary"
179+
}
170180
]

0 commit comments

Comments
 (0)