From 001abe6a4d674273947d9b3356d24935f188b71d Mon Sep 17 00:00:00 2001
From: Hashim Khan <sardarhashim30@gmail.com>
Date: Thu, 23 Jul 2026 04:20:20 +0500
Subject: [PATCH] docs: document peer authentication over unix sockets

Clarify unix socket host usage and add a peer auth example so
password-less local connections are easier to discover. Fixes #1797.
---
 docs/pages/features/connecting.mdx | 36 +++++++++++++++++++++++++++---
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/docs/pages/features/connecting.mdx b/docs/pages/features/connecting.mdx
index 97b5c779f..677cd95e4 100644
--- a/docs/pages/features/connecting.mdx
+++ b/docs/pages/features/connecting.mdx
@@ -116,19 +116,49 @@ const pool = new Pool({
 
 ### Unix Domain Sockets
 
-Connections to unix sockets can also be made. This can be useful on distros like Ubuntu, where authentication is managed via the socket connection instead of a password.
+Connections to unix sockets can also be made by setting `host` to the directory that contains the PostgreSQL socket (commonly `/var/run/postgresql` or `/tmp`).
 
 ```js
 import pg from 'pg'
 const { Client } = pg
-client = new Client({
+const client = new Client({
+  host: '/cloudsql/myproject:zone:mydb',
   user: 'username',
   password: 'password',
-  host: '/cloudsql/myproject:zone:mydb',
   database: 'database_name',
 })
 ```
 
+### Peer authentication (password-less)
+
+PostgreSQL [peer authentication](https://www.postgresql.org/docs/current/auth-peer.html) allows the operating system user to authenticate to a local database without a password. Peer auth only works over a local unix socket connection, not TCP.
+
+To use it with node-postgres, point `host` at the socket directory and omit the password:
+
+```js
+import pg from 'pg'
+const { Pool, Client } = pg
+
+const pool = new Pool({
+  host: '/var/run/postgresql',
+  database: 'mydb',
+})
+
+console.log(await pool.query('SELECT NOW()'))
+await pool.end()
+
+const client = new Client({
+  host: '/var/run/postgresql',
+  database: 'mydb',
+})
+
+await client.connect()
+console.log(await client.query('SELECT NOW()'))
+await client.end()
+```
+
+The client connects as the OS user that runs the process (unless you set `user`). This is common on Linux installs where `pg_hba.conf` uses `peer` for local connections.
+
 ## Connection URI
 
 You can initialize both a pool and a client with a connection string URI as well. This is common in environments like Heroku where the database connection string is supplied to your application dyno through an environment variable. Connection string parsing brought to you by [pg-connection-string](https://github.com/brianc/node-postgres/tree/master/packages/pg-connection-string).