From e1cbd1d57da93fc282cd49f41129f324e457a57e Mon Sep 17 00:00:00 2001
From: Erich Blume <blume.erich@gmail.com>
Date: Sat, 14 Feb 2026 07:16:16 -0800
Subject: [PATCH] Add how-to guide for connecting to PostgreSQL via psql

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../docs-connect-to-postgres.doc.md           |  1 +
 docs/how-to/connect-to-postgres.md            | 49 +++++++++++++++++++
 docs/how-to/how-to.md                         |  6 +++
 docs/reference/services/postgresql.md         |  1 +
 4 files changed, 57 insertions(+)
 create mode 100644 docs/changelog.d/docs-connect-to-postgres.doc.md
 create mode 100644 docs/how-to/connect-to-postgres.md

diff --git a/docs/changelog.d/docs-connect-to-postgres.doc.md b/docs/changelog.d/docs-connect-to-postgres.doc.md
new file mode 100644
index 0000000..753dd0b
--- /dev/null
+++ b/docs/changelog.d/docs-connect-to-postgres.doc.md
@@ -0,0 +1 @@
+Add how-to guide for connecting to PostgreSQL as a superuser via psql.
diff --git a/docs/how-to/connect-to-postgres.md b/docs/how-to/connect-to-postgres.md
new file mode 100644
index 0000000..fb3ae86
--- /dev/null
+++ b/docs/how-to/connect-to-postgres.md
@@ -0,0 +1,49 @@
+---
+title: Connect to Postgres
+modified: 2026-02-14
+tags:
+  - how-to
+  - database
+---
+
+# Connect to Postgres
+
+How to connect to the [[postgresql]] cluster as a superuser using `psql`.
+
+## Prerequisites
+
+- `psql` installed (`brew install libpq` on macOS)
+- [1Password CLI](https://developer.1password.com/docs/cli/) (`op`) installed and signed in
+- Machine on the tailnet (e.g. [[gilbert]])
+
+## Connect
+
+```bash
+PGPASSWORD=$(op read "op://blumeops/postgres/password") psql -h pg.ops.eblu.me -U eblume -d postgres
+```
+
+This connects as the `eblume` superuser. To connect to a specific database, replace `postgres` with the database name (e.g. `miniflux`, `teslamate`).
+
+## Useful Queries
+
+```sql
+-- List databases
+\l
+
+-- List roles
+\du
+
+-- Check cluster status (CNPG)
+SELECT pg_is_in_recovery();
+
+-- Show active connections
+SELECT datname, usename, client_addr, state
+FROM pg_stat_activity
+WHERE state IS NOT NULL;
+```
+
+## Related
+
+- [[postgresql]] - Service reference
+- [[borgmatic]] - Database backup
+- [[troubleshooting]] - Cluster health checks
diff --git a/docs/how-to/how-to.md b/docs/how-to/how-to.md
index dfce173..855a0e5 100644
--- a/docs/how-to/how-to.md
+++ b/docs/how-to/how-to.md
@@ -38,6 +38,12 @@ Task-oriented instructions for common BlumeOps operations. These guides assume y
 |-------|-------------|
 | [[review-documentation]] | Periodically review and maintain documentation |
 
+## Database
+
+| Guide | Description |
+|-------|-------------|
+| [[connect-to-postgres]] | Connect to PostgreSQL as a superuser via psql |
+
 ## Operations
 
 | Guide | Description |
diff --git a/docs/reference/services/postgresql.md b/docs/reference/services/postgresql.md
index 08c1b8b..efa3b8b 100644
--- a/docs/reference/services/postgresql.md
+++ b/docs/reference/services/postgresql.md
@@ -55,6 +55,7 @@ Backed up via [[borgmatic]] `postgresql_databases` hook. Streams `pg_dump` direc
 
 ## Related
 
+- [[connect-to-postgres]] - How to connect via psql
 - [[miniflux]] - Feed reader database
 - [[teslamate]] - Vehicle data database
 - [[borgmatic]] - Database backup
-- 
2.50.1 (Apple Git-155)