1PG_AUTOCTL SHOW FILE(1)        pg_auto_failover        PG_AUTOCTL SHOW FILE(1)
2
3
4

NAME

6       pg_autoctl show file - pg_autoctl show file
7
8       pg_autoctl  show  file - List pg_autoctl internal files (config, state,
9       pid)
10

SYNOPSIS

12       This command the files that pg_autoctl uses internally for its own con‐
13       figuration, state, and pid:
14
15          usage: pg_autoctl show file  [ --pgdata --all --config | --state | --init | --pid --contents ]
16
17          --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

DESCRIPTION

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
31       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
34       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
39   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
44       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
49       See also pg_autoctl config get and pg_autoctl config set.
50
51   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
56       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
60       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
65   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
70       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
74       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
78       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
83   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
88       The PID file is located in a temporary directory by default, or in  the
89       XDG_RUNTIME_DIR directory when this is setup.
90

OPTIONS

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
98       --all  List all the files that belong to this pg_autoctl node.
99
100       --config
101              Show only the configuration file.
102
103       --state
104              Show only the state file.
105
106       --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
111       --pid  Show only the pid file.
112
113       --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
118       --json Output JSON formatted data.
119

ENVIRONMENT

121       PGDATA
122          Postgres directory location. Can be used instead of the --pgdata op‐
123          tion.
124
125       PG_AUTOCTL_MONITOR
126          Postgres URI to connect to the monitor node, can be used instead  of
127          the --monitor option.
128
129       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
134       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

EXAMPLES

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
145          $  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
150       Within that self-contained test location, we can see the following  ex‐
151       amples.
152
153          $ 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
162          $ 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
165          $ 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
178          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

AUTHOR

190       Microsoft
191
193       Copyright (c) Microsoft Corporation. All rights reserved.
194
195
196
197
1982.0                              Sep 13, 2023          PG_AUTOCTL SHOW FILE(1)
Impressum