docs/db-migrator/policy-db-migrator.rst

   1 .. This work is licensed under a  Creative Commons Attribution
   2 .. 4.0 International License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 Using Policy DB Migrator
   6 ########################
   7
   8 Policy DB Migrator is a set of shell scripts used to
   9 install the database tables required to run ONAP Policy Framework.
  10
  11 .. note::
  12    Currently the Istanbul versions of the PAP and API components require
  13    ``db-migrator`` to run prior to initialization.
  14
  15 Package contents
  16 ================
  17
  18 Policy DB Migrator is run as a docker container and consists of the following scripts:
  19
  20 .. code::
  21   :number-lines:
  22
  23     prepare_upgrade.sh
  24     prepare_downgrade.sh
  25     db-migrator
  26
  27
  28 ``prepare_upgrade.sh`` is included as part of the docker image and is used
  29 to copy the upgrade sql files to the run directory.
  30 This script takes one parameter: <SCHEMA NAME>.
  31
  32 ``prepare_downgrade.sh`` is included as part of the docker image and is used
  33 to copy the downgrade sql files to the run directory.
  34 This script takes one parameter: <SCHEMA NAME>.
  35
  36 ``db-migrator`` is included as part of the docker image and is used
  37 to run either the upgrade or downgrade operation depending on user requirements.
  38 This script can take up to four parameters:
  39
  40 .. list-table::
  41    :widths: 20 20 20
  42    :header-rows: 1
  43
  44    * - Parameter Name
  45      - Parameter flag
  46      - Value (example)
  47    * - operation
  48      - -o
  49      - upgrade/downgrade/report
  50    * - schema
  51      - -s
  52      - policyadmin
  53    * - to
  54      - -t
  55      - 0800/0900
  56    * - from
  57      - -f
  58      - 0800/0900
  59
  60 The container also consists of several sql files which are used to upgrade/downgrade
  61 the policy database.
  62
  63 The following environment variables need to be set to enable ``db-migrator``
  64 to run and connect to the database.
  65
  66 .. list-table::
  67    :widths: 20 20
  68    :header-rows: 1
  69
  70    * - Name
  71      - Value (example)
  72    * - SQL_HOST
  73      - mariadb
  74    * - SQL_DB
  75      - policyadmin
  76    * - SQL_USER
  77      - policy_user
  78    * - SQL_PASSWORD
  79      - policy_user
  80    * - POLICY_HOME
  81      - /opt/app/policy
  82
  83 Prepare Upgrade
  84 ===============
  85
  86 Prior to upgrading the following script is run:
  87
  88 .. code::
  89
  90    /opt/app/policy/bin/prepare_upgrade.sh <SCHEMA NAME>
  91
  92 This will copy the upgrade files from ``/home/policy/sql`` to ``$POLICY_HOME/etc/db/migration/<SCHEMA NAME>/sql/``
  93
  94 Each individual sql file that makes up that release will be run as part of the upgrade.
  95
  96
  97 Prepare Downgrade
  98 =================
  99
 100 Prior to downgrading the following script is run:
 101 .. code::
 102
 103    /opt/app/policy/bin/prepare_downgrade.sh <SCHEMA NAME>
 104
 105 This will copy the downgrade files from ``/home/policy/sql`` to ``$POLICY_HOME/etc/db/migration/<SCHEMA NAME>/sql/``
 106
 107 Each individual sql file that makes up that release will be run as part of the downgrade.
 108
 109 Upgrade
 110 =======
 111
 112 .. code::
 113
 114    /opt/app/policy/bin/db-migrator -s <SCHEMA NAME> -o upgrade -f 0800 -t 0900
 115
 116 If the ``-f`` and ``-t`` flags are not specified, the script will attempt to run all available
 117 sql files greater than the current version.
 118
 119 The script will return either 1 or 0 depending on successful completion.
 120
 121 Downgrade
 122 =========
 123
 124 .. code::
 125
 126    /opt/app/policy/bin/db-migrator -s <SCHEMA NAME> -o downgrade -f 0900 -t 0800
 127
 128 If the ``-f`` and ``-t`` flags are not specified, the script will attempt to run all available
 129 sql files less than the current version.
 130
 131 The script will return either 1 or 0 depending on successful completion.
 132
 133 Logging
 134 =======
 135
 136     .. container:: paragraph
 137
 138 After every upgrade/downgrade ``db-migrator`` runs the report operation to show the
 139 contents of the db-migrator log table.
 140
 141 .. code::
 142
 143    /opt/app/policy/bin/db-migrator -s <SCHEMA NAME> -o report
 144
 145 Console output will also show the sql script command as in the example below:
 146
 147 .. code::
 148
 149    upgrade 0100-jpapdpgroup_properties.sql
 150    --------------
 151    CREATE TABLE IF NOT EXISTS jpapdpgroup_properties (name VARCHAR(120) NULL, version VARCHAR(20) NULL,
 152    PROPERTIES VARCHAR(255) NULL, PROPERTIES_KEY VARCHAR(255) NULL)
 153
 154
 155 migration schema
 156 ================
 157
 158 The migration schema contains two tables which belong to ``db-migrator``.
 159
 160 * schema_versions - table to store the schema version currently installed by ``db-migrator``
 161
 162 .. list-table::
 163    :widths: 20 20
 164    :header-rows: 1
 165
 166    * - name
 167      - version
 168    * - policyadmin
 169      - 0900
 170
 171 * policyadmin_schema_changelog - table which stores a record of each sql file that has been run
 172
 173 .. list-table::
 174    :widths: 10 40 10 10 10 20 10 20
 175    :header-rows: 1
 176
 177    * - ID
 178      - script
 179      - operation
 180      - from_version
 181      - to_version
 182      - tag
 183      - success
 184      - atTime
 185    * - 1
 186      - 0100-jpapdpgroup_properties.sql
 187      - upgrade
 188      - 0
 189      - 0800
 190      - 1309210909250800u
 191      - 1
 192      - 2021-09-13 09:09:26
 193
 194 * ID: Sequence number of the operation
 195 * script: name of the sql script which was run
 196 * operation: operation type - upgrade/downgrade
 197 * from_version: starting version
 198 * to_version: target version
 199 * tag: tag to identify operation batch
 200 * success: 1 if script succeeded and 0 if it failed
 201 * atTime: time script was run
 202
 203
 204 Partial Upgrade/Downgrade
 205 =========================
 206
 207 If an upgrade or downgrade ends with a failure status (success=0) the next time an upgrade
 208 or downgrade is run it will start from the point of failure rather than re-run scripts
 209 that succeeded. This allows the user to perform a partial upgrade or downgrade depending
 210 on their requirements.
 211
 212 Running db-migrator
 213 ===================
 214
 215 The script that runs ``db-migrator`` is part of the database configuration and is in the following directory:
 216
 217 .. code::
 218
 219    oom/kubernetes/policy/resources/config/db_migrator_policy_init.sh
 220
 221 This script is mounted from the host file system to the policy-db-migrator container.
 222 It is setup to run an upgrade by default.
 223
 224 .. code::
 225
 226    /opt/app/policy/bin/prepare_upgrade.sh ${SQL_DB}
 227    /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o upgrade
 228    rc=$?
 229    /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o report
 230    exit $rc
 231
 232 The following table describes what each line does:
 233
 234 .. list-table::
 235    :widths: 30 30
 236    :header-rows: 1
 237
 238    * - code
 239      - description
 240    * - /opt/app/policy/bin/prepare_upgrade.sh ${SQL_DB}
 241      - prepare the upgrade scripts for the <SQL_DB> schema
 242    * - /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o upgrade
 243      - run the upgrade
 244    * - rc=$?
 245      - assign the return code from db-migrator to a variable
 246    * - /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o report
 247      - run the db-migrator report for the <SQL_DB> schema
 248    * - exit $rc
 249      - exit with the return code from db-migrator
 250
 251 To alter how ``db-migrator`` is run the first two lines need to be modified.
 252 The first line can be changed to call either ``prepare_upgrade.sh`` or ``prepare_downgrade.sh``.
 253 The second line can be changed to use different input parameters for ``db-migrator`` :
 254
 255 .. list-table::
 256    :widths: 10 20 10
 257    :header-rows: 1
 258
 259    * - flag
 260      - value
 261      - required
 262    * - ``-o``
 263      - upgrade/downgrade
 264      - ``Y``
 265    * - ``-s``
 266      - ${SQL_DB}
 267      - ``Y``
 268    * - ``-f``
 269      - current version (e.g. 0800)
 270      - ``N``
 271    * - ``-t``
 272      - target version (e.g. 0900)
 273      - ``N``
 274
 275 This is an example of how a downgrade from version 0900 to version 0800 could be run:
 276
 277 .. code::
 278
 279    /opt/app/policy/bin/prepare_downgrade.sh ${SQL_DB}
 280    /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o downgrade -f 0900 -t 0800
 281    rc=$?
 282    /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o report
 283    exit $rc
 284
 285 Additional Information
 286 ======================
 287 If the target version of your upgrade or downgrade is the same as the current version,
 288 no sql files are run.
 289
 290 If an upgrade is run on a database where tables already exist in the policy schema, the
 291 current schema version is set to 0800 and only sql scripts from later versions are run.
 292
 293 .. note::
 294    It is advisable to take a backup of your database prior to running this utility.
 295    Please refer to the mariadb documentation on how to do this.
 296
 297 End of Document