1PG_AUTOCTL SHOW FILE(1) pg_auto_failover PG_AUTOCTL SHOW FILE(1)
2
6 pg_autoctl show file - pg_autoctl show file
7 pg_autoctl show file - List pg_autoctl internal files (config, state,
9 pid)
10
12 This command the files that pg_autoctl uses internally for its own con‐
13 figuration, state, and pid:
14 usage: pg_autoctl show file [ --pgdata --all --config | --state | --init | --pid --contents ]
16 --pgdata path to data directory
18 --all show all pg_autoctl files
19 --config show pg_autoctl configuration file
20 --state show pg_autoctl state file
21 --init show pg_autoctl initialisation state file
22 --pid show pg_autoctl PID file
23 --contents show selected file contents
24 --json output data in the JSON format
25
27 The pg_autoctl command follows the XDG Base Directory Specification and
28 places its internal and configuration files by default in places such
29 as ~/.config/pg_autoctl and ~/.local/share/pg_autoctl.
30 It is possible to change the default XDG locations by using the envi‐
32 ronment variables XDG_CONFIG_HOME, XDG_DATA_HOME, and XDG_RUNTIME_DIR.
33 Also, pg_config uses sub-directories that are specific to a given PG‐
35 DATA, making it possible to run several Postgres nodes on the same ma‐
36 chine, which is very practical for testing and development purposes,
37 though not advised for production setups.
38 Configuration File
40 The pg_autoctl configuration file for an instance serving the data di‐
41 rectory at /data/pgsql is found at ~/.config/pg_au‐
42 toctl/data/pgsql/pg_autoctl.cfg, written in the INI format.
43 It is possible to get the location of the configuration file by using
45 the command pg_autoctl show file --config --pgdata /data/pgsql and to
46 output its content by using the command pg_autoctl show file --config
47 --contents --pgdata /data/pgsql.
48 See also pg_autoctl config get and pg_autoctl config set.
50 State File
52 The pg_autoctl state file for an instance serving the data directory at
53 /data/pgsql is found at ~/.local/share/pg_autoctl/data/pgsql/pg_au‐
54 toctl.state, written in a specific binary format.
55 This file is not intended to be written by anything else than pg_au‐
57 toctl itself. In case of state corruption, see the trouble shooting
58 section of the documentation.
59 It is possible to get the location of the state file by using the com‐
61 mand pg_autoctl show file --state --pgdata /data/pgsql and to output
62 its content by using the command pg_autoctl show file --state --con‐
63 tents --pgdata /data/pgsql.
64 Init State File
66 The pg_autoctl init state file for an instance serving the data direc‐
67 tory at /data/pgsql is found at ~/.local/share/pg_au‐
68 toctl/data/pgsql/pg_autoctl.init, written in a specific binary format.
69 This file is not intended to be written by anything else than pg_au‐
71 toctl itself. In case of state corruption, see the trouble shooting
72 section of the documentation.
73 This initialization state file only exists during the initialization of
75 a pg_auto_failover node. In normal operations, this file does not ex‐
76 ist.
77 It is possible to get the location of the state file by using the com‐
79 mand pg_autoctl show file --init --pgdata /data/pgsql and to output its
80 content by using the command pg_autoctl show file --init --contents
81 --pgdata /data/pgsql.
82 PID File
84 The pg_autoctl PID file for an instance serving the data directory at
85 /data/pgsql is found at /tmp/pg_autoctl/data/pgsql/pg_autoctl.pid,
86 written in a specific text format.
87 The PID file is located in a temporary directory by default, or in the
89 XDG_RUNTIME_DIR directory when this is setup.
90
92 --pgdata
93 Location of the Postgres node being managed locally. Defaults to
94 the environment variable PGDATA. Use --monitor to connect to a
95 monitor from anywhere, rather than the monitor URI used by a lo‐
96 cal Postgres node managed with pg_autoctl.
97 --all List all the files that belong to this pg_autoctl node.
99 --config
101 Show only the configuration file.
102 --state
104 Show only the state file.
105 --init Show only the init state file, which only exists while the com‐
107 mand pg_autoctl create postgres or the command pg_autoctl create
108 monitor is running, or when than command failed (and can then be
109 retried).
110 --pid Show only the pid file.
112 --contents
114 When one of the options to show a specific file is in use, then
115 --contents shows the contents of the selected file instead of
116 showing its absolute file path.
117 --json Output JSON formatted data.
119
121 PGDATA
122 Postgres directory location. Can be used instead of the --pgdata op‐
123 tion.
124 PG_AUTOCTL_MONITOR
126 Postgres URI to connect to the monitor node, can be used instead of
127 the --monitor option.
128 XDG_CONFIG_HOME
130 The pg_autoctl command stores its configuration files in the stan‐
131 dard place XDG_CONFIG_HOME. See the XDG Base Directory Specifica‐
132 tion.
133 XDG_DATA_HOME
135 The pg_autoctl command stores its internal states files in the stan‐
136 dard place XDG_DATA_HOME, which defaults to ~/.local/share. See the
137 XDG Base Directory Specification.
138
140 The following examples are taken from a QA environment that has been
141 prepared thanks to the make cluster command made available to the
142 pg_auto_failover contributors. As a result, the XDG environment vari‐
143 ables have been tweaked to obtain a self-contained test:
144 $ tmux show-env | grep XDG
146 XDG_CONFIG_HOME=/Users/dim/dev/MS/pg_auto_failover/tmux/config
147 XDG_DATA_HOME=/Users/dim/dev/MS/pg_auto_failover/tmux/share
148 XDG_RUNTIME_DIR=/Users/dim/dev/MS/pg_auto_failover/tmux/run
149 Within that self-contained test location, we can see the following ex‐
151 amples.
152 $ pg_autoctl show file --pgdata ./node1
154 File | Path
155 --------+----------------
156 Config | /Users/dim/dev/MS/pg_auto_failover/tmux/config/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.cfg
157 State | /Users/dim/dev/MS/pg_auto_failover/tmux/share/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.state
158 Init | /Users/dim/dev/MS/pg_auto_failover/tmux/share/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.init
159 Pid | /Users/dim/dev/MS/pg_auto_failover/tmux/run/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.pid
160 'ANY 1 (pgautofailover_standby_2, pgautofailover_standby_3)'
161 $ pg_autoctl show file --pgdata node1 --state
163 /Users/dim/dev/MS/pg_auto_failover/tmux/share/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.state
164 $ pg_autoctl show file --pgdata node1 --state --contents
166 Current Role: primary
167 Assigned Role: primary
168 Last Monitor Contact: Thu Mar 18 17:32:25 2021
169 Last Secondary Contact: 0
170 pg_autoctl state version: 1
171 group: 0
172 node id: 1
173 nodes version: 0
174 PostgreSQL Version: 1201
175 PostgreSQL CatVersion: 201909212
176 PostgreSQL System Id: 6940955496243696337
177 pg_autoctl show file --pgdata node1 --config --contents --json | jq .pg_autoctl
179 {
180 "role": "keeper",
181 "monitor": "postgres://autoctl_node@localhost:5500/pg_auto_failover?sslmode=prefer",
182 "formation": "default",
183 "group": 0,
184 "name": "node1",
185 "hostname": "localhost",
186 "nodekind": "standalone"
187 }
188
190 Microsoft
191
193 Copyright (c) Microsoft Corporation. All rights reserved.
1942.0 Sep 13, 2023 PG_AUTOCTL SHOW FILE(1)