.\" 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 PERFORM FAILOVER" "1" "Nov 25, 2023" "2.1" "pg_auto_failover" .SH NAME pg_autoctl perform failover \- pg_autoctl perform failover .sp pg_autoctl perform failover \- Perform a failover for given formation and group .SH SYNOPSIS .sp This command starts a Postgres failover orchestration from the pg_auto_failover monitor: .INDENT 0.0 .INDENT 3.5 .sp .EX usage: pg_autoctl perform failover [ \-\-pgdata \-\-formation \-\-group ] \-\-pgdata path to data directory \-\-formation formation to target, defaults to \(aqdefault\(aq \-\-group group to target, defaults to 0 \-\-wait how many seconds to wait, default to 60 .EE .UNINDENT .UNINDENT .SH DESCRIPTION .sp The pg_auto_failover monitor can be used to orchestrate a manual failover, sometimes also known as a switchover. When doing so, split\-brain are prevented thanks to intermediary states being used in the Finite State Machine. .sp The \fBpg_autoctl perform failover\fP command waits until the failover is known complete on the monitor, or until the hard\-coded 60s timeout has passed. .sp The failover orchestration is done in the background by the monitor, so even if the \fBpg_autoctl perform failover\fP stops on the timeout, the failover orchestration continues at the monitor. .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 \-\-formation Formation to target for the operation. Defaults to \fBdefault\fP\&. .TP .B \-\-group Postgres group to target for the operation. Defaults to \fB0\fP, only Citus formations may have more than one group. .TP .B \-\-wait How many seconds to wait for notifications about the promotion. The command stops when the promotion is finished (a node is primary), or when the timeout has elapsed, whichever comes first. The value 0 (zero) disables the timeout and allows the command to wait forever. .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 PGHOST, PGPORT, PGDATABASE, PGUSER, PGCONNECT_TIMEOUT, ... .INDENT 0.0 .INDENT 3.5 See the \fI\%Postgres docs about Environment Variables\fP for details. .UNINDENT .UNINDENT .sp TMPDIR .INDENT 0.0 .INDENT 3.5 The pgcopydb command creates all its work files and directories in \fB${TMPDIR}/pgcopydb\fP, and defaults to \fB/tmp/pgcopydb\fP\&. .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 .INDENT 0.0 .INDENT 3.5 .sp .EX $ pg_autoctl perform failover 12:57:30 3635 INFO Listening monitor notifications about state changes in formation \(dqdefault\(dq and group 0 12:57:30 3635 INFO Following table displays times when notifications are received Time | Name | Node | Host:Port | Current State | Assigned State \-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- 12:57:30 | node1 | 1 | localhost:5501 | primary | draining 12:57:30 | node1 | 1 | localhost:5501 | draining | draining 12:57:30 | node2 | 2 | localhost:5502 | secondary | report_lsn 12:57:30 | node3 | 3 | localhost:5503 | secondary | report_lsn 12:57:36 | node3 | 3 | localhost:5503 | report_lsn | report_lsn 12:57:36 | node2 | 2 | localhost:5502 | report_lsn | report_lsn 12:57:36 | node2 | 2 | localhost:5502 | report_lsn | prepare_promotion 12:57:36 | node2 | 2 | localhost:5502 | prepare_promotion | prepare_promotion 12:57:36 | node2 | 2 | localhost:5502 | prepare_promotion | stop_replication 12:57:36 | node1 | 1 | localhost:5501 | draining | demote_timeout 12:57:36 | node3 | 3 | localhost:5503 | report_lsn | join_secondary 12:57:36 | node1 | 1 | localhost:5501 | demote_timeout | demote_timeout 12:57:36 | node3 | 3 | localhost:5503 | join_secondary | join_secondary 12:57:37 | node2 | 2 | localhost:5502 | stop_replication | stop_replication 12:57:37 | node2 | 2 | localhost:5502 | stop_replication | wait_primary 12:57:37 | node1 | 1 | localhost:5501 | demote_timeout | demoted 12:57:37 | node1 | 1 | localhost:5501 | demoted | demoted 12:57:37 | node2 | 2 | localhost:5502 | wait_primary | wait_primary 12:57:37 | node3 | 3 | localhost:5503 | join_secondary | secondary 12:57:37 | node1 | 1 | localhost:5501 | demoted | catchingup 12:57:38 | node3 | 3 | localhost:5503 | secondary | secondary 12:57:38 | node2 | 2 | localhost:5502 | wait_primary | primary 12:57:38 | node1 | 1 | localhost:5501 | catchingup | catchingup 12:57:38 | node2 | 2 | localhost:5502 | primary | primary $ pg_autoctl show state Name | Node | Host:Port | LSN | Connection | Current State | Assigned State \-\-\-\-\-\-+\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- node1 | 1 | localhost:5501 | 0/4000F50 | read\-only | secondary | secondary node2 | 2 | localhost:5502 | 0/4000F50 | read\-write | primary | primary node3 | 3 | localhost:5503 | 0/4000F50 | read\-only | secondary | secondary .EE .UNINDENT .UNINDENT .SH AUTHOR Microsoft .SH COPYRIGHT Copyright (c) Microsoft Corporation. All rights reserved. .\" Generated by docutils manpage writer. .