Document the URL syntax for Unix-domain sockets when connecting to postgres

[IreneKnapp]

I have found these related issues/pull requests

I searched, but wasn't able to find any.

Description

The behavior implemented at https://docs.rs/sqlx-postgres/0.8.3/src/sqlx_postgres/options/parse.rs.html#13 is quite important to know about for anyone who relies on Unix-domain sockets. Somebody clearly wrote this feature deliberately, but the examples do not show how to construct a URL for a Unix-domain socket.

To save time in case whoever triages this doesn't have context for the code: What it does is it takes the hostname component of the URL, percent-decodes it, and if the percent-decoded string is non-empty and starts with a slash, it is used as a filesystem path pointing to a Unix-domain socket. Otherwise it's used as a DNS hostname.

This seems to have changed in a recent version; it caused a production outage for me today. It appears that the old default when the hostname is blank was to use a Unix-domain socket with the default path, and now it is to use a TCP socket to localhost.

So, for example, the old URL postgres:///lotsadata now needs to become postgres://%2frun%2fpostgresql%2f.s.PGSQL.5432/lotsadata. This is no big deal, as long as people know about it!

I'm not complaining, I'm glad that sqlx exists, but I thought you'd want to know that some of us do rely on these small details, including indirect reliance via downstream projects that have been supporting the old behavior without realizing it exists. It was quite the debugging marathon. A few words in the documentation could have helped the downstream projects to be aware of the subtlety and know to mention it in their own documentation...

[this is of course a feature request - asking for a documentation change - but I couldn't figure out how to fit the things I have to say into the feature request template, so I'm using the bug report template. sorry about that.]

Reproduction steps

Read the documentation at [1]. Observe that it does not mention Unix-domain sockets.

[1] https://docs.rs/sqlx/latest/sqlx/postgres/struct.PgConnectOptions.html

SQLx version

0.8.3

Enabled SQLx features

N/A

Database server and version

Postgres

Operating system

NixOS

Rust version

N/A

[jaskij]

FWIW, I have a mildly complicated postgres URL using UDS, and just used the same one I used with tokio-postgres.

postgres:///database_name?user=user_name&host=/run/postgresql

I do agree that in general, documentation on this is somewhat difficult to find.

[IreneKnapp]

yeah... I was eventually able to make a version with ?host=... work, but only by also specifying &port=5432. one thing that the docs could really benefit from is a specific example of a working URL that connects to postgres in its default configuration, which is the same across numerous Linux distros.

[abonander]

A PR would be greatly appreciated!