pig patroni

pig patroni (alias pig pt) runs the installed patronictl command. Use it to inspect cluster members, change cluster configuration, and switch the primary. PIG selects the configuration file and provides local service, status, and log commands. Other commands use patronictl’s arguments, prompts, output, and exit codes.

Install Patroni and configure access to its cluster before running cluster operations. Use pig pt COMMAND --help for native command help, or pig pt -- --help for patronictl root help. Running pig pt alone shows PIG’s help.

Command Overview

Forwarded commands (native patronictl):

Put the cluster name before member names. These commands use the installed patronictl interface.

Local commands (implemented by PIG):

Use pig pt restart CLUSTER to restart PostgreSQL through Patroni. Use pig pt svc restart to restart the local Patroni daemon.

Inspect a cluster

On a configured Patroni node, inspect the cluster members and dynamic configuration. Replace pg-meta with your cluster name:

pig pt list pg-meta
pig pt show-config pg-meta

Use pig pt status to inspect the local service and pig pt log -f to follow its logs.

PIG options

These PIG options must precede the native command; once the native command token appears, all remaining tokens belong to patronictl:

pig pt -c /path/patroni.yml list pg-meta   # PIG -c: config file
pig pt query -c 'select 1'                 # native query -c: SQL

Use the full --dbsu option; pig pt has no -U shorthand.

Config-File Resolution

PIG selects the patronictl configuration file in this order:

1. explicit -c/--config-file given before the command;
2. non-empty PATRONICTL_CONFIG_FILE environment variable;
3. /etc/patroni/patroni.yml (exists and readable as the DBSU);
4. /infra/conf/patronictl.yml (exists and readable as the DBSU);
5. otherwise /etc/patroni/patroni.yml; patronictl reports a missing file.

PIG uses an explicit path or environment path even if the file is missing or unreadable. It resolves relative paths before switching operating-system user. It checks the two conventional paths as the selected user. Service commands and native help do not need a configuration file.

Command dispatch and output

PIG handles the local commands listed above. It forwards any other command and every argument after that command to patronictl. Put PIG options before the native command:

pig pt -c /etc/patroni/patroni.yml list pg-meta
pig pt list pg-meta --format json

Native commands keep interactive prompts, editor sessions, streamed output, and exit codes. Use the native --format json option for JSON. PIG’s -o json and -o yaml cannot format these commands and are rejected before the native command token.

Use pig pt -- COMMAND ... to forward a command whose name matches a local command. The local set, status, and service commands support PIG structured output. Log output has the formats described below.

pt set

pt set updates the cluster selected by the configuration file:

pig pt set KEY=VALUE [KEY=VALUE ...] [--yes] [--plan]

Key classification:

• These scalar Patroni dynamic keys translate to native --set: loop_wait, ttl, retry_timeout, primary_race_backoff, maximum_lag_on_failover, maximum_lag_on_syncnode, max_timelines_history, primary_start_timeout, primary_stop_timeout, synchronous_mode, synchronous_mode_strict, synchronous_node_count, failsafe_mode, check_timeline, member_slots_ttl (pause is deliberately excluded — use native pause/resume);
• every other key is treated as a PostgreSQL parameter and translates to native --pg (including dotted custom GUCs like timescaledb.telemetry_level);
• structural keys starting with postgresql., standby_cluster., slots., or ignore_slots. are rejected, pointing to native pig pt edit-config --set.

All pairs merge into one native edit-config call in input order — one configuration diff and one confirmation:

pig pt set ttl=60 max_connections=200 synchronous_mode=on
# equivalent: patronictl -c <selected> edit-config --set ttl=60 --pg max_connections=200 --set synchronous_mode=on

• --yes/-y appends native --force to skip confirmation; otherwise patronictl shows the diff and owns confirmation;
• --plan mutates nothing and renders the selected config plus the translated native command (including the values you supplied);
• in structured output mode, execution requires an explicit --yes;
• values parse as YAML: both KEY=null and KEY= remove a key, passed unchanged;
• after changing restart-required PostgreSQL parameters, PIG suggests the follow-up: first pig pt list, then pig pt restart CLUSTER --pending (explicit cluster required).

Service Management

pt service (alias pt svc) manages the local patroni systemd unit:

pt start / pt stop (aliases up / dn) call the same service actions. Stopping the Patroni service may also stop PostgreSQL on this node (depending on Patroni configuration).

pt status

Shows combined status: systemd service state, Patroni process info, and cluster members from patronictl.

pig pt status
pig pt st -o json                # structured output

pt log

View local Patroni logs. The log directory comes from log.dir in the selected config, falling back to /pg/log/patroni, or set it explicitly with --log-dir. Only pt log and pt log show support -o json (JSONL snapshot); -f, tail, and grep use text output. Log snapshots do not support YAML or json-pretty.

pig pt log                     # show last 50 lines
pig pt log -f                  # follow log output
pig pt log -n 100              # show last 100 lines
pig pt log show -o json        # JSONL snapshot
pig pt log tail -n 100         # follow logs
pig pt log grep ERROR          # search logs

Migrating from v1.5.x

When upgrading from v1.5.x, update older scripts to use patronictl syntax:

Requirements and privileges

Service commands require Linux and systemd. Log commands need readable Patroni log files. PIG runs patronictl as the operating-system user selected by --dbsu, then $PIG_DBSU, then postgres. It executes directly as that user, uses su from root, or uses sudo -H -u from another account. Service management uses root privileges.

Design record

Let Patronictl Speak for Itself records why PIG stopped mirroring the upstream command tree and which local responsibilities remain.