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