begriffs open source - ai-pg/blob - full-docs/man1/pg_isready.1

   1 '\" t
   2 .\"     Title: pg_isready
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "PG_ISREADY" "1" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 pg_isready \- check the connection status of a PostgreSQL server
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBpg_isready\fR\ 'u
  34 \fBpg_isready\fR [\fIconnection\-option\fR...] [\fIoption\fR...]
  35 .SH "DESCRIPTION"
  36 .PP
  37 pg_isready
  38 is a utility for checking the connection status of a
  39 PostgreSQL
  40 database server\&. The exit status specifies the result of the connection check\&.
  41 .SH "OPTIONS"
  42 .PP
  43 \fB\-d \fR\fB\fIdbname\fR\fR
  44 .br
  45 \fB\-\-dbname=\fR\fB\fIdbname\fR\fR
  46 .RS 4
  47 Specifies the name of the database to connect to\&. The
  48 \fIdbname\fR
  49 can be a
  50 connection string\&. If so, connection string parameters will override any conflicting command line options\&.
  51 .RE
  52 .PP
  53 \fB\-h \fR\fB\fIhostname\fR\fR
  54 .br
  55 \fB\-\-host=\fR\fB\fIhostname\fR\fR
  56 .RS 4
  57 Specifies the host name of the machine on which the server is running\&. If the value begins with a slash, it is used as the directory for the Unix\-domain socket\&.
  58 .RE
  59 .PP
  60 \fB\-p \fR\fB\fIport\fR\fR
  61 .br
  62 \fB\-\-port=\fR\fB\fIport\fR\fR
  63 .RS 4
  64 Specifies the TCP port or the local Unix\-domain socket file extension on which the server is listening for connections\&. Defaults to the value of the
  65 \fBPGPORT\fR
  66 environment variable or, if not set, to the port specified at compile time, usually 5432\&.
  67 .RE
  68 .PP
  69 \fB\-q\fR
  70 .br
  71 \fB\-\-quiet\fR
  72 .RS 4
  73 Do not display status message\&. This is useful when scripting\&.
  74 .RE
  75 .PP
  76 \fB\-t \fR\fB\fIseconds\fR\fR
  77 .br
  78 \fB\-\-timeout=\fR\fB\fIseconds\fR\fR
  79 .RS 4
  80 The maximum number of seconds to wait when attempting connection before returning that the server is not responding\&. Setting to 0 disables\&. The default is 3 seconds\&.
  81 .RE
  82 .PP
  83 \fB\-U \fR\fB\fIusername\fR\fR
  84 .br
  85 \fB\-\-username=\fR\fB\fIusername\fR\fR
  86 .RS 4
  87 Connect to the database as the user
  88 \fIusername\fR
  89 instead of the default\&.
  90 .RE
  91 .PP
  92 \fB\-V\fR
  93 .br
  94 \fB\-\-version\fR
  95 .RS 4
  96 Print the
  97 pg_isready
  98 version and exit\&.
  99 .RE
 100 .PP
 101 \fB\-?\fR
 102 .br
 103 \fB\-\-help\fR
 104 .RS 4
 105 Show help about
 106 pg_isready
 107 command line arguments, and exit\&.
 108 .RE
 109 .SH "EXIT STATUS"
 110 .PP
 111 pg_isready
 112 returns
 113 0
 114 to the shell if the server is accepting connections normally,
 115 1
 116 if the server is rejecting connections (for example during startup),
 117 2
 118 if there was no response to the connection attempt, and
 119 3
 120 if no attempt was made (for example due to invalid parameters)\&.
 121 .SH "ENVIRONMENT"
 122 .PP
 123 \fBpg_isready\fR, like most other
 124 PostgreSQL
 125 utilities, also uses the environment variables supported by
 126 libpq
 127 (see
 128 Section\ \&32.15)\&.
 129 .PP
 130 The environment variable
 131 \fBPG_COLOR\fR
 132 specifies whether to use color in diagnostic messages\&. Possible values are
 133 always,
 134 auto
 135 and
 136 never\&.
 137 .SH "NOTES"
 138 .PP
 139 It is not necessary to supply correct user name, password, or database name values to obtain the server status; however, if incorrect values are provided, the server will log a failed connection attempt\&.
 140 .SH "EXAMPLES"
 141 .PP
 142 Standard Usage:
 143 .sp
 144 .if n \{\
 145 .RS 4
 146 .\}
 147 .nf
 148 $ \fBpg_isready\fR
 149 /tmp:5432 \- accepting connections
 150 $ \fBecho $?\fR
 151 0
 152 .fi
 153 .if n \{\
 154 .RE
 155 .\}
 156 .PP
 157 Running with connection parameters to a
 158 PostgreSQL
 159 cluster in startup:
 160 .sp
 161 .if n \{\
 162 .RS 4
 163 .\}
 164 .nf
 165 $ \fBpg_isready \-h localhost \-p 5433\fR
 166 localhost:5433 \- rejecting connections
 167 $ \fBecho $?\fR
 168 1
 169 .fi
 170 .if n \{\
 171 .RE
 172 .\}
 173 .PP
 174 Running with connection parameters to a non\-responsive
 175 PostgreSQL
 176 cluster:
 177 .sp
 178 .if n \{\
 179 .RS 4
 180 .\}
 181 .nf
 182 $ \fBpg_isready \-h someremotehost\fR
 183 someremotehost:5432 \- no response
 184 $ \fBecho $?\fR
 185 2
 186 .fi
 187 .if n \{\
 188 .RE
 189 .\}
 190 .sp
 191