Upgrading Corteza

This guide helps you upgrade your Corteza to the newest version in no time!

While there are internal safeguards in place that can prevent data loss or other kinds of disasters, make sure you backup your database before you upgrade. Refer to devops guide on backup procedure for details.

If you are upgrading multiple versions at the same time; for example from 2019.12 to 2020.9; you should follow all the upgrade guides between the two versions.

Recommended Steps for Corteza Upgrade

Especially before any major version upgrade, it is recommended that before upgrading your production you either:

  • upgrade your staging environment, or

  • deploy a temporary environment with a copy of the production database and perform a test upgrade there.

Steps to upgrade Corteza when deployed with docker-compose:

  1. changing image versions in your docker-compose.yaml (or .env) file,

  2. pull new images from docker hub with docker-compose pull,

  3. recreate containers with docker-compose up -d.

Upgrading to 2024.9.6

The newly added user groups requires database schema modifications that may not be backwards compatible. The role_members table receives a new rel_resource column which is generated based on the rel_user column. After the upgrade, you need to either delete the rel_user column or drop the requirement the rel_user column is populated.

Before the Upgrade

Since the database schema will be modified, we recommend you create a backup just in case.

Run the following commands based on your database:

MySQL

ALTER TABLE role_members
    ADD COLUMN rel_resource TEXT;

ALTER TABLE role_members
    DROP PRIMARY KEY;

ALTER TABLE role_members
    ADD PRIMARY KEY (rel_resource, rel_role);

ALTER TABLE role_members
    MODIFY rel_user BIGINT UNSIGNED NULL;

PostgreSQL

ALTER TABLE role_members
    ADD COLUMN rel_resource text;

ALTER TABLE role_members
    DROP CONSTRAINT role_members_pkey;

ALTER TABLE role_members
    ADD CONSTRAINT role_members_pkey
        PRIMARY KEY (rel_resource, rel_role);

ALTER TABLE role_members
    ALTER COLUMN rel_user DROP NOT NULL;

SQL Server

ALTER TABLE role_members
    ADD rel_resource NVARCHAR(MAX) NULL;

ALTER TABLE role_members
    DROP CONSTRAINT role_members_pkey;

ALTER TABLE role_members
    ADD CONSTRAINT role_members_pkey
        PRIMARY KEY (rel_resource, rel_role);

ALTER TABLE role_members
    ALTER COLUMN rel_user BIGINT NULL;

After the Upgrade

If you’ll no longer require the column, you can safely delete it.

ALTER TABLE role_members DROP COLUMN rel_user;