fix: PgConnectOptions docs

[mbj]

Note I'm PRing this to document the current behavior, I'm not sure if it was the intention of the original author to support MORE behavior than libpq offers.

If I look at pub fn ssl_client_key(self, key: impl AsRef<Path>) -> PgConnectOptions there is no way to "set" the inline version of CertificateInput, it only accepts the file version. This potentially should be lifted for symmetry with the environment variables.

This may not be the intention? But also I seen no reason to artificially constrain sqlx-postgres to libpq behavior, in lots of scenarios (single file lambda binary) its much better to be able to set the certificate inline.

Regardless of what the desired final behavior is: This PR just documents the status quo, even if we wish to change it in the future.

Is this a breaking change?

no

[abonander]

I'm going to merge this so you get the attribution, but the release is going to have pretty significant wording changes since this could be blended better with the rest of the doc comment.

[abonander]

As it turns out, the handling of PGSSLKEY is a bit buggy and it won't actually accept a private key directly from the environment variable. That's because it only looks for -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- which wouldn't appear in a PEM encoded private key file.

I'm not sure whether to fix that or leave it as-is.

[mbj]

As it turns out, the handling of PGSSLKEY is a bit buggy and it won't actually accept a private key directly from the environment variable. That's because it only looks for -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- which wouldn't appear in a PEM encoded private key file.

I'm not sure whether to fix that or leave it as-is.

If inlining key materials via the environment is a deliberate feature and not just a feature by accident than IMO:

I think the internal representation of certs and keys has to be split to fix this. And IMO it should be fixed. We need dedicated types so we can run dedicated inference logic. Basically we'd need to add an CertificateKey type with a dedicated CertificateKey::from that would than snoop for ----BEGIN PRIVATE KEY----- and friends.

On the other hand if its not a deliberate feature and just a feature by accident: Inference logic should NOT exist and the PG* environment variables should only support whats in libpq and if we added extra logic to environment varibles these should be in SQLXPG prefixed ones.

I personally prefer that PG* env variables behave exactly as in libpq, and any supersetting should be done explicitly in SQLXPG* or similar.

[tisonkun]

As it turns out, the handling of PGSSLKEY is a bit buggy and it won't actually accept a private key directly from the environment variable. That's because it only looks for -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- which wouldn't appear in a PEM encoded private key file.

I'm not sure whether to fix that or leave it as-is.

From PostgreSQL's docs it seems that all these options only accept the param as filepath. Also the documented "system" option doesn't seem to be handled in sqlx-postgres.