1PG_AUTOCTL CREATE POSTGRES(1) pg_auto_failover PG_AUTOCTL CREATE POSTGRES(1)
2
6 pg_autoctl create postgres - pg_autoctl create postgres
7 pg_autoctl create postgres - Initialize a pg_auto_failover postgres
9 node
10
12 The command pg_autoctl create postgres initializes a standalone Post‐
13 gres node to a pg_auto_failover monitor. The monitor is then handling
14 auto-failover for this Postgres node (as soon as a secondary has been
15 registered too, and is known to be healthy).
16 usage: pg_autoctl create postgres
18 --pgctl path to pg_ctl
20 --pgdata path to data directory
21 --pghost PostgreSQL's hostname
22 --pgport PostgreSQL's port number
23 --listen PostgreSQL's listen_addresses
24 --username PostgreSQL's username
25 --dbname PostgreSQL's database name
26 --name pg_auto_failover node name
27 --hostname hostname used to connect from the other nodes
28 --formation pg_auto_failover formation
29 --monitor pg_auto_failover Monitor Postgres URL
30 --auth authentication method for connections from monitor
31 --skip-pg-hba skip editing pg_hba.conf rules
32 --pg-hba-lan edit pg_hba.conf rules for --dbname in detected LAN
33 --ssl-self-signed setup network encryption using self signed certificates (does NOT protect against MITM)
34 --ssl-mode use that sslmode in connection strings
35 --ssl-ca-file set the Postgres ssl_ca_file to that file path
36 --ssl-crl-file set the Postgres ssl_crl_file to that file path
37 --no-ssl don't enable network encryption (NOT recommended, prefer --ssl-self-signed)
38 --server-key set the Postgres ssl_key_file to that file path
39 --server-cert set the Postgres ssl_cert_file to that file path
40 --candidate-priority priority of the node to be promoted to become primary
41 --replication-quorum true if node participates in write quorum
42 --maximum-backup-rate maximum transfer rate of data transferred from the server during initial sync
43
45 Three different modes of initialization are supported by this command,
46 corresponding to as many implementation strategies.
47 1. Initialize a primary node from scratch
49 This happens when --pgdata (or the environment variable PGDATA)
51 points to an non-existing or empty directory. Then the given
52 --hostname is registered to the pg_auto_failover --monitor as a
53 member of the --formation.
54 The monitor answers to the registration call with a state to as‐
56 sign to the new member of the group, either SINGLE or
57 WAIT_STANDBY. When the assigned state is SINGLE, then pg_autoctl
58 create postgres proceeds to initialize a new PostgreSQL instance.
59 2. Initialize an already existing primary server
61 This happens when --pgdata (or the environment variable PGDATA)
63 points to an already existing directory that belongs to a Post‐
64 greSQL instance. The standard PostgreSQL tool pg_controldata is
65 used to recognize whether the directory belongs to a PostgreSQL
66 instance.
67 In that case, the given --hostname is registered to the monitor
69 in the tentative SINGLE state. When the given --formation and
70 --group is currently empty, then the monitor accepts the regis‐
71 tration and the pg_autoctl create prepares the already existing
72 primary server for pg_auto_failover.
73 3. Initialize a secondary node from scratch
75 This happens when --pgdata (or the environment variable PGDATA)
77 points to a non-existing or empty directory, and when the monitor
78 registration call assigns the state WAIT_STANDBY in step 1.
79 In that case, the pg_autoctl create command steps through the
81 initial states of registering a secondary server, which includes
82 preparing the primary server PostgreSQL HBA rules and creating a
83 replication slot.
84 When the command ends successfully, a PostgreSQL secondary server
86 has been created with pg_basebackup and is now started, catch‐
87 ing-up to the primary server.
88 4. Initialize a secondary node from an existing data directory
90 When the data directory pointed to by the option --pgdata or the
92 environment variable PGDATA already exists, then pg_auto_failover
93 verifies that the system identifier matches the one of the other
94 nodes already existing in the same group.
95 The system identifier can be obtained with the command pg_con‐
97 troldata. All nodes in a physical replication setting must have
98 the same system identifier, and so in pg_auto_failover all the
99 nodes in a same group have that constraint too.
100 When the system identifier matches the already registered system
102 identifier of other nodes in the same group, then the node is
103 set-up as a standby and Postgres is started with the primary con‐
104 ninfo pointed at the current primary.
105 The --auth option allows setting up authentication method to be used
107 when monitor node makes a connection to data node with pgauto‐
108 failover_monitor user. As with the pg_autoctl create monitor command,
109 you could use --auth trust when playing with pg_auto_failover at first
110 and consider something production grade later. Also, consider using
111 --skip-pg-hba if you already have your own provisioning tools with a
112 security compliance process.
113 See Security settings for pg_auto_failover for notes on .pgpass
115
117 The following options are available to pg_autoctl create postgres:
118 --pgctl
120 Path to the pg_ctl tool to use for the version of PostgreSQL you
121 want to use.
122 Defaults to the pg_ctl found in the PATH when there is a single
124 entry for pg_ctl in the PATH. Check your setup using which -a
125 pg_ctl.
126 When using an RPM based distribution such as RHEL or CentOS, the
128 path would usually be /usr/pgsql-13/bin/pg_ctl for Postgres 13.
129 When using a debian based distribution such as debian or ubuntu,
131 the path would usually be /usr/lib/postgresql/13/bin/pg_ctl for
132 Postgres 13. Those distributions also use the package post‐
133 gresql-common which provides /usr/bin/pg_config. This tool can
134 be automatically used by pg_autoctl to discover the default ver‐
135 sion of Postgres to use on your setup.
136 --pgdata
138 Location where to initialize a Postgres database cluster, using
139 either pg_ctl initdb or pg_basebackup. Defaults to the environ‐
140 ment variable PGDATA.
141 --pghost
143 Hostname to use when connecting to the local Postgres instance
144 from the pg_autoctl process. By default, this field is left
145 blank in the connection string, allowing to use Unix Domain
146 Sockets with the default path compiled in your libpq version,
147 usually provided by the Operating System. That would be
148 /var/run/postgresql when using debian or ubuntu.
149 --pgport
151 Postgres port to use, defaults to 5432.
152 --listen
154 PostgreSQL's listen_addresses to setup. At the moment only one
155 address is supported in this command line option.
156 --username
158 PostgreSQL's username to use when connecting to the local Post‐
159 gres instance to manage it.
160 --dbname
162 PostgreSQL's database name to use in your application. Defaults
163 to being the same as the --username, or to postgres when none of
164 those options are used.
165 --name Node name used on the monitor to refer to this node. The host‐
167 name is a technical information, and given Postgres requirements
168 on the HBA setup and DNS resolution (both forward and reverse
169 lookups), IP addresses are often used for the hostname.
170 The --name option allows using a user-friendly name for your
172 Postgres nodes.
173 --hostname
175 Hostname or IP address (both v4 and v6 are supported) to use
176 from any other node to connect to this node.
177 When not provided, a default value is computed by running the
179 following algorithm.
180 1. We get this machine's "public IP" by opening a connection
182 to the given monitor hostname or IP address. Then we get
183 TCP/IP client address that has been used to make that con‐
184 nection.
185 2. We then do a reverse DNS lookup on the IP address found in
187 the previous step to fetch a hostname for our local ma‐
188 chine.
189 3. If the reverse DNS lookup is successful , then pg_autoctl
191 does a forward DNS lookup of that hostname.
192 When the forward DNS lookup response in step 3. is an IP address
194 found in one of our local network interfaces, then pg_autoctl
195 uses the hostname found in step 2. as the default --hostname.
196 Otherwise it uses the IP address found in step 1.
197 You may use the --hostname command line option to bypass the
199 whole DNS lookup based process and force the local node name to
200 a fixed value.
201 --formation
203 Formation to register the node into on the monitor. Defaults to
204 the default formation, that is automatically created in the mon‐
205 itor in the pg_autoctl create monitor command.
206 --monitor
208 Postgres URI used to connect to the monitor. Must use the au‐
209 toctl_node username and target the pg_auto_failover database
210 name. It is possible to show the Postgres URI from the monitor
211 node using the command pg_autoctl show uri.
212 --auth Authentication method used by pg_autoctl when editing the Post‐
214 gres HBA file to open connections to other nodes. No default
215 value, must be provided by the user. The value --trust is only a
216 good choice for testing and evaluation of pg_auto_failover, see
217 Security settings for pg_auto_failover for more information.
218 --skip-pg-hba
220 When this option is used then pg_autoctl refrains from any edit‐
221 ing of the Postgres HBA file. Please note that editing the HBA
222 file is still needed so that other nodes can connect using ei‐
223 ther read privileges or replication streaming privileges.
224 When --skip-pg-hba is used, pg_autoctl still outputs the HBA en‐
226 tries it needs in the logs, it only skips editing the HBA file.
227 --pg-hba-lan
229 When this option is used pg_autoctl determines the local IP ad‐
230 dress used to connect to the monitor, and retrieves its netmask,
231 and uses that to compute your local area network CIDR. This CIDR
232 is then opened for connections in the Postgres HBA rules.
233 For instance, when the monitor resolves to 192.168.0.1 and your
235 local Postgres node uses an inferface with IP address
236 192.168.0.2/255.255.255.0 to connect to the monitor, then the
237 LAN CIDR is computed to be 192.168.0.0/24.
238 --candidate-priority
240 Sets this node replication setting for candidate priority to the
241 given value (between 0 and 100) at node registration on the mon‐
242 itor. Defaults to 50.
243 --replication-quorum
245 Sets this node replication setting for replication quorum to the
246 given value (either true or false) at node registration on the
247 monitor. Defaults to true, which enables synchronous replica‐
248 tion.
249 --maximum-backup-rate
251 Sets the maximum transfer rate of data transferred from the
252 server during initial sync. This is used by pg_basebackup. De‐
253 faults to 100M.
254 --run Immediately run the pg_autoctl service after having created this
256 node.
257 --ssl-self-signed
259 Generate SSL self-signed certificates to provide network encryp‐
260 tion. This does not protect against man-in-the-middle kinds of
261 attacks. See Security settings for pg_auto_failover for more
262 about our SSL settings.
263 --ssl-mode
265 SSL Mode used by pg_autoctl when connecting to other nodes, in‐
266 cluding when connecting for streaming replication.
267 --ssl-ca-file
269 Set the Postgres ssl_ca_file to that file path.
270 --ssl-crl-file
272 Set the Postgres ssl_crl_file to that file path.
273 --no-ssl
275 Don't enable network encryption. This is not recommended, prefer
276 --ssl-self-signed.
277 --server-key
279 Set the Postgres ssl_key_file to that file path.
280 --server-cert
282 Set the Postgres ssl_cert_file to that file path.
283
285 PGDATA
286 Postgres directory location. Can be used instead of the --pgdata op‐
287 tion.
288 PG_AUTOCTL_MONITOR
290 Postgres URI to connect to the monitor node, can be used instead of
291 the --monitor option.
292 PG_AUTOCTL_NODE_NAME
294 Node name to register to the monitor, can be used instead of the
295 --name option.
296 PG_AUTOCTL_REPLICATION_QUORUM
298 Can be used instead of the --replication-quorum option.
299 PG_AUTOCTL_CANDIDATE_PRIORITY
301 Can be used instead of the --candidate-priority option.
302 PG_CONFIG
304 Can be set to the absolute path to the pg_config Postgres tool. This
305 is mostly used in the context of building extensions, though it can
306 be a useful way to select a Postgres version when several are in‐
307 stalled on the same system.
308 PATH
310 Used the usual way mostly. Some entries that are searched in the
311 PATH by the pg_autoctl command are expected to be found only once,
312 to avoid mistakes with Postgres major versions.
313 PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ...
315 See the Postgres docs about Environment Variables for details.
316 TMPDIR
318 The pgcopydb command creates all its work files and directories in
319 ${TMPDIR}/pgcopydb, and defaults to /tmp/pgcopydb.
320 XDG_CONFIG_HOME
322 The pg_autoctl command stores its configuration files in the stan‐
323 dard place XDG_CONFIG_HOME. See the XDG Base Directory Specifica‐
324 tion.
325 XDG_DATA_HOME
327 The pg_autoctl command stores its internal states files in the stan‐
328 dard place XDG_DATA_HOME, which defaults to ~/.local/share. See the
329 XDG Base Directory Specification.
330
332 Microsoft
333
335 Copyright (c) Microsoft Corporation. All rights reserved.
3362.0 Sep 13, 2023 PG_AUTOCTL CREATE POSTGRES(1)