24.103. taler-merchant-dbinit(1)

24.103.1. Name

taler-merchant-dbinit - initialize Taler merchant database

24.103.2. Synopsis

taler-merchant-dbinit [–dry] [-c FILENAME | –config=‌FILENAME] [-g | –gc] [-h | –help] [-L LOGLEVEL | –loglevel=‌LOGLEVEL] [-l FILENAME | –logfile=‌FILENAME] [-r | –reset] [-v | –version]

24.103.3. Description

taler-merchant-dbinit is a command-line tool to initialize the Taler 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.

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.

If an upgrade fails, rerun taler-merchant-dbinit to complete it before restarting the services. Services refuse to start while the final upgrade steps are unfinished.

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.

-g | –gc

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.

-L LOGLEVEL | –loglevel=‌LOGLEVEL

Specifies the log level to use. Accepted values are: DEBUG, INFO, WARNING, ERROR.

-l FILENAME | –logfile=‌FILENAME

Send logging output to FILENAME.

-r | –reset

Drop tables. Dangerous, will delete all existing data in the database before creating the tables. Takes precedence over -g if both are given.

-v | –version

Print version information.

24.103.4. Exit Status

0

The requested database operation completed successfully.

1

A database connection or operation failed.

2

Dry inspection found pending initialization or upgrade work.

3

Command-line or configuration processing failed.

24.103.5. See Also

taler-merchant-httpd(1), taler-merchant-dbconfig(1), taler-merchant.conf(5).

24.103.6. Bugs

Report bugs by using https://bugs.taler.net or by sending electronic mail to <taler@gnu.org>.