.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "PG_AUTOCTL SHOW FILE" "1" "Nov 06, 2022" "2.0" "pg_auto_failover"
.SH NAME
pg_autoctl show file \- pg_autoctl show file
.sp
pg_autoctl show file \- List pg_autoctl internal files (config, state, pid)
.SH SYNOPSIS
.sp
This command the files that \fBpg_autoctl\fP uses internally for its own
configuration, state, and pid:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
usage: pg_autoctl show file  [ \-\-pgdata \-\-all \-\-config | \-\-state | \-\-init | \-\-pid \-\-contents ]

\-\-pgdata      path to data directory
\-\-all         show all pg_autoctl files
\-\-config      show pg_autoctl configuration file
\-\-state       show pg_autoctl state file
\-\-init        show pg_autoctl initialisation state file
\-\-pid         show pg_autoctl PID file
\-\-contents    show selected file contents
\-\-json        output data in the JSON format
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
The \fBpg_autoctl\fP command follows the \fI\%XDG Base Directory Specification\fP
and places its internal and configuration files by default in places such as
\fB~/.config/pg_autoctl\fP and \fB~/.local/share/pg_autoctl\fP\&.
.sp
It is possible to change the default XDG locations by using the environment
variables \fBXDG_CONFIG_HOME\fP, \fBXDG_DATA_HOME\fP, and \fBXDG_RUNTIME_DIR\fP\&.
.sp
Also, \fBpg_config\fP uses sub\-directories that are specific to a given
\fBPGDATA\fP, making it possible to run several Postgres nodes on the same
machine, which is very practical for testing and development purposes,
though not advised for production setups.
.SS Configuration File
.sp
The \fBpg_autoctl\fP configuration file for an instance serving the data
directory at \fB/data/pgsql\fP is found at
\fB~/.config/pg_autoctl/data/pgsql/pg_autoctl.cfg\fP, written in the INI
format.
.sp
It is possible to get the location of the configuration file by using the
command \fBpg_autoctl show file \-\-config \-\-pgdata /data/pgsql\fP and to output
its content by using the command \fBpg_autoctl show
file \-\-config \-\-contents \-\-pgdata /data/pgsql\fP\&.
.sp
See also \fI\%pg_autoctl config get\fP and \fI\%pg_autoctl config set\fP\&.
.SS State File
.sp
The \fBpg_autoctl\fP state file for an instance serving the data directory at
\fB/data/pgsql\fP is found at
\fB~/.local/share/pg_autoctl/data/pgsql/pg_autoctl.state\fP, written in a
specific binary format.
.sp
This file is not intended to be written by anything else than \fBpg_autoctl\fP
itself. In case of state corruption, see the trouble shooting section of the
documentation.
.sp
It is possible to get the location of the state file by using the command
\fBpg_autoctl show file \-\-state \-\-pgdata /data/pgsql\fP and to output its
content by using the command \fBpg_autoctl show
file \-\-state \-\-contents \-\-pgdata /data/pgsql\fP\&.
.SS Init State File
.sp
The \fBpg_autoctl\fP init state file for an instance serving the data
directory at \fB/data/pgsql\fP is found at
\fB~/.local/share/pg_autoctl/data/pgsql/pg_autoctl.init\fP, written in a
specific binary format.
.sp
This file is not intended to be written by anything else than \fBpg_autoctl\fP
itself. In case of state corruption, see the trouble shooting section of the
documentation.
.sp
This initialization state file only exists during the initialization of a
pg_auto_failover node. In normal operations, this file does not exist.
.sp
It is possible to get the location of the state file by using the command
\fBpg_autoctl show file \-\-init \-\-pgdata /data/pgsql\fP and to output its
content by using the command \fBpg_autoctl show
file \-\-init \-\-contents \-\-pgdata /data/pgsql\fP\&.
.SS PID File
.sp
The \fBpg_autoctl\fP PID file for an instance serving the data directory at
\fB/data/pgsql\fP is found at \fB/tmp/pg_autoctl/data/pgsql/pg_autoctl.pid\fP,
written in a specific text format.
.sp
The PID file is located in a temporary directory by default, or in the
\fBXDG_RUNTIME_DIR\fP directory when this is setup.
.SH OPTIONS
.INDENT 0.0
.TP
.B  \-\-pgdata
Location of the Postgres node being managed locally. Defaults to the
environment variable \fBPGDATA\fP\&. Use \fB\-\-monitor\fP to connect to a monitor
from anywhere, rather than the monitor URI used by a local Postgres node
managed with \fBpg_autoctl\fP\&.
.TP
.B  \-\-all
List all the files that belong to this \fIpg_autoctl\fP node.
.TP
.B  \-\-config
Show only the configuration file.
.TP
.B  \-\-state
Show only the state file.
.TP
.B  \-\-init
Show only the init state file, which only exists while the command
\fBpg_autoctl create postgres\fP or the command \fBpg_autoctl create
monitor\fP is running, or when than command failed (and can then be
retried).
.TP
.B  \-\-pid
Show only the pid file.
.TP
.B  \-\-contents
When one of the options to show a specific file is in use, then
\fB\-\-contents\fP shows the contents of the selected file instead of showing
its absolute file path.
.TP
.B  \-\-json
Output JSON formatted data.
.UNINDENT
.SH ENVIRONMENT
.sp
PGDATA
.INDENT 0.0
.INDENT 3.5
Postgres directory location. Can be used instead of the \fB\-\-pgdata\fP
option.
.UNINDENT
.UNINDENT
.sp
PG_AUTOCTL_MONITOR
.INDENT 0.0
.INDENT 3.5
Postgres URI to connect to the monitor node, can be used instead of the
\fB\-\-monitor\fP option.
.UNINDENT
.UNINDENT
.sp
XDG_CONFIG_HOME
.INDENT 0.0
.INDENT 3.5
The pg_autoctl command stores its configuration files in the standard
place XDG_CONFIG_HOME. See the \fI\%XDG Base Directory Specification\fP\&.
.UNINDENT
.UNINDENT
.sp
XDG_DATA_HOME
.INDENT 0.0
.INDENT 3.5
The pg_autoctl command stores its internal states files in the standard
place XDG_DATA_HOME, which defaults to \fB~/.local/share\fP\&. See the \fI\%XDG
Base Directory Specification\fP\&.
.UNINDENT
.UNINDENT
.SH EXAMPLES
.sp
The following examples are taken from a QA environment that has been
prepared thanks to the \fBmake cluster\fP command made available to the
pg_auto_failover contributors. As a result, the XDG environment variables
have been tweaked to obtain a self\-contained test:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$  tmux show\-env | grep XDG
XDG_CONFIG_HOME=/Users/dim/dev/MS/pg_auto_failover/tmux/config
XDG_DATA_HOME=/Users/dim/dev/MS/pg_auto_failover/tmux/share
XDG_RUNTIME_DIR=/Users/dim/dev/MS/pg_auto_failover/tmux/run
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Within that self\-contained test location, we can see the following examples.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ pg_autoctl show file \-\-pgdata ./node1
   File | Path
\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 Config | /Users/dim/dev/MS/pg_auto_failover/tmux/config/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.cfg
  State | /Users/dim/dev/MS/pg_auto_failover/tmux/share/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.state
   Init | /Users/dim/dev/MS/pg_auto_failover/tmux/share/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.init
    Pid | /Users/dim/dev/MS/pg_auto_failover/tmux/run/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.pid
   \(aqANY 1 (pgautofailover_standby_2, pgautofailover_standby_3)\(aq

$ pg_autoctl show file \-\-pgdata node1 \-\-state
/Users/dim/dev/MS/pg_auto_failover/tmux/share/pg_autoctl/Users/dim/dev/MS/pg_auto_failover/tmux/node1/pg_autoctl.state

$ pg_autoctl show file \-\-pgdata node1 \-\-state \-\-contents
Current Role:             primary
Assigned Role:            primary
Last Monitor Contact:     Thu Mar 18 17:32:25 2021
Last Secondary Contact:   0
pg_autoctl state version: 1
group:                    0
node id:                  1
nodes version:            0
PostgreSQL Version:       1201
PostgreSQL CatVersion:    201909212
PostgreSQL System Id:     6940955496243696337

pg_autoctl show file \-\-pgdata node1 \-\-config \-\-contents \-\-json | jq .pg_autoctl
{
  "role": "keeper",
  "monitor": "postgres://autoctl_node@localhost:5500/pg_auto_failover?sslmode=prefer",
  "formation": "default",
  "group": 0,
  "name": "node1",
  "hostname": "localhost",
  "nodekind": "standalone"
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH AUTHOR
Microsoft
.SH COPYRIGHT
Copyright (c) Microsoft Corporation. All rights reserved.
.\" Generated by docutils manpage writer.
.