docs/system-attributes/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 After every upgrade/downgrade ``db-migrator`` runs the report operation to show the
 137 contents of the db-migrator log table.
 138
 139 .. code::
 140
 141    /opt/app/policy/bin/db-migrator -s <SCHEMA NAME> -o report
 142
 143 Console output will also show the sql script command as in the example below:
 144
 145 .. code::
 146
 147    upgrade 0100-jpapdpgroup_properties.sql
 148    --------------
 149    CREATE TABLE IF NOT EXISTS jpapdpgroup_properties (name VARCHAR(120) NULL, version VARCHAR(20) NULL,
 150    PROPERTIES VARCHAR(255) NULL, PROPERTIES_KEY VARCHAR(255) NULL)
 151
 152
 153 migration schema
 154 ================
 155
 156 The migration schema contains two tables which belong to ``db-migrator``.
 157
 158 * schema_versions - table to store the schema version currently installed by ``db-migrator``
 159
 160 .. list-table::
 161    :widths: 20 20
 162    :header-rows: 1
 163
 164    * - name
 165      - version
 166    * - policyadmin
 167      - 0900
 168
 169 * policyadmin_schema_changelog - table which stores a record of each sql file that has been run
 170
 171 .. list-table::
 172    :widths: 10 40 10 10 10 20 10 20
 173    :header-rows: 1
 174
 175    * - ID
 176      - script
 177      - operation
 178      - from_version
 179      - to_version
 180      - tag
 181      - success
 182      - atTime
 183    * - 1
 184      - 0100-jpapdpgroup_properties.sql
 185      - upgrade
 186      - 0
 187      - 0800
 188      - 1309210909250800u
 189      - 1
 190      - 2021-09-13 09:09:26
 191
 192 * ID: Sequence number of the operation
 193 * script: name of the sql script which was run
 194 * operation: operation type - upgrade/downgrade
 195 * from_version: starting version
 196 * to_version: target version
 197 * tag: tag to identify operation batch
 198 * success: 1 if script succeeded and 0 if it failed
 199 * atTime: time script was run
 200
 201
 202 Partial Upgrade/Downgrade
 203 =========================
 204
 205 If an upgrade or downgrade ends with a failure status (success=0) the next time an upgrade
 206 or downgrade is run it will start from the point of failure rather than re-run scripts
 207 that succeeded. This allows the user to perform a partial upgrade or downgrade depending
 208 on their requirements.
 209
 210 Running db-migrator
 211 ===================
 212
 213 The script that runs ``db-migrator`` is part of the database configuration and is in the following directory:
 214
 215 .. code::
 216
 217    oom/kubernetes/policy/resources/config/db_migrator_policy_init.sh
 218
 219 This script is mounted from the host file system to the policy-db-migrator container.
 220 It is setup to run an upgrade by default.
 221
 222 .. code::
 223
 224    /opt/app/policy/bin/prepare_upgrade.sh ${SQL_DB}
 225    /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o upgrade
 226    rc=$?
 227    /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o report
 228    exit $rc
 229
 230 The following table describes what each line does:
 231
 232 .. list-table::
 233    :widths: 30 30
 234    :header-rows: 1
 235
 236    * - code
 237      - description
 238    * - /opt/app/policy/bin/prepare_upgrade.sh ${SQL_DB}
 239      - prepare the upgrade scripts for the <SQL_DB> schema
 240    * - /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o upgrade
 241      - run the upgrade
 242    * - rc=$?
 243      - assign the return code from db-migrator to a variable
 244    * - /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o report
 245      - run the db-migrator report for the <SQL_DB> schema
 246    * - exit $rc
 247      - exit with the return code from db-migrator
 248
 249 To alter how ``db-migrator`` is run the first two lines need to be modified.
 250 The first line can be changed to call either ``prepare_upgrade.sh`` or ``prepare_downgrade.sh``.
 251 The second line can be changed to use different input parameters for ``db-migrator`` :
 252
 253 .. list-table::
 254    :widths: 10 20 10
 255    :header-rows: 1
 256
 257    * - flag
 258      - value
 259      - required
 260    * - ``-o``
 261      - upgrade/downgrade
 262      - ``Y``
 263    * - ``-s``
 264      - ${SQL_DB}
 265      - ``Y``
 266    * - ``-f``
 267      - current version (e.g. 0800)
 268      - ``N``
 269    * - ``-t``
 270      - target version (e.g. 0900)
 271      - ``N``
 272
 273 This is an example of how a downgrade from version 0900 to version 0800 could be run:
 274
 275 .. code::
 276
 277    /opt/app/policy/bin/prepare_downgrade.sh ${SQL_DB}
 278    /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o downgrade -f 0900 -t 0800
 279    rc=$?
 280    /opt/app/policy/bin/db-migrator -s ${SQL_DB} -o report
 281    exit $rc
 282
 283 Additional Information
 284 ======================
 285 If the target version of your upgrade or downgrade is the same as the current version,
 286 no sql files are run.
 287
 288 If an upgrade is run on a database where tables already exist in the policy schema, the
 289 current schema version is set to 0800 and only sql scripts from later versions are run.
 290
 291 .. note::
 292    It is advisable to take a backup of your database prior to running this utility.
 293    Please refer to the mariadb documentation on how to do this.
 294
 295 End of Document