Docs

docs/config.md

@@ -53,6 +53,16 @@ Here are a few working sample configs using a `/etc/ntfy/server.yml` file:
     behind-proxy: true
     ```
 
+=== "server.yml (PostgreSQL, behind proxy)"
+    ``` yaml
+    base-url: "https://ntfy.example.com"
+    listen-http: ":2586"
+    database-url: "postgres://ntfy:mypassword@db.example.com:5432/ntfy?sslmode=require"
+    attachment-cache-dir: "/var/cache/ntfy/attachments"
+    behind-proxy: true
+    auth-default-access: "deny-all"
+    ```
+
 === "server.yml (ntfy.sh config)"
     ``` yaml
     # All the things: Behind a proxy, Firebase, cache, attachments, 
@@ -137,7 +147,7 @@ no external dependencies:
 * `auth-file`: Database file for authentication and [access control](#access-control). If set, enables auth.
 * `web-push-file`: Database file for [web push](#web-push) subscriptions.
 
-### PostgreSQL
+### PostgreSQL (EXPERIMENTAL)
 As an alternative, you can configure ntfy to use PostgreSQL for **all** database-backed stores by setting the
 `database-url` option to a PostgreSQL connection string:
 
@@ -155,7 +165,11 @@ topics. To restrict access, set `auth-default-access` to `deny-all` (see [access
 
 You can also set this via the environment variable `NTFY_DATABASE_URL` or the command line flag `--database-url`.
 
-You can tune the PostgreSQL connection pool by appending query parameters to the database URL:
+The database URL supports the standard [PostgreSQL connection parameters](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS)
+as query parameters, such as `sslmode`, `connect_timeout`, `sslcert`, `sslkey`, `sslrootcert`, and `application_name`.
+See the [pgx driver documentation](https://pkg.go.dev/github.com/jackc/pgx/v5) for the full list of supported parameters.
+
+In addition, ntfy supports the following custom query parameters to tune the connection pool:
 
 | Parameter                 | Default | Description                                                                      |
 |---------------------------|---------|----------------------------------------------------------------------------------|
@@ -167,7 +181,7 @@ You can tune the PostgreSQL connection pool by appending query parameters to the
 Example:
 
 ```yaml
-database-url: "postgres://user:pass@host:5432/ntfy?pool_max_conns=50&pool_conn_max_idle_time=5m"
+database-url: "postgres://user:pass@host:5432/ntfy?sslmode=require&pool_max_conns=50&pool_conn_max_idle_time=5m"
 ```
 
 ## Message cache
@@ -1192,7 +1206,7 @@ a database to keep track of the browser's subscriptions, and an admin email addr
 - `web-push-expiry-duration` defines the duration after which unused subscriptions will expire (default is `60d`)
 
 Alternatively, you can use PostgreSQL instead of SQLite by setting `database-url`
-(see [PostgreSQL database](#postgresql-database)).
+(see [PostgreSQL database](#postgresql-experimental)).
 
 Limitations:
 

docs/releases.md

@@ -1720,4 +1720,4 @@ and the [ntfy Android app](https://github.com/binwiederhier/ntfy-android/release
 
 **Features:**
 
-* Add PostgreSQL as an alternative database backend for all stores (message cache, user manager, web push subscriptions) via `database-url` config option, using a single shared connection pool with configurable pool settings (`pool_max_conns`, `pool_max_idle_conns`, `pool_conn_max_lifetime`, `pool_conn_max_idle_time`)
+* Add experimental [PostgreSQL support](config.md#postgresql-experimental) as an alternative database backend (message cache, user manager, web push subscriptions) via `database-url` config option

server/server.yml

@@ -45,17 +45,25 @@
 # Note: Setting "database-url" implicitly enables authentication and access control.
 # The default access is "read-write" (see "auth-default-access").
 #
-# You can append connection pool parameters as query parameters:
+# The URL supports standard PostgreSQL parameters (sslmode, connect_timeout, sslcert, etc.),
+# as well as ntfy-specific connection pool parameters:
 #   pool_max_conns=10          - Maximum number of open connections (default: 10)
 #   pool_max_idle_conns=N      - Maximum number of idle connections
 #   pool_conn_max_lifetime=5m  - Maximum lifetime of a connection (Go duration)
 #   pool_conn_max_idle_time=1m - Maximum idle time of a connection (Go duration)
 #
-# database-url: "postgres://user:pass@host:5432/ntfy"
-# database-url: "postgres://user:pass@host:5432/ntfy?pool_max_conns=50"
+# See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
+# for the full list of supported PostgreSQL connection parameters.
+#
+# Examples:
+#   database-url: "postgres://user:pass@host:5432/ntfy"
+#   database-url: "postgres://user:pass@host:5432/ntfy?sslmode=require&pool_max_conns=50"
+#
+# database-url: <connection-string>
 
 # If "cache-file" is set, messages are cached in a local SQLite database instead of only in-memory.
 # This allows for service restarts without losing messages in support of the since= parameter.
+# Not required if "database-url" is set (messages are stored in PostgreSQL instead).
 #
 # The "cache-duration" parameter defines the duration for which messages will be buffered
 # before they are deleted. This is required to support the "since=..." and "poll=1" parameter.
@@ -215,6 +223,7 @@
 # - web-push-public-key is the generated VAPID public key, e.g. AA1234BBCCddvveekaabcdfqwertyuiopasdfghjklzxcvbnm1234567890
 # - web-push-private-key is the generated VAPID private key, e.g. AA2BB1234567890abcdefzxcvbnm1234567890
 # - web-push-file is a database file to keep track of browser subscription endpoints, e.g. /var/cache/ntfy/webpush.db
+#   Not required if "database-url" is set (subscriptions are stored in PostgreSQL instead).
 # - web-push-email-address is the admin email address send to the push provider, e.g. sysadmin@example.com
 # - web-push-startup-queries is an optional list of queries to run on startup
 # - web-push-expiry-warning-duration defines the duration after which unused subscriptions are sent a warning (default is 55d)