DOKK / manpages / debian 12 / pg-auto-failover-cli / pg_autoctl show file.1.en
PG_AUTOCTL SHOW FILE(1) pg_auto_failover PG_AUTOCTL SHOW FILE(1)

pg_autoctl show file - pg_autoctl show file

pg_autoctl show file - List pg_autoctl internal files (config, state, pid)

This command the files that pg_autoctl uses internally for its own configuration, state, and pid:

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


The pg_autoctl command follows the XDG Base Directory Specification and places its internal and configuration files by default in places such as ~/.config/pg_autoctl and ~/.local/share/pg_autoctl.

It is possible to change the default XDG locations by using the environment variables XDG_CONFIG_HOME, XDG_DATA_HOME, and XDG_RUNTIME_DIR.

Also, pg_config uses sub-directories that are specific to a given PGDATA, 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.

The pg_autoctl configuration file for an instance serving the data directory at /data/pgsql is found at ~/.config/pg_autoctl/data/pgsql/pg_autoctl.cfg, written in the INI format.

It is possible to get the location of the configuration file by using the command pg_autoctl show file --config --pgdata /data/pgsql and to output its content by using the command pg_autoctl show file --config --contents --pgdata /data/pgsql.

See also pg_autoctl config get and pg_autoctl config set.

The pg_autoctl state file for an instance serving the data directory at /data/pgsql is found at ~/.local/share/pg_autoctl/data/pgsql/pg_autoctl.state, written in a specific binary format.

This file is not intended to be written by anything else than pg_autoctl itself. In case of state corruption, see the trouble shooting section of the documentation.

It is possible to get the location of the state file by using the command pg_autoctl show file --state --pgdata /data/pgsql and to output its content by using the command pg_autoctl show file --state --contents --pgdata /data/pgsql.

The pg_autoctl init state file for an instance serving the data directory at /data/pgsql is found at ~/.local/share/pg_autoctl/data/pgsql/pg_autoctl.init, written in a specific binary format.

This file is not intended to be written by anything else than pg_autoctl itself. In case of state corruption, see the trouble shooting section of the documentation.

This initialization state file only exists during the initialization of a pg_auto_failover node. In normal operations, this file does not exist.

It is possible to get the location of the state file by using the command pg_autoctl show file --init --pgdata /data/pgsql and to output its content by using the command pg_autoctl show file --init --contents --pgdata /data/pgsql.

The pg_autoctl PID file for an instance serving the data directory at /data/pgsql is found at /tmp/pg_autoctl/data/pgsql/pg_autoctl.pid, written in a specific text format.

The PID file is located in a temporary directory by default, or in the XDG_RUNTIME_DIR directory when this is setup.

Location of the Postgres node being managed locally. Defaults to the environment variable PGDATA. Use --monitor to connect to a monitor from anywhere, rather than the monitor URI used by a local Postgres node managed with pg_autoctl.
List all the files that belong to this pg_autoctl node.
Show only the configuration file.
Show only the state file.
Show only the init state file, which only exists while the command pg_autoctl create postgres or the command pg_autoctl create monitor is running, or when than command failed (and can then be retried).
Show only the pid file.
When one of the options to show a specific file is in use, then --contents shows the contents of the selected file instead of showing its absolute file path.
Output JSON formatted data.

PGDATA

Postgres directory location. Can be used instead of the --pgdata option.


PG_AUTOCTL_MONITOR

Postgres URI to connect to the monitor node, can be used instead of the --monitor option.


XDG_CONFIG_HOME

The pg_autoctl command stores its configuration files in the standard place XDG_CONFIG_HOME. See the XDG Base Directory Specification.


XDG_DATA_HOME

The pg_autoctl command stores its internal states files in the standard place XDG_DATA_HOME, which defaults to ~/.local/share. See the XDG Base Directory Specification.


The following examples are taken from a QA environment that has been prepared thanks to the make cluster 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:

$  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


Within that self-contained test location, we can see the following examples.

$ 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


   'ANY 1 (pgautofailover_standby_2, pgautofailover_standby_3)'
$ 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"
}


Microsoft

Copyright (c) Microsoft Corporation. All rights reserved.

November 6, 2022 2.0