taler-docs

Documentation for GNU Taler components, APIs and protocols
Log | Files | Refs | README | LICENSE

taler-merchant-dbconfig.1.rst (2973B)

      1 taler-merchant-dbconfig(1)
      2 ##########################
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **taler-merchant-dbconfig** - configure Taler merchant database
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **taler-merchant-dbconfig**
     16 [**--dry**]
     17 [**-c** *FILENAME*]
     18 [**-h**]
     19 [**-r**]
     20 [**-s**]
     21 [**-u** *USER*]
     22 
     23 Description
     24 ===========
     25 
     26 **taler-merchant-dbconfig** is a simple shell script that configures
     27 the default local PostgreSQL cluster for use by the GNU Taler merchant.
     28 It creates missing roles/databases and initializes or migrates the schema by
     29 running **taler-merchant-dbinit** as the selected user. Existing data is preserved
     30 unless **-r** is specified. Run it as root, after stopping all Merchant services
     31 and backing up the database when upgrading.
     32 
     33 Only connections of the form ``postgres:///NAME`` are supported, with letters,
     34 digits, underscores, dots or hyphens in NAME. For remote databases or other
     35 connection forms, provision the database separately and invoke
     36 **taler-merchant-dbinit** with the correct configuration and database identity.
     37 The script does not stop/start services or make backups.
     38 
     39 Its options are as follows:
     40 
     41 **--dry**
     42    Report pending role/database creation, permission setup, and schema or
     43    stored-procedure migrations without changing PostgreSQL state. Existing
     44    databases are inspected by invoking the corresponding dbinit tool with
     45    ``--dry`` as the configured service user. Root and the service operating
     46    system account are still required, as for normal dbconfig operation.
     47 
     48    If the database or PostgreSQL role does not exist, report its creation
     49    followed by full initialization. Individual migrations are not enumerated
     50    until the target can be inspected. With ``-s``, omit initialization;
     51    combining ``--dry`` with ``-r`` is an error.
     52 
     53    Output is empty when current. Exit status is 0 when current, 2 when work
     54    is pending, and 1 on error. Database inspection failures are errors, not
     55    evidence that a database or role is missing.
     56 
     57 **-c** *FILENAME*
     58    Read the database connection from FILENAME. The default is
     59    ``/etc/taler-merchant/taler-merchant.conf``; this file is not modified.
     60 
     61 **-h**
     62    Print short help on options.
     63 
     64 **-r**
     65    Reset any existing database. Loses all existing data. DANGEROUS.
     66 
     67 **-s**
     68    Skip database initialization. Useful if you want to run
     69    ``taler-merchant-dbinit`` manually.
     70 
     71 **-u** *USER*
     72    Specifies the existing operating-system user and database role used for
     73    ownership and migration. Defaults to ``taler-merchant-httpd``.
     74 
     75 Exit Status
     76 ===========
     77 
     78 ``0``
     79    The database was configured successfully.
     80 
     81 ``1``
     82    An argument, prerequisite, permission, or database operation caused setup
     83    to fail.
     84 
     85 The script may also propagate another non-zero status from a utility it
     86 invokes, such as **taler-merchant-config**.
     87 
     88 See Also
     89 ========
     90 
     91 taler-merchant-dbinit(1), taler-merchant.conf(5).
     92 
     93 Bugs
     94 ====
     95 
     96 Report bugs by using https://bugs.taler.net or by sending electronic
     97 mail to <taler@gnu.org>.