PG_ISREADY(1)

💖 pg_isready — check the connection status of a PostgreSQL server

okay bestie, so this is the pg_isready page from the PostgreSQL 14.24 docs, and honestly? it's giving "tiny utility, huge main character energy" ✨ she's a whole vibe check for your database server and she does exactly one thing but she does it flawlessly 💅

🌸 SYNOPSIS 🌸

pg_isready [connection-option...] [option...]

✨ DESCRIPTION ✨

so pg_isready is this adorable little utility that just... checks the connection status of a PostgreSQL database server 🫶 that's it, that's the job, and she ate. the actual result of the check comes back through the exit status, which is literally the whole point — so if you're scripting, this is your girl 💖

🎀 OPTIONS 🎀

• -d dbname, --dbname=dbname — tells her which database to connect to, bestie. and here's the slay part: dbname can be a connection string, and if it is, then those connection string parameters override any conflicting command line options. no cap, they win 💅
• -h hostname, --host=hostname — names the host of the machine the server is running on 🌈 and if the value starts with a slash, it gets used as the directory for the Unix-domain socket. cute little detail, love that for us.
• -p port, --port=port — the TCP port, or the local Unix-domain socket file extension, that the server is listening on for connections ✨ defaults to whatever PGPORT environment variable says, or if that's not set, the port specified at compile time — usually 5432 ⭐
• -q, --quiet — do not display the status message 🙈 super useful when you're scripting, because sometimes you just want the exit status and zero chatter, iykyk.
• -t seconds, --timeout=seconds — the max number of seconds to wait while attempting the connection before it comes back with "the server is not responding" 😭 setting it to 0 disables the timeout entirely. the default is 3 seconds.
• -U username, --username=username — connect to the database as the user username instead of the default 🦋
• -V, --version — print the pg_isready version and exit, periodt 👑
• -?, --help — show help about pg_isready command line arguments, and exit 💜

🔥 EXIT STATUS 🔥

this is the part that matters most, so pay attention bestie 👀 pg_isready returns:

• 0 to the shell if the server is accepting connections normally 🎉
• 1 if the server is rejecting connections (for example during startup) 🥲
• 2 if there was no response to the connection attempt 💀
• 3 if no attempt was made at all (for example due to invalid parameters) 🙈

🌈 ENVIRONMENT 🌈

pg_isready, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see Section 34.15) 🫶

the environment variable PG_COLOR specifies whether to use color in diagnostic messages 💖 possible values are always, auto and never.

🦋 NOTES 🦋

okay so here's the tea: it is not necessary to supply correct user name, password, or database name values to obtain the server status 👑 like, she'll still tell you what's up. BUT — and this is the important bit — if incorrect values are provided, the server will log a failed connection attempt 📝 so maybe don't spam it with nonsense unless you're fine with your logs being messy.

💜 EXAMPLES 💜

Standard usage, the classic, the icon:

$ pg_isready
/tmp:5432 - accepting connections
$ echo $?
0

Running with connection parameters to a PostgreSQL cluster in startup — she's rejecting, bless her, she's still booting:

$ pg_isready -h localhost -p 5433
localhost:5433 - rejecting connections
$ echo $?
1

Running with connection parameters to a non-responsive PostgreSQL cluster — crickets, absolutely nothing, no response:

$ pg_isready -h someremotehost
someremotehost:5432 - no response
$ echo $?
2

---

and that's the whole page, bestie 🎀 no extra lore, no secret options, just the exact same facts dressed up cute 💖 this was the pg_isready page from the PostgreSQL 14.24 docs, dated 2026 — go check your server's vibe, she's waiting 🦋✨💅