From 6eea2d53231e816c0c2f5395176dccc7316b3ca3 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Mon, 13 Apr 2026 10:40:10 -0700
Subject: [PATCH] Document the permissions needed for the PostgreSQL database
 hook (#1229).

---
 NEWS                                          |  2 +
 .../configuration/data-sources/postgresql.md  | 55 +++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/NEWS b/NEWS
index c40abec7..e752c52f 100644
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,6 @@
 2.1.5.dev0
+ * #1229: Document the permissions needed for the PostgreSQL database hook:
+   https://torsion.org/borgmatic/reference/configuration/data-sources/postgresql/
  * #1289: Add mutual TLS support for the Loki monitoring hook. See the documentation for more
    information: https://torsion.org/borgmatic/reference/configuration/monitoring/loki/
  * #1292: Fix a "source directories do not exist" regression when configuration paths are relative
diff --git a/docs/reference/configuration/data-sources/postgresql.md b/docs/reference/configuration/data-sources/postgresql.md
index c1d68310..7e5e5322 100644
--- a/docs/reference/configuration/data-sources/postgresql.md
+++ b/docs/reference/configuration/data-sources/postgresql.md
@@ -13,6 +13,61 @@ postgresql_databases:
     - name: users
 ```
 
+See below for the full set of configuration options available, including
+hostname, PostgreSQL username, password, etc.
+
+
+## Permissions
+
+### Dumping
+
+In order to dump your database as part of creating a backup, the PostgreSQL user
+performing the dump needs relevant permissions. A common way to accomplish this
+is to connect as the PostgreSQL superuser, usually `postgres`. However, if you'd
+like to connect as a non-superuser, that user will need permissions to:
+
+ * connect to the database
+ * read tables and sequences
+
+Here is one way to do that with PostgreSQL 14+:
+
+```sql
+GRANT CONNECT ON DATABASE example_database TO database_user;
+GRANT pg_read_all_data TO database_user;
+```
+
+And here is an alternate way to accomplish something similar that limits read access
+to a particular schema instead of the whole cluster. Replace "public" with the
+name of the schema you're using:
+
+```sql
+GRANT CONNECT ON DATABASE example_database TO database_user;
+GRANT USAGE ON SCHEMA public TO database_user;
+-- Grant read privileges on all current and future tables in the schema.
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO database_user;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO database_user;
+-- Grant read privileges on all current and future indexes in the schema.
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO database_user;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO database_user;
+```
+
+### Restoring
+
+If you also want this user to be able to restore your database, and you're not
+restoring as the PostgreSQL superuser, then you'll need to grant write and
+`ANALYZE` permissions as well. For instance:
+
+```sql
+GRANT pg_write_all_data TO database_user;
+GRANT pg_maintain TO database_user;
+```
+
+Or you can perform schema-level grants if you prefer.
+
+For more information, see the PostgreSQL documentation on [PostgreSQL predefined
+roles](https://www.postgresql.org/docs/current/predefined-roles.html) and
+[privileges](https://www.postgresql.org/docs/current/ddl-priv.html)
+
 
 ## Full configuration