taler-exchange-dbinit.1.rst (5461B)
1 taler-exchange-dbinit(1) 2 ######################## 3 4 .. only:: html 5 6 Name 7 ==== 8 9 **taler-exchange-dbinit** - initialize Taler exchange database 10 11 12 Synopsis 13 ======== 14 15 **taler-exchange-dbinit** 16 [**--dry**] 17 [**-a** | **--inject-auditor**] 18 [**-c** *FILENAME* | **--config=**\ \ *FILENAME*] 19 [**-d** *SCHEMA* | **--disable-customization=**\ \ *SCHEMA*] 20 [**-e** *SCHEMA* | **--enable-customization=**\ \ *SCHEMA*] 21 [**-g** | **--gc**] 22 [**-h** | **--help**] 23 [**-L** *LOGLEVEL* | **--loglevel=**\ \ *LOGLEVEL*] 24 [**-l** *FILENAME* | **--logfile=**\ \ *FILENAME*] 25 [**-r** | **--reset**] 26 [**-s** | **--shardunlock**] 27 [**-v** | **--version**] 28 29 Description 30 =========== 31 32 **taler-exchange-dbinit** is a command-line tool to initialize the Taler 33 exchange database. It creates the necessary tables and indices for the 34 Taler exchange to operate. 35 36 Normal initialization skips stored-procedure files whose recorded contents 37 are current. Schema upgrades also refresh procedures. Databases initialized 38 before content tracking was introduced require one procedure refresh. 39 40 Normal initialization always executes ``versioning.sql`` under the migration 41 lock. This script upgrades the shared ``_v`` metadata schema transactionally 42 and records its revision in ``_v.versioning``. An already-current script 43 leaves schema objects and metadata unchanged. A script with an older target 44 revision preserves a newer installed revision. 45 46 Stop the services before upgrading the database. If an upgrade fails, rerun 47 **taler-exchange-dbinit** to complete it before restarting the services. 48 Services refuse to start while the final upgrade steps are unfinished. 49 50 Its options are as follows: 51 52 **--dry** 53 Inspect pending initialization and upgrade work without modifying the 54 database. Output contains one tab-separated line per action: kind, 55 component, SQL filename or finalization statement, and reason. A current 56 database produces no output. Diagnostics go to standard error. 57 58 Inspection includes versioning-schema upgrades, numbered migrations, 59 stored-procedure updates, and unfinished deferred table setup. Table setup 60 is reported as an operation, 61 including its partition argument; migration SQL is not executed to predict 62 individual table changes. 63 64 This option has no short form. It cannot be combined with reset or 65 maintenance actions. Exchange partition options remain available; 66 they apply to pending table setup, not repartitioning existing tables. 67 68 Exit status is 0 when current, 2 when work is pending, and 1 on inspection 69 failure. An existing empty database can be inspected; a missing database 70 or failed connection is an error. The plan describes a snapshot and does 71 not guarantee that executing the SQL will succeed. 72 73 Dry inspection compares the target revision declared in ``versioning.sql`` 74 with ``_v.versioning`` without executing the script. A missing revision table 75 is treated as revision zero, including on existing databases. The script also 76 creates the stored-procedure hash registry when upgrading a legacy database. 77 78 Content hashes track files applied by these tools. They do not detect 79 manual edits to database procedures or changes made by older tools. 80 81 **-a** \| **--inject-auditor** 82 Installs triggers to notify real-time auditors of relevant changes to the database state. 83 84 **-c** *FILENAME* \| **--config=**\ \ *FILENAME* 85 Use the configuration and other resources for the exchange to operate 86 from *FILENAME*. 87 88 **-d** *SCHEMA* \| **--disable-customization=**\ \ *SCHEMA* 89 Remove rules from a customization schema from an exchange database. 90 Note that doing so may result in an irrevocable loss of statistics, 91 depending on how the rules are written. 92 93 **-e** *SCHEMA* \| **--enable-customization=**\ \ *SCHEMA* 94 Load a customization schema to inject deployment-specific rules into an 95 exchange database. Used to add operator-specific AML rules and statistics 96 via triggers defined in their own schema. 97 98 **-g** \| **--gc** 99 Garbage collect database. Deletes all unnecessary data in the 100 database. Requires an initialized, current schema and does not apply 101 migrations or reload stored procedures. If migration is pending, exits 102 with a diagnostic and a nonzero status; run the schema upgrade explicitly 103 before retrying GC. An explicit **--reset** retains precedence and recreates 104 the schema even when combined with **--gc**. 105 106 **-h** \| **--help** 107 Print short help on options. 108 109 **-L** *LOGLEVEL* \| **--loglevel=**\ \ *LOGLEVEL* 110 Specifies the log level to use. Accepted values are: ``DEBUG``, ``INFO``, 111 ``WARNING``, ``ERROR``. 112 113 **-l** *FILENAME* \| **--logfile=**\ \ *FILENAME* 114 Send logging output to *FILENAME*. 115 116 **-r** \| **--reset** 117 Drop tables. Dangerous, will delete all existing data in the database 118 before creating the tables. 119 120 **-s** \| **--shardunlock** 121 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. 122 123 **-v** \| **–version** 124 Print version information. 125 126 See Also 127 ======== 128 129 taler-exchange-httpd(1), taler-exchange-offline(1), 130 taler-exchange-dbconfig(1), taler-exchange.conf(5). 131 132 Bugs 133 ==== 134 135 Report bugs by using https://bugs.taler.net or by sending electronic 136 mail to <taler@gnu.org>.