From 001abe6a4d674273947d9b3356d24935f188b71d Mon Sep 17 00:00:00 2001 From: Hashim Khan Date: Thu, 23 Jul 2026 04:20:20 +0500 Subject: [PATCH 1/2] 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). From 8a069a9da7cb73d61f6443a08e26a304046e460e Mon Sep 17 00:00:00 2001 From: Hashim Khan Date: Wed, 29 Jul 2026 18:59:20 +0500 Subject: [PATCH 2/2] docs: simplify Unix socket authentication guidance --- docs/pages/features/connecting.mdx | 36 +++--------------------------- 1 file changed, 3 insertions(+), 33 deletions(-) diff --git a/docs/pages/features/connecting.mdx b/docs/pages/features/connecting.mdx index 677cd95e4..48b3aa0cf 100644 --- a/docs/pages/features/connecting.mdx +++ b/docs/pages/features/connecting.mdx @@ -116,49 +116,19 @@ const pool = new Pool({ ### Unix Domain Sockets -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`). +Connections to unix sockets can also be made by setting `host` to the directory that contains the PostgreSQL socket (commonly `/run/postgresql` or `/tmp`). Unix sockets can support [peer authentication](https://www.postgresql.org/docs/current/auth-peer.html) without a password. ```js import pg from 'pg' const { Client } = pg -const client = new Client({ - host: '/cloudsql/myproject:zone:mydb', +client = new Client({ 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).