Fix postgresql hostaddr semantics

* Before hostaddr was used to just be an alternative way to set `host`.
  But this is not how libpq actually behaves or intents hostaddr to be
  used.
* Instead `hostaddr` is meant to contain a numeric IP address to connect
  to, bypassing DNS lookups. This can be useful if the DNS lookups are
  slow, or if the DNS lookup has to be bypassed as the port is proxied
  to localhost for ifrastructure reasons. The TLS verification is still
  always done against the `host` parameter. Basically it allows to do
  `verify-full` on proxied ports.

Author: mbj

sqlx-postgres/src/connection/stream.rs

@@ -44,7 +44,14 @@ impl PgStream {
     pub(super) async fn connect(options: &PgConnectOptions) -> Result<Self, Error> {
         let socket_result = match options.fetch_socket() {
             Some(ref path) => net::connect_uds(path, MaybeUpgradeTls(options)).await?,
-            None => net::connect_tcp(&options.host, options.port, MaybeUpgradeTls(options)).await?,
+            None => {
+                net::connect_tcp(
+                    options.host_addr.as_ref().unwrap_or(&options.host),
+                    options.port,
+                    MaybeUpgradeTls(options),
+                )
+                .await?
+            }
         };
 
         let socket = socket_result?;

sqlx-postgres/src/options/doc.md

@@ -29,7 +29,7 @@ if a parameter is not passed in via URL, it is populated by reading
 | `password`         | `PGPASSWORD`         | Read from [`passfile`], if it exists.                       |
 | [`passfile`]       | `PGPASSFILE`         | `~/.pgpass` or `%APPDATA%\postgresql\pgpass.conf` (Windows) |
 | `host`             | `PGHOST`             | See [Note: Default Host](#note-default-host).               |
-| `hostaddr`         | `PGHOSTADDR`         | See [Note: Default Host](#note-default-host).               |
+| `hostaddr`         | `PGHOSTADDR`         | Numeric IP address, allows to overwrite DNS lookup          |
 | `port`             | `PGPORT`             | `5432`                                                      |
 | `dbname`           | `PGDATABASE`         | Unset; defaults to the username server-side.                |
 | `sslmode`          | `PGSSLMODE`          | `prefer`. See [`PgSslMode`] for details.                    |
@@ -182,4 +182,4 @@ let pool = PgPool::connect_with(opts).await?;
 [libpq-params]: https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
 [libpq-envars]: https://www.postgresql.org/docs/current/libpq-envars.html
 [rfc7468]: https://datatracker.ietf.org/doc/html/rfc7468
-[`webpki-roots`]: https://docs.rs/webpki-roots
+[`webpki-roots`]: https://docs.rs/webpki-roots

sqlx-postgres/src/options/mod.rs

@@ -16,6 +16,7 @@ mod ssl_mode;
 #[derive(Debug, Clone)]
 pub struct PgConnectOptions {
     pub(crate) host: String,
+    pub(crate) host_addr: Option<String>,
     pub(crate) port: u16,
     pub(crate) socket: Option<PathBuf>,
     pub(crate) username: String,
@@ -59,10 +60,9 @@ impl PgConnectOptions {
             .and_then(|v| v.parse().ok())
             .unwrap_or(5432);
 
-        let host = var("PGHOSTADDR")
-            .ok()
-            .or_else(|| var("PGHOST").ok())
-            .unwrap_or_else(|| default_host(port));
+        let host = var("PGHOST").ok().unwrap_or_else(|| default_host(port));
+
+        let host_addr = var("PGHOSTADDR").ok();
 
         let username = var("PGUSER").ok().unwrap_or_else(whoami::username);
 
@@ -71,6 +71,7 @@ impl PgConnectOptions {
         PgConnectOptions {
             port,
             host,
+            host_addr,
             socket: None,
             username,
             password: var("PGPASSWORD").ok(),
@@ -127,6 +128,25 @@ impl PgConnectOptions {
         self
     }
 
+    /// Sets the host address to connect to.
+    ///
+    /// This is different to the host parameter as it overwrites DNS lookups for TCP/IP
+    /// communication. This is particuarly useful when the DB port has to be
+    /// proxied to localhost for security reasons.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use sqlx_postgres::PgConnectOptions;
+    /// let options = PgConnectOptions::new()
+    ///     .host("example.com")
+    ///     .host_addr("127.0.0.1");
+    /// ```
+    pub fn host_addr(mut self, host_addr: &str) -> Self {
+        self.host_addr = Some(host_addr.to_string());
+        self
+    }
+
     /// Sets the port to connect to at the server host.
     ///
     /// The default port for PostgreSQL is `5432`.
@@ -477,6 +497,21 @@ impl PgConnectOptions {
         &self.host
     }
 
+    /// Get the current host addr.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use sqlx_postgres::PgConnectOptions;
+    /// let options = PgConnectOptions::new()
+    ///     .host("example.com")
+    ///     .host_addr("127.0.0.1");
+    /// assert_eq!(options.get_host_addr(), Some("127.0.0.1"));
+    /// ```
+    pub fn get_host_addr(&self) -> Option<&str> {
+        self.host_addr.as_deref()
+    }
+
     /// Get the server's port.
     ///
     /// # Example