KBEC-00517 - CloudBees CD/RO Database Pre-Validation Tool

2 minute readKnowledge base

Issue

This document describes how to use the database pre-validation tool. This tool can check for potential database problems before taking a system down for upgrade. If you would like to use this tool, please contact CloudBees support.

Specifically, it will look at the current schema of the database which is about to be upgraded, and the target schema that you want to upgrade to, and look at the constraints that will be applied and notify you of potential issues. For example, we would want to know if we are about to apply a NotNull constraint to a column that has NULL values.

(As a caveat: this utility does not give a 100% guarantee of a successful database upgrade. There are certain upgrade conditions that this utility can not detect.)

Environment

Resolution

Pre-requisites

  1. Find out which database you are using: MySQL or something else.

    1. If MySQL, be sure to obtain the mysql-connector-java.jar file from MySQL Downloads. For licensing reasons we are not allowed to distribute it.

  2. Verify that you can you ping the database.

    1. This utility will make a direct connection to the database.

  3. Determine if CD/RO is running in clustered mode or not.

    1. This affects the command you will run.

Usage

  1. Obtain the tool db-validation-tool-jar-with-dependencies.jar for the version you want to upgrade to.

    1. Currently the tool is packaged with the installation, so you will need to install the target CD/RO version in a test environment and retrieve the file or request this file from CloudBees support.

    2. Default tool location: /opt/cloudbees/sda/server/bin/db-validation-tool-jar-with-dependencies.jar

  2. Place the pre-validator jar file in a directory accessible to the database. If using MySQL, place mysql-connector-java.jar in the same location. Ensure the following:

    1. Tool is placed where it can see the database.

    2. Read Access to files database.properties and passkey.

    3. Additionally, if you execute in a directory that has the database.properties and passkey files, you don’t need to provide those arguments in the command. If you run somewhere else then you need arguments to point to these 2 files.

    4. Default location for the above files: /opt/cloudbees/sda/conf

  3. Run the appropriate command and inspect the output:

MySQL, CD/RO is in cluster mode

java -Dloader.path=/var/tmp/mysql-connector-java-8.0.16.jar -jar db-validation-tool-jar-with-dependencies.jar --showChanges true --validate true  --zkConnectionUrl 192.168.0.30:2181

MySQL, CD/RO is NOT in cluster mode

java -Dloader.path=/var/tmp/mysql-connector-java-8.0.16.jar -jar db-validation-tool-jar-with-dependencies.jar --databaseProperties /opt/cloudbees/sda/conf/database.properties --passkey /opt/cloudbees/sda/conf/passkey --showChanges true --validate true

Other DB, CD/RO is in cluster mode

java -jar db-validation-tool-jar-with-dependencies.jar --zkConnectionUrl 192.168.0.30:2181 --showChanges true --validate true

Other DB, CD/RO is NOT in cluster mode

java -jar db-validation-tool-jar-with-dependencies.jar --databaseProperties /opt/cloudbees/sda/conf/database.properties --passkey /opt/cloudbees/sda/conf/passkey --showChanges true --validate true

Getting Help

  • If you are seeing java version incompatibility errors, you will need to obtain the jre/ folder along with the jar file from your target version’s install directory.

    • Then use the newer java version from the jre/ folder.

  • You can see the options for the tool using java -jar db-validation-tool-jar-with-dependencies.jar --help.

Tested product/plugin versions

  • CloudBees CD/RO: Available for upgrades to versions 2024.03 and onward

    • Tested upgrades starting from versions 8.0 and onward