From 7c69a76345d1c825b21c64b28ea690bcd39725db Mon Sep 17 00:00:00 2001 From: binwiederhier Date: Fri, 20 Feb 2026 16:56:47 -0500 Subject: [PATCH] Docs --- docs/config.md | 22 ++++++++++++++++++---- docs/releases.md | 2 +- server/server.yml | 15 ++++++++++++--- 3 files changed, 31 insertions(+), 8 deletions(-) diff --git a/docs/config.md b/docs/config.md index 5216d765..52777cd8 100644 --- a/docs/config.md +++ b/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: diff --git a/docs/releases.md b/docs/releases.md index aff0483e..b5ce5f31 100644 --- a/docs/releases.md +++ b/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 diff --git a/server/server.yml b/server/server.yml index 389fae80..43cb5fb4 100644 --- a/server/server.yml +++ b/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: # 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)