taler-exchange-dbinit(1)

24.61. taler-exchange-dbinit(1)#

24.61.1. Name#

taler-exchange-dbinit - initialize Taler exchange database

24.61.2. Synopsis#

24.61.3. Description#

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

Stop the services before upgrading the database. If an upgrade fails, rerun taler-exchange-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 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.

-c FILENAME | –config=‌FILENAME

Use the configuration and other resources for the exchange to operate from FILENAME.

-d SCHEMA | –disable-customization=‌SCHEMA

Remove rules from a customization schema from an exchange database. Note that doing so may result in an irrevocable loss of statistics, depending on how the rules are written.

-e SCHEMA | –enable-customization=‌SCHEMA

Load a customization schema to inject deployment-specific rules into an exchange database. Used to add operator-specific AML rules and statistics via triggers defined in their own schema.

-g | –gc

Garbage collect database. Deletes all unnecessary data in the database. Requires an initialized, current schema and does not apply migrations or reload stored procedures. If migration is pending, exits with a diagnostic and a nonzero status; run the schema upgrade explicitly before retrying GC. An explicit –reset retains precedence and recreates the schema even when combined with –gc.

-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.

-s | –shardunlock

Clears the (revolving) shards table. Needed to clear locks that may be held after a crash (of taler-exchange-aggregator or the operating system, say due to power outage) or if the AGGREGATOR_SHARD_SIZE option is changed in the configuration file.

-v | –version

Print version information.

24.61.4. See Also#

taler-exchange-httpd(1), taler-exchange-offline(1), taler-exchange-dbconfig(1), taler-exchange.conf(5).

24.61.5. Bugs#

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