commit 5a7c6f98077771e8ef649d3bbd97b0b912d2dc35
parent 7c2e8879e09270d39b8394e28d421d9a339358f2
Author: Florian Dold <dold@taler.net>
Date: Tue, 8 Sep 2026 20:50:40 +0200
manpages: document dbinit/dbconfig migration inspection
Diffstat:
6 files changed, 170 insertions(+), 0 deletions(-)
diff --git a/manpages/taler-auditor-dbconfig.1.rst b/manpages/taler-auditor-dbconfig.1.rst
@@ -13,6 +13,7 @@ Synopsis
========
**taler-auditor-dbconfig**
+[**--dry**]
[**-c** *FILENAME*]
[**-h**]
[**-n** *NAME*]
@@ -28,6 +29,22 @@ a Postgresql database for use by the GNU Taler auditor.
Its options are as follows:
+**--dry**
+ Report pending role/database creation, permission setup, and schema or
+ stored-procedure migrations without changing PostgreSQL state. Existing
+ databases are inspected by invoking the corresponding dbinit tool with
+ ``--dry`` as the configured service user. Root and the service operating
+ system account are still required, as for normal dbconfig operation.
+
+ If the database or PostgreSQL role does not exist, report its creation
+ followed by full initialization. Individual migrations are not enumerated
+ until the target can be inspected. With ``-s``, omit initialization;
+ combining ``--dry`` with ``-r`` is an error.
+
+ Output is empty when current. Exit status is 0 when current, 2 when work
+ is pending, and 1 on error. Database inspection failures are errors, not
+ evidence that a database or role is missing.
+
**-c** *FILENAME*
Write the database configuration to FILENAME. The tool
will append the required ``CONFIG`` option for the
diff --git a/manpages/taler-auditor-dbinit.1.rst b/manpages/taler-auditor-dbinit.1.rst
@@ -13,6 +13,7 @@ Synopsis
========
**taler-auditor-dbinit**
+[**--dry**]
[**-c** *FILENAME* | **--config=**\ \ *FILENAME*]
[**-g** | **--gc**]
[**-h** | **--help**]
@@ -29,8 +30,46 @@ Description
exchange database. It creates the necessary tables and indices for the
Taler exchange to operate.
+Normal initialization skips stored-procedure files whose recorded contents
+are current. Schema upgrades also refresh procedures. Databases initialized
+before content tracking was introduced require one procedure refresh.
+
+Normal initialization always executes ``versioning.sql`` under the migration
+lock. This script upgrades the shared ``_v`` metadata schema transactionally
+and records its revision in ``_v.versioning``. An already-current script
+leaves schema objects and metadata unchanged. A script with an older target
+revision preserves a newer installed revision.
+
Its options are as follows:
+**--dry**
+ Inspect pending initialization and upgrade work without modifying the
+ database. Output contains one tab-separated line per action: kind,
+ component, SQL filename or finalization statement, and reason. A current
+ database produces no output. Diagnostics go to standard error.
+
+ Inspection includes versioning-schema upgrades, numbered migrations,
+ stored-procedure updates, and unfinished deferred table setup. Table setup
+ is reported as an operation,
+ including its partition argument; migration SQL is not executed to predict
+ individual table changes.
+
+ This option has no short form. It cannot be combined with reset or
+ maintenance actions.
+
+ Exit status is 0 when current, 2 when work is pending, and 1 on inspection
+ failure. An existing empty database can be inspected; a missing database
+ or failed connection is an error. The plan describes a snapshot and does
+ not guarantee that executing the SQL will succeed.
+
+ Dry inspection compares the target revision declared in ``versioning.sql``
+ with ``_v.versioning`` without executing the script. A missing revision table
+ is treated as revision zero, including on existing databases. The script also
+ creates the stored-procedure hash registry when upgrading a legacy database.
+
+ Content hashes track files applied by these tools. They do not detect
+ manual edits to database procedures or changes made by older tools.
+
**-c** *FILENAME* \| **--config=**\ \ *FILENAME*
Use the configuration and other resources for the exchange to operate
from *FILENAME*.
diff --git a/manpages/taler-exchange-dbconfig.1.rst b/manpages/taler-exchange-dbconfig.1.rst
@@ -13,6 +13,7 @@ Synopsis
========
**taler-exchange-dbconfig**
+[**--dry**]
[**-c** *FILENAME*]
[**-h**]
[**-n** *NAME*]
@@ -28,6 +29,22 @@ a Postgresql database for use by the GNU Taler exchange.
Its options are as follows:
+**--dry**
+ Report pending role/database creation, permission setup, and schema or
+ stored-procedure migrations without changing PostgreSQL state. Existing
+ databases are inspected by invoking the corresponding dbinit tool with
+ ``--dry`` as the configured service user. Root and the service operating
+ system account are still required, as for normal dbconfig operation.
+
+ If the database or PostgreSQL role does not exist, report its creation
+ followed by full initialization. Individual migrations are not enumerated
+ until the target can be inspected. With ``-s``, omit initialization;
+ combining ``--dry`` with ``-r`` is an error.
+
+ Output is empty when current. Exit status is 0 when current, 2 when work
+ is pending, and 1 on error. Database inspection failures are errors, not
+ evidence that a database or role is missing.
+
**-c** *FILENAME*
Write the database configuration to FILENAME. The tool
will append the required ``CONFIG`` option for the
diff --git a/manpages/taler-exchange-dbinit.1.rst b/manpages/taler-exchange-dbinit.1.rst
@@ -13,6 +13,7 @@ Synopsis
========
**taler-exchange-dbinit**
+[**--dry**]
[**-a** | **--inject-auditor**]
[**-c** *FILENAME* | **--config=**\ \ *FILENAME*]
[**-d** *SCHEMA* | **--disable-customization=**\ \ *SCHEMA*]
@@ -32,8 +33,47 @@ Description
exchange database. It creates the necessary tables and indices for the
Taler exchange to operate.
+Normal initialization skips stored-procedure files whose recorded contents
+are current. Schema upgrades also refresh procedures. Databases initialized
+before content tracking was introduced require one procedure refresh.
+
+Normal initialization always executes ``versioning.sql`` under the migration
+lock. This script upgrades the shared ``_v`` metadata schema transactionally
+and records its revision in ``_v.versioning``. An already-current script
+leaves schema objects and metadata unchanged. A script with an older target
+revision preserves a newer installed revision.
+
Its options are as follows:
+**--dry**
+ Inspect pending initialization and upgrade work without modifying the
+ database. Output contains one tab-separated line per action: kind,
+ component, SQL filename or finalization statement, and reason. A current
+ database produces no output. Diagnostics go to standard error.
+
+ Inspection includes versioning-schema upgrades, numbered migrations,
+ stored-procedure updates, and unfinished deferred table setup. Table setup
+ is reported as an operation,
+ including its partition argument; migration SQL is not executed to predict
+ individual table changes.
+
+ This option has no short form. It cannot be combined with reset or
+ maintenance actions. Exchange partition options remain available;
+ they apply to pending table setup, not repartitioning existing tables.
+
+ Exit status is 0 when current, 2 when work is pending, and 1 on inspection
+ failure. An existing empty database can be inspected; a missing database
+ or failed connection is an error. The plan describes a snapshot and does
+ not guarantee that executing the SQL will succeed.
+
+ Dry inspection compares the target revision declared in ``versioning.sql``
+ with ``_v.versioning`` without executing the script. A missing revision table
+ is treated as revision zero, including on existing databases. The script also
+ creates the stored-procedure hash registry when upgrading a legacy database.
+
+ Content hashes track files applied by these tools. They do not detect
+ manual edits to database procedures or changes made by older tools.
+
**-a** \| **--inject-auditor**
Installs triggers to notify real-time auditors of relevant changes to the database state.
diff --git a/manpages/taler-merchant-dbconfig.1.rst b/manpages/taler-merchant-dbconfig.1.rst
@@ -13,6 +13,7 @@ Synopsis
========
**taler-merchant-dbconfig**
+[**--dry**]
[**-c** *FILENAME*]
[**-h**]
[**-r**]
@@ -37,6 +38,22 @@ The script does not stop/start services or make backups.
Its options are as follows:
+**--dry**
+ Report pending role/database creation, permission setup, and schema or
+ stored-procedure migrations without changing PostgreSQL state. Existing
+ databases are inspected by invoking the corresponding dbinit tool with
+ ``--dry`` as the configured service user. Root and the service operating
+ system account are still required, as for normal dbconfig operation.
+
+ If the database or PostgreSQL role does not exist, report its creation
+ followed by full initialization. Individual migrations are not enumerated
+ until the target can be inspected. With ``-s``, omit initialization;
+ combining ``--dry`` with ``-r`` is an error.
+
+ Output is empty when current. Exit status is 0 when current, 2 when work
+ is pending, and 1 on error. Database inspection failures are errors, not
+ evidence that a database or role is missing.
+
**-c** *FILENAME*
Read the database connection from FILENAME. The default is
``/etc/taler-merchant/taler-merchant.conf``; this file is not modified.
diff --git a/manpages/taler-merchant-dbinit.1.rst b/manpages/taler-merchant-dbinit.1.rst
@@ -13,6 +13,7 @@ Synopsis
========
**taler-merchant-dbinit**
+[**--dry**]
[**-c** *FILENAME* | **--config=**\ \ *FILENAME*]
[**-g** | **--gc**]
[**-h** | **--help**]
@@ -30,8 +31,44 @@ 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.
+Normal initialization skips stored-procedure files whose recorded contents
+are current. Schema upgrades also refresh procedures. Databases initialized
+before content tracking was introduced require one procedure refresh.
+
+Normal initialization always executes ``versioning.sql`` under the migration
+lock. This script upgrades the shared ``_v`` metadata schema transactionally
+and records its revision in ``_v.versioning``. An already-current script
+leaves schema objects and metadata unchanged. A script with an older target
+revision preserves a newer installed revision.
+
Its options are as follows:
+**--dry**
+ Inspect pending initialization and upgrade work without modifying the
+ database. Output contains one tab-separated line per action: kind,
+ component, SQL filename or finalization statement, and reason. A current
+ database produces no output. Diagnostics go to standard error.
+
+ Inspection includes versioning-schema upgrades, numbered migrations,
+ stored-procedure updates, and synchronization of procedures into merchant
+ instance schemas.
+
+ This option has no short form. It cannot be combined with reset or
+ maintenance actions.
+
+ Exit status is 0 when current, 2 when work is pending, and 1 on inspection
+ failure. An existing empty database can be inspected; a missing database
+ or failed connection is an error. The plan describes a snapshot and does
+ not guarantee that executing the SQL will succeed.
+
+ Dry inspection compares the target revision declared in ``versioning.sql``
+ with ``_v.versioning`` without executing the script. A missing revision table
+ is treated as revision zero, including on existing databases. The script also
+ creates the stored-procedure hash registry when upgrading a legacy database.
+
+ Content hashes track files applied by these tools. They do not detect
+ manual edits to database procedures or changes made by older tools.
+
**-c** *FILENAME* \| **--config=**\ \ *FILENAME*
Use the configuration and other resources for the merchant to operate
from *FILENAME*.
@@ -67,6 +104,9 @@ Exit Status
``1``
A database connection or operation failed.
+``2``
+ Dry inspection found pending initialization or upgrade work.
+
``3``
Command-line or configuration processing failed.
