commit f4f77e5b50c77936b75816b68380638745ef87ef
parent 4c867f5f3c2ece6aca964e8913466cdc96fbb099
Author: Florian Dold <dold@taler.net>
Date: Tue, 8 Sep 2026 15:39:44 +0200
Merchant: document database upgrades
Diffstat:
4 files changed, 79 insertions(+), 31 deletions(-)
diff --git a/design-documents/102-systemd-service-restart-policy.rst b/design-documents/102-systemd-service-restart-policy.rst
@@ -277,6 +277,16 @@ a loop hides the worker's exit status and restart count from systemd. If the
worker's termination makes the service unavailable, propagate the result and
let systemd restart it.
+A failed synchronization pass is not necessarily worker termination. Keep
+recoverable API and database-operation retries inside the worker, with suitable
+backoff that resets after success. Reconnect failed sessions without discarding
+healthy clients or independent work. For example, Wise balances have independent
+polling/retry loops; Cyclos polling continues while its optional notification
+listener reconnects. The adapters' HTTP servers are separate services, so a
+worker restart does not restart HTTP serving. Propagate terminal failures such
+as an unusable closed database pool, and do not catch panics merely to relaunch
+the application.
+
Detecting crash loops
---------------------
diff --git a/manpages/taler-merchant-dbconfig.1.rst b/manpages/taler-merchant-dbconfig.1.rst
@@ -15,7 +15,6 @@ Synopsis
**taler-merchant-dbconfig**
[**-c** *FILENAME*]
[**-h**]
-[**-n** *NAME*]
[**-r**]
[**-s**]
[**-u** *USER*]
@@ -24,30 +23,37 @@ Description
===========
**taler-merchant-dbconfig** is a simple shell script that configures
-a Postgresql database for use by the GNU Taler merchant.
+the default local PostgreSQL cluster for use by the GNU Taler merchant.
+It creates missing roles/databases and initializes or migrates the schema by
+running **taler-merchant-dbinit** as the selected user. Existing data is preserved
+unless **-r** is specified. Run it as root, after stopping all Merchant services
+and backing up the database when upgrading.
+
+Only connections of the form ``postgres:///NAME`` are supported, with letters,
+digits, underscores, dots or hyphens in NAME. For remote databases or other
+connection forms, provision the database separately and invoke
+**taler-merchant-dbinit** with the correct configuration and database identity.
+The script does not stop/start services or make backups.
Its options are as follows:
**-c** *FILENAME*
- Write the database configuration to FILENAME. The tool
- will append the required ``CONFIG`` option for the
- Postgresql access to the respective file.
+ Read the database connection from FILENAME. The default is
+ ``/etc/taler-merchant/taler-merchant.conf``; this file is not modified.
**-h**
Print short help on options.
-**-n** *DBNAME*
- Use DBNAME for the name of the created database.
-
**-r**
- Reset any existing database. Looses all existing data. DANGEROUS.
+ Reset any existing database. Loses all existing data. DANGEROUS.
**-s**
Skip database initialization. Useful if you want to run
``taler-merchant-dbinit`` manually.
**-u** *USER*
- Specifies the (main) merchant user that will access the database.
+ Specifies the existing operating-system user and database role used for
+ ownership and migration. Defaults to ``taler-merchant-httpd``.
Exit Status
===========
diff --git a/manpages/taler-merchant-dbinit.1.rst b/manpages/taler-merchant-dbinit.1.rst
@@ -25,8 +25,10 @@ Description
===========
**taler-merchant-dbinit** is a command-line tool to initialize the Taler
-merchant database. It creates the necessary tables and indices for the
-Taler merchant to operate.
+merchant database. By default it applies schema patches and installs stored
+procedures. Stop all Merchant services and back up the database before upgrading.
+For the standard local Debian setup, **taler-merchant-dbconfig** invokes this
+command with the package configuration and database identity.
Its options are as follows:
@@ -35,8 +37,9 @@ Its options are as follows:
from *FILENAME*.
**-g** \| **--gc**
- Garbage collect database. Deletes all unnecessary data in the
- database.
+ Garbage collect expired data without initializing or migrating the schema
+ or replacing stored procedures. Requires a current schema; exits with status
+ 1 if the schema check or garbage collection fails.
**-h** \| **--help**
Print short help on options.
@@ -50,7 +53,7 @@ Its options are as follows:
**-r** \| **--reset**
Drop tables. Dangerous, will delete all existing data in the database
- before creating the tables.
+ before creating the tables. Takes precedence over **-g** if both are given.
**-v** \| **–version**
Print version information.
diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
@@ -571,8 +571,11 @@ DBMS-specific options to access the database.
been created, so you can just run the tool without any arguments and should
have a working database configuration.
- Please make sure you did not create a taler merchant database manually before running
- this command or it will fail with SQL errors.
+ The tool preserves an existing database unless explicitly invoked with
+ ``-r``. Existing databases must have the expected ownership and migration
+ privileges. It provisions only the default local PostgreSQL cluster; for
+ remote databases, provision the database separately and use
+ ``taler-merchant-dbinit`` with the appropriate database identity.
For the ``postgres`` backend, you need to specify:
@@ -1799,20 +1802,46 @@ Please note that upgrades are ONLY supported for released version of the
merchant. Attempting to upgrade from or to a version in Git is not supported
and may result in subtle data loss.
-To safely upgrade the merchant, you should first stop the existing
-``taler-merchant-httpd`` process, backup your merchant database (see
-PostgreSQL manual), and then install the latest version of the code.
-
-If you REVOKED database permissions, ensure that the rights to CREATE,
-DROP, and ALTER tables are GRANTed to ``$USER`` again. Then, run:
-
-.. code-block:: console
-
- $ taler-merchant-dbinit
-
-to upgrade the database to the latest schema. After that, you may again
-REVOKE the database permissions. Finally, restart the merchant services
-processes, either via your systemd or init system, or directly.
+Debian packages do not migrate the database or restart Merchant on upgrade.
+The operator must coordinate the complete upgrade; leaving old processes running
+is not a way to defer migration, since a crash or runtime limit can start newly
+installed binaries against the old database.
+
+1. Stop all Merchant services **before installing the new packages**. On Debian,
+ run ``sudo systemctl stop taler-merchant.target``. This includes workers,
+ the HTTP service and socket, and the garbage-collection timer. If multiple
+ machines share the database, stop the Merchant services on every machine.
+2. Back up the database using your PostgreSQL backup procedure.
+3. Install the new packages. Services remain stopped.
+4. Apply the migration. For the standard Debian installation using the default
+ local PostgreSQL cluster, run:
+
+ .. code-block:: console
+
+ $ sudo taler-merchant-dbconfig
+
+ This preserves the existing database and invokes ``taler-merchant-dbinit``
+ as ``taler-merchant-httpd`` with
+ ``/etc/taler-merchant/taler-merchant.conf``. Never use ``-r`` for an upgrade:
+ it deletes the existing database.
+
+ For remote databases or separately administered credentials, run
+ ``taler-merchant-dbinit -c /path/to/merchant.conf`` as the database owner
+ or designated migration identity instead. Ensure all required migration
+ privileges are available; ``dbconfig`` grants permission to set
+ ``session_replication_role`` but does not restore other revoked privileges.
+5. After migration succeeds, restore any normal-operation privilege restrictions
+ and start the desired Merchant services. Use
+ ``sudo systemctl start taler-merchant.target`` to start the complete group.
+ If migration fails, keep all Merchant services stopped while resolving it.
+
+``taler-merchant-dbconfig`` does not stop services, make backups, or restart
+services. Its successful completion only confirms the database setup/migration
+step. Installation without a configured database remains supported.
+
+Scheduled garbage collection (``taler-merchant-dbinit -g``) never initializes
+or upgrades the schema or replaces stored procedures. It requires a current
+schema and fails with a diagnostic if migration is needed.
