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