kych

OAuth 2.0 API for Swiyu to enable Taler integration of Swiyu for KYC (experimental)
Log | Files | Refs | Submodules | README | LICENSE

kych-dbinit.1.rst (3789B)

      1 kych-dbinit(1)
      2 ##############
      3 
      4 .. only:: html
      5 
      6    Name
      7    ====
      8 
      9    **kych-dbinit** - initialise and upgrade the KyCH database schema
     10 
     11 
     12 Synopsis
     13 ========
     14 
     15 **kych-dbinit**
     16 [**-c** *CONFIG*]
     17 [**-L** *LEVEL*]
     18 [**-v**]
     19 [**--sql-dir** *DIR*]
     20 [**-n** \| **--dry-run**]
     21 [**--print-connection**]
     22 
     23 
     24 Description
     25 ===========
     26 
     27 **kych-dbinit** creates the ``oauth2gw`` schema that kych-oauth2-gateway(1)
     28 works on, and brings an existing one up to the patch level of the installed
     29 SQL files. Both are the same operation: every schema change is a numbered
     30 patch file, ``oauth2gw-000N.sql``, which registers itself with the
     31 ``Versioning`` bookkeeping in the ``_v`` schema, and this tool applies those
     32 patches the database does not have yet, in ascending order, each in its own
     33 transaction.
     34 
     35 It is idempotent: running it against a database that is already current
     36 changes nothing and succeeds. That is what makes it safe to run unattended,
     37 which the Debian package does from its ``postinst`` on every upgrade, so that
     38 a newly installed patch is applied before the service is restarted.
     39 
     40 It does not create the database or the role that owns it; kych-dbconfig(1)
     41 does that once, and calls this tool afterwards.
     42 
     43 
     44 Options
     45 =======
     46 
     47 **-c** *CONFIG* \| **--config=**\ *CONFIG*
     48   Use the configuration file *CONFIG*. Without it the standard search path
     49   applies, ending at ``/etc/kych/kych.conf``; see kych.conf(5). The database
     50   to act on is the ``DATABASE`` option in it.
     51 
     52 **-L** *LEVEL* \| **--log=**\ *LEVEL*
     53   Set the logging verbosity: ``ERROR``, ``WARN``, ``INFO``, ``DEBUG`` or
     54   ``TRACE``, or the numbers 1 to 5. Defaults to ``INFO``.
     55 
     56 **-v** \| **--verbose**
     57   Also log what the libraries have to say, ``sqlx`` in particular, which is
     58   the way to see the statements this tool runs.
     59 
     60 **--sql-dir=**\ *DIR*
     61   Read ``versioning.sql`` and the ``oauth2gw-*.sql`` patches from *DIR*
     62   instead of the ``SQL_DIR`` of the configuration, which defaults to
     63   ``$DATADIR/sql`` -- ``/usr/share/kych/sql`` for the Debian package.
     64 
     65 **-n** \| **--dry-run**
     66   Report which patches would be applied and change nothing. Note that in a
     67   database without the ``_v`` bookkeeping every patch is reported as pending,
     68   since there is nothing yet to say otherwise.
     69 
     70 **--print-connection**
     71   Print the connection the configuration names as ``PGDATABASE``, ``PGHOST``
     72   and ``PGPORT`` assignments for a shell to ``eval``, and exit without
     73   connecting. kych-dbconfig(1) uses this instead of parsing kych.conf(5)
     74   itself, which is what makes it work against a PostgreSQL that is not on the
     75   default port.
     76 
     77 **-h** \| **--help**
     78   Print short help.
     79 
     80 **--version**
     81   Print version information.
     82 
     83 
     84 Exit Status
     85 ===========
     86 
     87 0
     88   The database is at the latest patch level, whether or not anything had to be
     89   applied.
     90 
     91 2
     92   There is no database to work on: it does not exist, or the server is not
     93   listening where the configuration says it is. The Debian package's
     94   ``postinst`` treats this as the expected state of a first install, where
     95   kych-dbconfig(1) has not run yet, and does not fail the installation over
     96   it.
     97 
     98 1
     99   Anything else: the configuration could not be loaded, the connection was
    100   refused for a reason of its own, or a patch failed. A failing patch is
    101   rolled back, so the database keeps the patch level it had.
    102 
    103 
    104 Examples
    105 ========
    106 
    107 Apply whatever is pending, as the user the daemon runs as:
    108 
    109 .. code-block:: shell
    110 
    111    $ sudo -u kych kych-dbinit -c /etc/kych/kych.conf
    112 
    113 Check before an upgrade what it would do:
    114 
    115 .. code-block:: shell
    116 
    117    $ sudo -u kych kych-dbinit -c /etc/kych/kych.conf --dry-run
    118 
    119 
    120 See Also
    121 ========
    122 
    123 kych-dbconfig(1), kych-oauth2-gateway(1), kych-client-management(1),
    124 kych.conf(5).
    125 
    126 
    127 Bugs
    128 ====
    129 
    130 Report bugs by using https://bugs.taler.net/ or by sending electronic
    131 mail to <taler@gnu.org>.