Built-in database schema on disk is older than required for upgrade

Description

During an upgrade, the installer displays the following error prompt:

CloudBees Flow is configured to use the built-in database. The built-in
database on disk has a schema intended for CloudBees Flow version
<version>, which is older than that needed by this CloudBees Flow
<version> server. CloudBees Flow does not support version upgrades of
the built-in database, so the CloudBees Flow server cannot start. For
options to resolve this issue, see the "Troubleshooting" chapter of
the "CloudBees Flow Installation Guide".

This problem occurs because starting with CloudBees Flow version 8.0, CloudBees does not support upgrades from CloudBees Flow versions that use HSQLDB. HSQLDB is the built-in (default) database that was replaced by MariaDB in CloudBees Flow version 8.3 as the built-in database.

Workarounds

Because the HSQLDB database in CloudBees Flow is not upgradeable, to work around this issue, you can either point to a supported database, wipe the database (if you do not need its contents), or migrate the database contents to a database supported by CloudBees Flow.

Pointing to a supported database

To point to a different CloudBees Flow-supported database, modify the database.properties file to point to that database.

Wiping the database contents

If you do not need the contents of the built-in database, complete the following steps:

  1. Back up the database.

    For details, see CloudBees Flow Server Backups .

  2. Delete the files and folders whose names match the pattern:

    <DATA_DIR>/builtin/commander.*

Migrating the database contents to a supported database

If you do need the contents of the built-in database, complete the following steps:

  • Back up your <DATA_DIR>\builtin folder and your <DATA_DIR>\conf\database.properties, passkey, and keystore files (or simply back up the entire <DATA_DIR>\conf folder).

  • Reinstall the prior CloudBees Flow version by using the following substeps:

    1. Uninstall the newer instance that is not working.

    2. Install the prior version again, which will use a new built-in database by default.

      If you installed the DevOps Insight server on the same system, you must use a different <INSTALL_DIR> and <DATA_DIR> for this CloudBees Flow server installation.
    3. After the CommanderServer service starts (meaning that the plugins are installed and so on) and you can log into the installed version from substep b, stop the CommanderServer service.

    4. Back up the new <DATA_DIR>\builtin and <DATA_DIR>\conf folders and replace them with the folders that you backed up in step 1.

    5. Restart the new CommanderServer service. It should now use the original built-in database containing your data and should function properly.

  • Do a full export of the database contents.

    For details, see CloudBees Flow Server Backups .

  • Switch to another production-quality database that CloudBees Flow supports.

  • Do a full import of your data to the new database.

    For details, see CloudBees Flow Server Restores .

  • Re-upgrade CloudBees Flow.

Copyright © 2010-2020 CloudBees, Inc.Online version published by CloudBees, Inc. under the Creative Commons Attribution-ShareAlike 4.0 license.CloudBees and CloudBees DevOptics are registered trademarks and CloudBees Core, CloudBees Flow, CloudBees Flow Deploy, CloudBees Flow DevOps Insight, CloudBees Flow DevOps Foresight, CloudBees Flow Release, CloudBees Accelerator, CloudBees Accelerator ElectricInsight, CloudBees Accelerator Electric Make, CloudBees CodeShip, CloudBees Jenkins Enterprise, CloudBees Jenkins Platform, CloudBees Jenkins Operations Center, and DEV@cloud are trademarks of CloudBees, Inc. Most CloudBees products are commonly referred to by their short names — Accelerator, Automation Platform, Flow, Deploy, Foresight, Release, Insight, and eMake — throughout various types of CloudBees product-specific documentation. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Jenkins is a registered trademark of the non-profit Software in the Public Interest organization. Used with permission. See here for more info about the Jenkins project. The registered trademark Jenkins® is used pursuant to a sublicense from the Jenkins project and Software in the Public Interest, Inc. Read more at www.cloudbees.com/jenkins/about. Apache, Apache Ant, Apache Maven, Ant and Maven are trademarks of The Apache Software Foundation. Used with permission. No endorsement by The Apache Software Foundation is implied by the use of these marks.Other names may be trademarks of their respective owners. Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this content, and CloudBees was aware of a trademark claim, the designations have been printed in caps or initial caps. While every precaution has been taken in the preparation of this content, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.