Upgrading Obsidian

There are a number of options available to you. Select the one that best suits your situation.

Note that you don't necessarily need to go through the installer UI again, although you're free to do so. Since the primary purpose of the installer is to provide fully configured Obsidian artifacts and your environment would already be configured, you really just need the updated artifacts (libraries and WAR files). Even if you want to take advantage of new configuration options, you could use the Configuration Reference to make the necessary changes.

Automated Installer File

This section applies if you have saved an automated installer XML file from a previous version of Obsidian.

If the release notes do not document any installer incompatibility between source and target releases, this means there are no new configuration options available and you can use your automated installer file without modification.

You can see installation configuration for more information, but essentially all you need to do is run java -jar Obsidian-Install-n-n-n.jar my-obsidian-install-config.xml. You may wish to change the target installation path before proceeding.

If the release notes do document installer incompatibility between releases, follow the relevant instructions to update your installer configuration file and then follow the same procedure.

Existing Configuration

You have a choice when it comes to upgrading an Obsidian environment that is already configured.

1. You can rerun the installer UI to get the configured artifacts.
2. Use the quickstart installation mode to get the updated artifacts with the quickstart configuration.

Existing Configuration with QuickStart

If you are using overrides support to specify ALL your configuration items, you likely are ready to go as the default configuration items are being overridden.

Otherwise, you are relying at least partially on embedded configuration items. You will need to replace the quickstart configuration values with your existing configuration values. The Obsidian WAR files have the com.carfey.properties file inside at WEB-INF/classes/com.carfey.properties and the standalone installation has it at the root of obsidian-props.jar.

Performing the Upgrade

We highly recommend performing a database backup and an installation backup (filesystem backup) prior to performing the upgrade with rollback strategies in place to restore the previous installation with its data.

Obsidian automatically applies any database modifications during the first deployment of the new version.

The simplest mechanism is to bring down all your Obsidian Scheduler nodes during a quiet scheduling period. Deploy the new artifacts and start the each node individually verifying its startup before proceeding to the next node.

Database Upgrade Scripts

Available as of version 3.0

When you start Obsidian, it will automatically upgrade the schema in your target database. However, if you wish to run Obsidian with a database user without create and drop privileges, or simply wish to prepare your database structure ahead of time, you can use the database upgrade scripts provided with your download zip file under the "db_scripts" directory.

First locate all files named "*upgrade.sql" under the directory for the database you are using under the "db_scripts" directory. Statements within these files contain the token "$px$" to enable table prefixes. Before you run the SQL files, replace all instances of the token "$px$" (without quotes) with a table prefix 6 characters or shorter (letters and underscores supported), or with blank.

Then, in your SQL client of choice, execute the scripts in order of their version numbers. This will upgrade your schema to your target version.

You'll need to allow the data portion of the migrations to execute while preventing the DDL scripts to run. To do this, you need to disable DDL Updates.

Performing an Always On Cluster Upgrade

If you absolutely must maintain at least one node running, Obsidian should be able to continue scheduling and executing on a single node while the other(s) is/are upgraded although we make no assurances and recommend that you test out your specific upgrade scenario first. Depending on the content between source and target releases, we also recommend that you don't attempt to perform other changes such as job configuration changes, failure resubmissions, etc. during this time. Feel free to contact us with questions about your specific upgrade scenario.

Always On Cluster Upgrade Steps

1. Bring down all but one Obsidian Scheduler node.
2. Target a downed node for upgrade.
3. Deploy the upgraded artifacts to the targeted downed node.
4. Startup the upgraded node.
5. Verify successful startup.
6. Bring down the still-running older Obsidian Scheduler node.
7. Repeat steps 3-5 for each remaining downed node in the cluster.