Upgrading ORDS from 3.0.5 to 3.0.7

Introduction

With ORDS 3.0.7 being released a few days ago, I thought I would provide an example of how to perform an in-place upgrade of ORDS from an older ORDS 3.X install. At the time of writing this post, there is little documentation on the subject of upgrading ORDS so I figured this may be useful.

Note: ORDS 2.X is fundamentally different to ORDS 3.X so this example does not apply to an ORDS 2 to ORDS 3 upgrade which is a much bigger undertaking. 

The example below shows upgrading an existing ORDS 3.0.5 install to ORDSS 3.0.7. You should also know that we are running ORDS within GlassFish.

Backups & Precautions

Before starting anything, backup the following:

• Your current ords.war file.
• The content of your ORDS config directory (in my case this is /srv/ords/config)
• Your current REST service modules, templates and handlers

It should also go without saying that you should run this in a test instance (and run regression tests) before running the upgrade in production.

The last thing to do before upgrading is to check the readme.html to make sure this is a version you will benefit from upgrading to and to see if there may be some other steps you need to perform manually after the upgrade. For example in 3.0.7. the readme has the following:

​"In line with security best practice and as recommended by the Oracle Application Express Documentation when a database pool is configured to use the APEX_PUBLIC_USER, Oracle REST Data Services will automatically set the value of the security.requestValidationFunction setting to be:
WWV_FLOW_EPG_INCLUDE_MODULES.AUTHORIZE"

As we are doing an in place upgrade we will need to go in and make this change ourselves if we want to do this (which we should).

Assumptions

• ​​The upgrade is from 3.0.5 to 3.0.7
• The existing (ORDS 3.0.5) WAR file is in the folder /srv/ords
• The existing (ORDS 3.0.5) config dir is /srv/ords/config

Upgrade Steps

Download the latest version of ORDS
Extract the ords.war file and copy it to your application server overwriting your existing ords.war file (you did back it up right!).

At this point, you can run the ORDS installer:
cd /srv/ords
java -jar ords.war install

The installer will ask for the location of the config directory. This is where you will provide the location of your existing (in this case ORDS 3.0.5 config directory):
Location of your existing config directory:
Enter the location to store configuration data:/srv/ords/config

At this point ORDS realizes you have an existing install. You will still have to provide the SYS user and password so the installer can upgrade the DB Schema:

Please login with SYSDBA privileges to verify Oracle REST Data Services schema.
Enter the username with SYSDBA privileges to verify the installation [SYS]: SYS
Enter the database password for SYS:syspassword
Confirm password:syspassword

You will then see ORDS upgrading the ORDS schema:
Upgrading Oracle REST Data Services schema 3.0.5.124.10.54 to version 3.0.7.253.09.40
... Log file written to /home/glassfish/ords_upgrade_2016-09-29_230052_00588.log
Upgrading ORDS schema to 3.0.6
Completed upgrade for Oracle REST Data Services version 3.0.7.253.09.40.  Elapsed time: 00:00:11.578 

At this point you should be about done. If like us, you are running ORDS within GlassFish, you should now remove your existing ORDS application and deploy the new ords.war file. Unless you are also upgrading APEX, there is no need to do anything with i.war.

Verify

You can verify the current version of ORDS by running the following SELECT as SYS (or SYSTEM):

You can also check the version from APEX by logging into a Workspace and clicking Help > About. You should see the following:

Conclusion

That about wraps it up. I can't stress enough, the importance of backing up your existing configuration first and also running the upgrade in a test instance before doing it in production.