Upgrade Data Sources

The schema of the Curity Identity Server is relatively simple to understand and administer. Some newer product versions require schema upgrades. Starting in version 11.0 of the Curity Identity Server, the upgrade process integrates with the Liquibase tool, which enables you to validate that data sources have the database objects (like tables, columns and indices) that the current product version requires.

This tutorial briefly summarizes how an organization can manage data source upgrades using changelogs that Curity provides. To do so you set environment variables such as database connection strings and then run the idsvr command with parameters, to identify schema changes. You then apply changes to upgrade data sources and can rollback if required. For full details, see the Database Schema Migration docs.

Read the Upgrade Instructions

For all upgrades of the Curity Identity Server, always start with the Upgrade Instructions. Data source upgrades are backwards compatible and most product upgrades do not require schema updates.

When the Curity Identity Server adds a new column or table, it typically does not come into effect until you activate new security features that use the new storage. Unless the upgrade instructions indicate otherwise, it is safe to either upgrade data sources before the product, or the product before data sources.

Liquibase tooling only supports upgrades from version 10.6.0 onwards. Whenever you perform a complex upgrade from a much older version, read the upgrade instructions to understand the full set of schema changes.

Use Liquibase Operations

The new schema migration tooling helps to verify that the schema is correct on every upgrade. To use Liquibase, set environment variables so that the Curity Identity Server can connect to one or more data sources. The following connection details might represent a PostgreSQL database on schema version 10.7.0.

export JDBC_URL='jdbc:postgresql://dbserver/idsvr'
export JDBC_USERNAME='idsvr_user'
export JDBC_PASSWORD='Password1'

Get Upgrade Changes

Whenever you upgrade the version of the Curity Identity Server, run the idsvr -C command to understand database changes. The following example saves schema changes to a SQL script.

idsvr -C default > upgrade-10.7.0_11.0.0.sql

Inspect the script, which will contain an empty set of actions if there is no need for a schema upgrade. You can then apply any schema changes using the script, or use Liquibase to automate the changes.

Run Automated Upgrades

Instead of running a script, Liquibase can automatically upgrade the data source. Use a tag to be explicit about the version to upgrade to, or omit the tag to upgrade to the latest product version. The database user must have permissions to add schema objects like tables or columns. For example, you may need to temporarily run the Curity Identity Server with database owner (DBO) privileges.

idsvr -L default -t '11.0.0'

You can safely re-run the idsvr -L command multiple times. The first execution will apply schema changes and subsequent executions will be no-ops.

Run Automated Downgrades

Downgrades work equivalently, to revert to a previous version. Downgrades are a destructive operation that can remove added tables and columns and the data they contain.

idsvr -L default -t '10.7.0'

Run Remote Commands

If you run the Curity Identity Server on a remote server, run the idsvr commands remotely. The following example produces a bash script to run in a remote container.

cat << EOF > get_upgrade_script.sh
#!/bin/bash

export JDBC_URL='jdbc:postgresql://dbserver/idsvr'
export JDBC_USERNAME='idsvr_user'
export JDBC_PASSWORD='Password1'
idsvr -C default
EOF
chmod +x get_upgrade_script.sh

The following command copies the bash script to a Docker container and executes it to get a SQL upgrade script.

CONTAINER_ID=$(docker ps | grep idsvr | awk '{print $1}')
docker cp get_upgrade_script.sh "$CONTAINER_ID":/tmp/
docker exec -it "$CONTAINER_ID" bash -c /tmp/get_upgrade_script.sh > upgrade.sql

Improve Database Automation

The Liquibase tooling provides a more streamlined way to manage data source upgrades than running scripts manually. You could run a utility Docker image for the Curity Identity Server to upgrade the schema, as in the following example upgrade.

• Start with a live cluster of the Curity Identity Server that runs version 10.7.0.
• Run a utility Docker container that connects to data sources as a database owner (DBO) user, to upgrade data sources from version 10.7.0 to version 11.0.0.
• Upgrade the admin and runtime workloads to version 11.0.0, after which those workloads continue to connect to data sources as a low privilege database user.

Design a Resilient Upgrade Process

The Liquibase tooling gives you choices to upgrade data sources according to your preferred database best practices. The idsvr -L option is suitable for organizations that frequently upgrade the Curity Identity Server to new versions in production environment. The idsvr -L command is safe to run on every product version upgrade, even if there are no schema changes.

Some organizations may need to supply scripts to a database administrator (DBA), who makes data source backups, then applies data updates before code updates. For database-first use cases, use the idsvr -C option to produce upgrade scripts. You can apply the same script to multiple stages of a deployment pipeline, like DEV, TEST, STAGING and PRODUCTION. After each stage you can run the idsvr -C command to verify that the data source is fully upgraded.

For important stages of your pipeline, like your main test system, combine schema upgrades with DBA best practices like backups. If you need to run an upgrade from a considerably older version, such as from version 9.5.0 to 11.0.0 of the Curity Identity Server, follow the upgrade instructions for each intermediate version and run an upgrade according to Upgrade Best Practices.

Summary

The Curity Identity Server integrates with the Liquibase tool to improve reliability and database automation. The tooling also enables you to validate that the current schema contains the correct database objects for the current schema version. For important data sources, combine the use of Liquibase with established DBA best practices, to protect your identity data.

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Email

Subscribe

I agree to Curity's Privacy Policy

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial