From f204c9823001409cbc9e91606c1005c887ccc285 Mon Sep 17 00:00:00 2001
From: ibizaman <ibizaman@tiserbox.com>
Date: Mon, 29 Dec 2025 09:28:11 +0100
Subject: [PATCH] postgresql: add usage documentation

---
 docs/redirects.json                       |  6 ++++
 modules/blocks/postgresql/docs/default.md | 41 ++++++++++++++++++++---
 2 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/docs/redirects.json b/docs/redirects.json
index 988c20f..6ff0db9 100644
--- a/docs/redirects.json
+++ b/docs/redirects.json
@@ -1148,6 +1148,9 @@
   "blocks-postgresql-contract-databasebackup-all": [
     "blocks-postgresql.html#blocks-postgresql-contract-databasebackup-all"
   ],
+  "blocks-postgresql-ensures": [
+    "blocks-postgresql.html#blocks-postgresql-ensures"
+  ],
   "blocks-postgresql-options": [
     "blocks-postgresql.html#blocks-postgresql-options"
   ],
@@ -1199,6 +1202,9 @@
   "blocks-postgresql-tests": [
     "blocks-postgresql.html#blocks-postgresql-tests"
   ],
+  "blocks-postgresql-usage": [
+    "blocks-postgresql.html#blocks-postgresql-usage"
+  ],
   "blocks-restic": [
     "blocks-restic.html#blocks-restic"
   ],
diff --git a/modules/blocks/postgresql/docs/default.md b/modules/blocks/postgresql/docs/default.md
index f8dc933..5f2dbce 100644
--- a/modules/blocks/postgresql/docs/default.md
+++ b/modules/blocks/postgresql/docs/default.md
@@ -6,17 +6,46 @@ This block sets up a [PostgreSQL][] database.
 
 [postgresql]: https://www.postgresql.org/
 
-## Tests {#blocks-postgresql-tests}
+Compared to the upstream nixpkgs module, this module also sets up:
 
-Specific integration tests are defined in [`/test/blocks/postgresql.nix`](@REPO@/test/blocks/postgresql.nix).
+- Enabling TCP/IP login and also accepting password authentication from localhost with [`shb.postgresql.enableTCPIP`](#blocks-postgresql-options-shb.postgresql.enableTCPIP).
+- Enhance the `ensure*` upstream option by setting up a database's password from a password file with [`shb.postgresql.ensures`](#blocks-postgresql-options-shb.postgresql.ensures).
+- Debug logging with `auto_explain` and `pg_stat_statements` with [`shb.postgresql.debug`](#blocks-postgresql-options-shb.postgresql.debug).
 
-## Database Backup Requester Contracts {#blocks-postgresql-contract-databasebackup}
+## Usage {#blocks-postgresql-usage}
+
+### Ensure User and Database {#blocks-postgresql-ensures}
+
+Ensure a database and user exists:
+
+```nix
+shb.postgresql.ensures = [
+  {
+    username = "firefly-iii";
+    database = "firefly-iii";
+  }
+];
+```
+
+Also set up the database password from a file path:
+
+```nix
+shb.postgresql.ensures = [
+  {
+    username = "firefly-iii";
+    database = "firefly-iii";
+    passwordFile = "/run/secrets/firefly-iii_db_password";
+  }
+];
+```
+
+### Database Backup Requester Contracts {#blocks-postgresql-contract-databasebackup}
 
 This block can be backed up using the [database backup](contracts-databasebackup.html) contract.
 
 Contract integration tests are defined in [`/test/contracts/databasebackup.nix`](@REPO@/test/contracts/databasebackup.nix).
 
-### Backing up All Databases {#blocks-postgresql-contract-databasebackup-all}
+#### Backing up All Databases {#blocks-postgresql-contract-databasebackup-all}
 
 ```nix
 {
@@ -30,6 +59,10 @@ Contract integration tests are defined in [`/test/contracts/databasebackup.nix`]
 }
 ```
 
+## Tests {#blocks-postgresql-tests}
+
+Specific integration tests are defined in [`/test/blocks/postgresql.nix`](@REPO@/test/blocks/postgresql.nix).
+
 ## Options Reference {#blocks-postgresql-options}
 
 ```{=include=} options