PG_AUTOCTL SHOW FILE(1)

📦
version 2.2 · 6 versions
, in debian trixie, ubuntu questing

💖 NAME 💖

pg_autoctl show file — bestie, this is the command that lists the pg_autoctl internal files. You know, the config, state, and pid situation. That's the whole vibe. ✨

🌸 SYNOPSIS 🌸

So this command shows 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

🦋 DESCRIPTION 🦋

The pg_autoctl command is a whole XDG girlie — it follows the XDG Base Directory Specification and drops its internal and configuration files by default in places like ~/.config/pg_autoctl and ~/.local/share/pg_autoctl. ✨

You can change those default XDG locations, no cap, by setting 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, which means you can run several Postgres nodes on the same machine. That is so practical for testing and development purposes 💅 — though lowkey not advised for production setups, bestie, I'm just saying. 🙈

📁 Configuration File 📁

The pg_autoctl configuration file for an instance serving the data directory at /data/pgsql lives at ~/.config/pg_autoctl/data/pgsql/pg_autoctl.cfg, and it's written in the INI format.

Wanna get the location of the configuration file? Run:

pg_autoctl show file --config --pgdata /data/pgsql

Wanna actually see what's inside it? Run:

pg_autoctl show file --config --contents --pgdata /data/pgsql

See also pg_autoctl config get and pg_autoctl config set. 🫶

🗂️ State File 🗂️

The pg_autoctl state file for an instance serving the data directory at /data/pgsql lives 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, go see the trouble shooting section of the documentation. Periodt. 💀

Wanna get the location of the state file? Run:

pg_autoctl show file --state --pgdata /data/pgsql

Wanna dump its contents? Run:

pg_autoctl show file --state --contents --pgdata /data/pgsql

🌱 Init State File 🌱

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

⚠️ Same energy as the state file: this one 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. 😭

Also important: this initialization state file only exists during the initialization of a pg_auto_failover node. In normal operations, this file does not exist. It's giving limited edition. 👑

Wanna get the location of the state file? Run:

pg_autoctl show file --init --pgdata /data/pgsql

Wanna dump its contents? Run:

pg_autoctl show file --init --contents --pgdata /data/pgsql

🏷️ PID File 🏷️

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

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

✨ OPTIONS ✨

  • --pgdata — 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. 🫶
  • --all — List all the files that belong to this pg_autoctl node. The whole collection, bestie. 🌈
  • --config — Show only the configuration file.
  • --state — Show only the state file.
  • --init — 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). 👀
  • --pid — Show only the pid file.
  • --contents — 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. It's the "not just where it is, but what's in it" option. 🎀
  • --json — Output JSON formatted data. For when you're piping into jq, iykyk. 💅

🌿 ENVIRONMENT 🌿

  • 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.

🔥 EXAMPLES 🔥

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"
}

👑 AUTHOR 👑

Microsoft

Copyright (c) Microsoft Corporation. All rights reserved.

And that's the whole page, bestie — this was pg_autoctl show file(1) from pg_auto_failover, version 2.2, dated Apr 07, 2025. Go show some files. Slay. 💖✨🦋

📦 where this page comes from