User-Agent: Cyrus-JMAP/3.5.0-alpha0-4526-gbc24f4957e-fm-20220105.001-gbc24f495
Mime-Version: 1.0
Message-Id: <d42e67fa-57ca-412d-8055-dca522a091db@www.fastmail.com>
In-Reply-To: 
 <164131990826.21661.14675569223855830732@wrigleys.postgresql.org>
References: <164131990826.21661.14675569223855830732@wrigleys.postgresql.org>
Date: Thu, 06 Jan 2022 21:29:16 -0300
From: "Euler Taveira" <euler@eulerto.com>
To: anatoli@rainforce.org, pgsql-docs@lists.postgresql.org
Subject: Re: pg_isready docs doesn't specify what exactly it is checking
Content-Type: multipart/alternative;
 boundary=23ab28e74d16448996dc344f83abe7e6
Archived-At: 
 <https://www.postgresql.org/message-id/d42e67fa-57ca-412d-8055-dca522a091db%40www.fastmail.com>
Precedence: bulk

--23ab28e74d16448996dc344f83abe7e6
Content-Type: text/plain

On Tue, Jan 4, 2022, at 3:11 PM, PG Doc comments form wrote:
> `pg_isready` docs don't specify how its different from a port probe - what
> does on top of checking that a port is open? Does it send some handshake
> message that a server responds to when initialization is finished?
pg_isready uses a PQping function that reports the current Postgres status. The
main advantage of pg_isready is that it uses the Postgres protocol to report
the server status. A port probe is not a sufficient step to determine if the
server is running and accepting connections. Why? A Postgres server can be
running but in a state that disallows connections such as during a startup or
crash recovery phase. pg_isready is capable of reporting such state
(PQPING_REJECT -- 1) [1].

We could include a sentence explaining that a port probe is not a sufficient
condition to successfully connect to a Postgres server because the state
machine has more than 2 states. PQping [1] already states "reports the status
of the server" and describe each state it provides. Feel free to suggest an
improvement to documentation.

> People here are telling that `pg_isready` is not reliable and that
> `pg_isready` may return when database is not actually ready
> https://github.com/docker-library/postgres/issues/880#issuecomment-1004251102
> Without further info about `pg_isready` it is not clear if it should be
> filled as a bug. Or if it should be filled as a bug only when an
> initialization script is involved.
There is no known issues with pg_isready and that report isn't clear. He says
"database and/or user wasn't available". What's the exact error message? If
there is a reproducible test case, share it here.


[1] https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PQPINGPARAMS


--
Euler Taveira
EDB   https://www.enterprisedb.com/

--23ab28e74d16448996dc344f83abe7e6
Content-Type: text/html
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE html><html><head><title></title><style type=3D"text/css">p.Mso=
Normal,p.MsoNoSpacing{margin:0}</style></head><body><div>On Tue, Jan 4, =
2022, at 3:11 PM, PG Doc comments form wrote:<br></div><blockquote type=3D=
"cite" id=3D"qt" style=3D""><div>`pg_isready` docs don't specify how its=
 different from a port probe - what<br></div><div>does on top of checkin=
g that a port is open? Does it send some handshake<br></div><div>message=
 that a server responds to when initialization is finished?<br></div></b=
lockquote><div>pg_isready uses a PQping function that reports the curren=
t Postgres status. The<br></div><div>main advantage of pg_isready is tha=
t it uses the Postgres protocol to report<br></div><div>the server statu=
s. A port probe is not a sufficient step to determine if the<br></div><d=
iv>server is running and accepting connections. Why? A Postgres server c=
an be<br></div><div>running but in a state that disallows connections su=
ch as during a startup or<br></div><div>crash recovery phase. pg_isready=
 is capable of reporting such state<br></div><div>(PQPING_REJECT -- 1) [=
1].<br></div><div><br></div><div>We could include a sentence explaining =
that a port probe is not a sufficient<br></div><div>condition to success=
fully connect to a Postgres server because the state<br></div><div>machi=
ne has more than 2 states. PQping [1] already states "reports the status=
<br></div><div>of the server" and describe each state it provides. Feel =
free to suggest an<br></div><div>improvement to documentation.<br></div>=
<div><br></div><blockquote type=3D"cite" id=3D"qt" style=3D""><div>Peopl=
e here are telling that `pg_isready` is not reliable and that<br></div><=
div>`pg_isready` may return when database is not actually ready<br></div=
><div><a href=3D"https://github.com/docker-library/postgres/issues/880#i=
ssuecomment-1004251102">https://github.com/docker-library/postgres/issue=
s/880#issuecomment-1004251102</a><br></div><div>Without further info abo=
ut `pg_isready` it is not clear if it should be<br></div><div>filled as =
a bug. Or if it should be filled as a bug only when an<br></div><div>ini=
tialization script is involved.<br></div></blockquote><div>There is no k=
nown issues with pg_isready and that report isn't clear. He says<br></di=
v><div>"database and/or user wasn't available". What's the exact error m=
essage? If<br></div><div>there is a reproducible test case, share it her=
e.<br></div><div><br></div><div><br></div><div>[1] <a href=3D"https://ww=
w.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PQPINGPARAMS">htt=
ps://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PQPINGPARA=
MS</a><br></div><div><br></div><div><br></div><div id=3D"sig112409080"><=
div class=3D"signature">--<br></div><div class=3D"signature">Euler Tavei=
ra<br></div><div class=3D"signature">EDB&nbsp;&nbsp; <a href=3D"https://=
www.enterprisedb.com/">https://www.enterprisedb.com/</a><br></div></div>=
<div><br></div></body></html>
--23ab28e74d16448996dc344f83abe7e6--