PG_AUTOCTL_SHOW_FILE(1)

📦
version 2.1 · 2 versions
, in fedora 43, fedora 44

💖 PG_AUTOCTL SHOW FILE 💖

okay bestie, welcome to pg_autoctl show file, a little command from the pg_auto_failover family 💅

✨ NAME ✨

pg_autoctl show file — literally just pg_autoctl show file, that's the name, no notes 🎀

pg_autoctl show file — this is the one that lists all of pg_autoctl's internal files for you: config, state, pid, the whole little family 🌸

🦋 SYNOPSIS 🦋

okay so this command shows you the files that pg_autoctl keeps for itself internally — its own configuration, its state, and its 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 good girl and follows the XDG Base Directory Specification, which means by default it drops its internal and configuration files in places like ~/.config/pg_autoctl and ~/.local/share/pg_autoctl 🏠✨

and yes, you can move those default XDG locations around! just use the environment variables XDG_CONFIG_HOME, XDG_DATA_HOME, and XDG_RUNTIME_DIR 🎀

also — and this is the cute part — pg_config uses sub-directories that are specific to a given PGDATA, which means you can run several Postgres nodes on the same machine 👑 super practical for testing and development purposes, though not advised for production setups, bestie, don't do it, i'm serious 😭

📁 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, written in the INI format 🍓

you can get the location of the configuration file like this:

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

and you can output its content like this:

pg_autoctl show file --config --contents --pgdata /data/pgsql
also go peek at pg_autoctl config get and pg_autoctl config set, they're the sibling commands 🫶

🧚 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. periodt. so if your state gets corrupted, go see the trouble shooting section of the documentation, not me 💀

you can get the location of the state file like this:

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

and you can output its content like this:

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 file is not intended to be written by anything else than pg_autoctl itself. if it's corrupted, trouble shooting section of the documentation, you know the vibe 😌

but also — plot twist — this initialization state file only exists during the initialization of a pg_auto_failover node. in normal operations, this file does not exist. she's a limited edition, a pop-up, here for a moment and then gone 🦋

you can get the location of the state file like this:

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

and you can output its content like this:

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 📝

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

🎀 OPTIONS 🎀

  • --pgdata — where the Postgres node being managed locally lives. 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 👑
  • --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 that 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 👀
  • --json — output JSON formatted data ✨

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

okay that's the whole page bestie, you ate it 💅✨ this was page 2.1 from Jan 18, 2025, part of the pg_auto_failover era, and honestly? iconic. go check your files, slay, and remember: don't touch the state files with your bare hands 😭💖

📦 where this page comes from