PostgreSQL URI

=?utf-8?Q?Paul_F=C3=B6rster?= <paul.foerster@gmail.com> writes:

in https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING it says that the syntax for a PostgreSQL URI is:

postgresql://[user[:password]@][host][:port][,...][/dbname][?param1=value1&...]

What I don't understand is the [,...] part, i.e. optionally repeating argument.

You can repeat the host[:port] part, no more.

regards, tom lane

Hi Tom,

On 25. Feb, 2021, at 16:09, Tom Lane <tgl@sss.pgh.pa.us> wrote:

=?utf-8?Q?Paul_F=C3=B6rster?= <paul.foerster@gmail.com> writes:

in https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING it says that the syntax for a PostgreSQL URI is:

postgresql://[user[:password]@][host][:port][,...][/dbname][?param1=value1&...]

What I don't understand is the [,...] part, i.e. optionally repeating argument.

You can repeat the host[:port] part, no more.

I suspected this already. Still the position of the closing angle bracket behind the "host" part in the syntax is IMHO wrong in the doc.

It currently says:
postgresql://[user[:password]@][host][:port][,...][/dbname][?param1=value1&...]

But shouldn't it say instead:
postgresql://[user[:password]@][host[:port]][,...][/dbname][?param1=value1&...]

Thanks very much.

Cheers,
Paul

=?utf-8?Q?Paul_F=C3=B6rster?= <paul.foerster@gmail.com> writes:

I suspected this already. Still the position of the closing angle bracket behind the "host" part in the syntax is IMHO wrong in the doc.

Hmm. Maybe

postgresql://[user[:password]@][host[:port][,...]][/dbname][?param1=value1&...]

? Seems like that would clarify how much you can repeat.

regards, tom lane

Hi Tom,

On 25. Feb, 2021, at 16:22, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Hmm. Maybe

postgresql://[user[:password]@][host[:port][,...]][/dbname][?param1=value1&...]

? Seems like that would clarify how much you can repeat.

yes, that looks better, thanks.

Cheers,
Paul

=?utf-8?Q?Paul_F=C3=B6rster?= <paul.foerster@gmail.com> writes:

On 25. Feb, 2021, at 16:22, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Hmm. Maybe
postgresql://[user[:password]@][host[:port][,...]][/dbname][?param1=value1&...]
? Seems like that would clarify how much you can repeat.

yes, that looks better, thanks.

Experimenting, it does let you omit the host and specify a port:

$ psql -d postgresql://:5433
psql: error: could not connect to server: No such file or directory
Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5433"?

So the original syntax diagram is not wrong. We could add brackets
to clarify the repeatable part:

postgresql://[user[:password]@][[host][:port][,...]][/dbname][?param1=value1&...]

but I'm less sure that that's an improvement.

regards, tom lane

Hi Tom,

On 25. Feb, 2021, at 16:43, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Experimenting, it does let you omit the host and specify a port:

$ psql -d postgresql://:5433
psql: error: could not connect to server: No such file or directory
Is the server running locally and accepting
connections on Unix domain socket "/tmp/.s.PGSQL.5433"?

So the original syntax diagram is not wrong. We could add brackets
to clarify the repeatable part:

postgresql://[user[:password]@][[host][:port][,...]][/dbname][?param1=value1&...]

but I'm less sure that that's an improvement.

hmm, the following indeed connects me to the primary, leaving out the host part completely:

$ psql -d postgresql://:5432,:5433/postgres?target_session_attrs=read-write
psql (13.2, server 12.6)
Type "help" for help.

postgres=# select user, current_setting('data_directory');
user | current_setting
----------+----------------------
postgres | /data/pg01/cdb01b/db
(1 row)

remark: cdb01a currently is replica and cdb01b is currently primary of a local Patroni test cluster, replicating between /data/pg01/cdb01a/db and /data/pg01/cdb01b/db.

So, my suggestion is:

postgresql://[user[:password]@][[host][:port]][,...][/dbname][?param1=value1&...]

Still, I think that it's an improvement, because it makes clear that not only the port, but also the host may be repeated.

Cheers,
Paul

On 2021-Feb-25, Paul F�rster wrote:

So, my suggestion is:

postgresql://[user[:password]@][[host][:port]][,...][/dbname][?param1=value1&...]

Still, I think that it's an improvement, because it makes clear that not only the port, but also the host may be repeated.

I wonder if we shouldn't instead try to break it up in parts that can be
explained or described separately. This many brackets makes it pretty
hard to read.

We could say something like

postgresql://[userspec@][hostspec][/dbname][?paramspec]

where
userspec is user[:password]
hostspec is [[host][:port]][,...]
paramspec is param1=value1&...

which makes it easier to focus on each part separately, and we can
provide more verbose explanations or examples where needed. (Now that I
broke it up, the original line became very clear to me, but when I saw
it in isolation it was not. You need to count brackets carefully to be
able to read it.)

--
�lvaro Herrera Valdivia, Chile

Hi Alvaro,

On 26. Feb, 2021, at 15:30, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote:

We could say something like

postgresql://[userspec@][hostspec][/dbname][?paramspec]

where
userspec is user[:password]
hostspec is [[host][:port]][,...]
paramspec is param1=value1&...

which makes it easier to focus on each part separately, and we can
provide more verbose explanations or examples where needed. (Now that I
broke it up, the original line became very clear to me, but when I saw
it in isolation it was not. You need to count brackets carefully to be
able to read it.)

+1

Cheers,
Paul

Alvaro Herrera <alvherre@alvh.no-ip.org> writes:

I wonder if we shouldn't instead try to break it up in parts that can be
explained or described separately. This many brackets makes it pretty
hard to read.

We could say something like

postgresql://[userspec@][hostspec][/dbname][?paramspec]

where
userspec is user[:password]
hostspec is [[host][:port]][,...]
paramspec is param1=value1&...

+1. I think you could lose the outer brackets in hostspec in
this formulation, ie given that hostspec is already bracketed
above, it should be enough to write

hostspec is [host][:port][,...]

Also, the paramspec is under-bracketed today. Should be
more like

paramspec is param=value[&...]

regards, tom lane

Hi Tom,

On 26. Feb, 2021, at 15:51, Tom Lane <tgl@sss.pgh.pa.us> wrote:

+1. I think you could lose the outer brackets in hostspec in
this formulation, ie given that hostspec is already bracketed
above, it should be enough to write

hostspec is [host][:port][,...]

Also, the paramspec is under-bracketed today. Should be
more like

paramspec is param=value[&...]

if you remove the outer brackets of host spec, then that means that only the port may be repeated. The repeat is always meant to refer to its immediate preceding argument. The outer brackets make sure that it refers to either of both host *and* port.

This is exactly what I was initially confused about. So I consider the outer brackets essential for that.

Cheers,
Paul

On 2021-Feb-26, Paul F�rster wrote:

Hi Tom,

On 26. Feb, 2021, at 15:51, Tom Lane <tgl@sss.pgh.pa.us> wrote:

+1. I think you could lose the outer brackets in hostspec in
this formulation, ie given that hostspec is already bracketed
above, it should be enough to write

hostspec is [host][:port][,...]

if you remove the outer brackets of host spec, then that means that
only the port may be repeated. The repeat is always meant to refer to
its immediate preceding argument. The outer brackets make sure that it
refers to either of both host *and* port.

I think an easier fix is to move the repeat to the main line, i.e., make
it "hostspec[,...]" and then hostspec is only [host][:port].

Also, the paramspec is under-bracketed today. Should be
more like

paramspec is param=value[&...]

True.

--
�lvaro Herrera Valdivia, Chile
"Estoy de acuerdo contigo en que la verdad absoluta no existe...
El problema es que la mentira s� existe y tu est�s mintiendo" (G. Lama)

Alvaro Herrera <alvherre@alvh.no-ip.org> writes:

On 2021-Feb-26, Paul Förster wrote:

if you remove the outer brackets of host spec, then that means that
only the port may be repeated. The repeat is always meant to refer to
its immediate preceding argument. The outer brackets make sure that it
refers to either of both host *and* port.

I think an easier fix is to move the repeat to the main line, i.e., make
it "hostspec[,...]" and then hostspec is only [host][:port].

WFM. Who's going to write the patch? (I can, but if one of you
wants to, be my guest.)

regards, tom lane

Hi Tom,

On 26. Feb, 2021, at 17:13, Tom Lane <tgl@sss.pgh.pa.us> wrote:

WFM. Who's going to write the patch? (I can, but if one of you
wants to, be my guest.)

I don't know how to write a patch. Is there any documentation about that?

Cheers,
Paul

Hi Tom,

On 26. Feb, 2021, at 17:13, Tom Lane <tgl@sss.pgh.pa.us> wrote:

WFM. Who's going to write the patch? (I can, but if one of you
wants to, be my guest.)

as I said, I don't know how to write a patch. But I played around with diff & patch.

However, does this do when applied to https://www.postgresql.org/docs/current/libpq-connect.html? Would this be what is needed?

Hi Tom,

On 26. Feb, 2021, at 19:02, Paul Förster <paul.foerster@gmail.com> wrote:

as I said, I don't know how to write a patch. But I played around with diff & patch.

However, does this do when applied to https://www.postgresql.org/docs/current/libpq-connect.html? Would this be what is needed?

sorry, I just realized I used a redundant @ character. So here's the corrected version.

=?utf-8?Q?Paul_F=C3=B6rster?= <paul.foerster@gmail.com> writes:

sorry, I just realized I used a redundant @ character. So here's the corrected version.

Actually we need a patch against the SGML sources, not the generated
files. I took this and marked it up into SGML, and (as usual when
looking at this text, it seems) failed to resist the temptation to
do some nearby copy-editing too. Pushed at

https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=4e90052c46c7751779ed83627676ed5e74ebe6d4

BTW, I ended up leaving out the extra brackets in the hostspec.
I do not buy the argument that those are needed to clarify what
you can repeat; I think they add confusion not clarity. Besides,
the adjacent text and examples make this quite clear.

regards, tom lane

Hi Tom,

On 26. Feb, 2021, at 21:29, Tom Lane <tgl@sss.pgh.pa.us> wrote:

Actually we need a patch against the SGML sources, not the generated
files.

I didn't know this, sorry. I'm not a developer. :-)

I took this and marked it up into SGML, and (as usual when
looking at this text, it seems) failed to resist the temptation to
do some nearby copy-editing too. Pushed at

https://git.postgresql.org/gitweb/?p=postgresql.git;a=commitdiff;h=4e90052c46c7751779ed83627676ed5e74ebe6d4

thanks very much.

BTW, I ended up leaving out the extra brackets in the hostspec.
I do not buy the argument that those are needed to clarify what
you can repeat; I think they add confusion not clarity. Besides,
the adjacent text and examples make this quite clear.

ok, you have the final word. I just made a suggestion.

Cheers,
Paul