Automating Database Schema Updates

Sometimes, the database schema must be “manually” updated to add new primary columns to the users table, to add columns to table attributes' underlying tables, to resize existing columns or the like.

Generally it is not advisable to actually do this by hand as this can be an error-prone task that needs to be performed individually for each deployment.

Every UM plugin has its own database schema level counter that implicitly starts at “0”. (The value of this counter is internally kept in the database and managed by the CSE class PluginSchemaMigration).

To implement a schema level update, two steps must be taken:

The new numeric schema level must be specified in the plugin’s descriptor file.
The actual schema update must be implemented.

Define new schema level in plugin descriptor

If your plugin descriptor file does not already contain it, add a new property named dbSchema and give it the value 1. If your plugin descriptor file already contains the dbSchema property, just increase its value by one.

Your plugin.desc.json should look like this:

{
    "$schema": "http://git.intra.pinuts.de/cmsbs/cmsbs/raw/master/doc/json-schemas/plugin.desc.json",
    "__encoding": "Pinuts File Encoding: UTF-8",
    ...,
    "dbSchema": 1
}

Implement schema update

Create a new ES6 file in your plugin’s CSE directory. If your plugin’s name is de.acme.projectx then cmsbs-conf/cse/plugins/de.acme.projectx/callback/DbSchemaUpdate.es6 would be a good choice:

/// <reference path="../../../.vscode.js"/>
const SQL = UM.config.sql;


export default class DbSchemaMigration extends PluginSchemaMigration {
    schemaUpdate_0_1(scr) {
        // Create column for primary attribute "new_attribute":
        this.primaryAddColumn(scr, UM.config.attributes.new_attribute;
    }

    schemaUpdate_1_2() {
        // Create column for new table attribute's column:
        this.tableAddColumn(scr, UM.config.getAttribute("table_attribute->new_column"));
    }

    schemaUpdate_2_3(scr) {
        let sql = "CREATE VIEW " + SQL.qualifyTable('v_groupmembers') + " AS SELECT "
            + " grp.oid user_oid, 1 pos, user.sid c_userUid, membership.c_joinedAt, membership.c_isManager, membership.c_fromSegment, "
            + " user.firstname c_firstname, user.lastname c_lastname "
            + " FROM  " + SQL.users + " grp, " + SQL.qualifyTable(UM.config.getAttribute('groupMemberships').sqlName) + " membership, " + SQL.users + " user"
            + " WHERE membership.c_groupUid=grp.sid AND user.oid=membership.user_oid";

        scr.add(new SqlQuery(sql));
    }
    
    schemaUpdate_3_4(scr) {
        this.tableModifyColumn(scr, UM.config.getAttribute("groupNews->link"));
    }


    schemaUpdate_23_24(scr) {
        var SQL = UM.config.sql;

        this.primaryModifyColumn(scr, UM.config.getAttribute("nid"));

        // Index on users.p_nid
        let createIndex1 = new SqlQuery("CREATE INDEX idx_users_nid ON " + SQL.qualifyTable('users') + " (P_NID)");
        scr.add(createIndex1);

        // HBSEDS-871 Fehlende MySQL-Indixe anlegen
        let createIndex2 = new SqlQuery("CREATE INDEX idx_users_address ON " + SQL.qualifyTable('users') + " (address)");
        createIndex2.expectException = true;
        scr.add(createIndex2);

        let createIndex3 = new SqlQuery("CREATE INDEX idx_users_city ON " + SQL.qualifyTable('users') + " (city)");
        createIndex3.expectException = true;
        scr.add(createIndex3);

        let createIndex4 = new SqlQuery("CREATE INDEX idx_users_company ON " + SQL.qualifyTable('users') + " (company)");
        createIndex4.expectException = true;
        scr.add(createIndex4);

        let createIndex5 = new SqlQuery("CREATE INDEX idx_users_country ON " + SQL.qualifyTable('users') + " (country)");
        createIndex5.expectException = true;
        scr.add(createIndex5);

        let createIndex6 = new SqlQuery("CREATE INDEX idx_users_sid ON " + SQL.qualifyTable('users') + " (sid)");
        createIndex6.expectException = true;
        scr.add(createIndex6);

        let createIndex7 = new SqlQuery("CREATE INDEX idx_users_zipcode ON " + SQL.qualifyTable('users') + " (zipcode)");
        createIndex7.expectException = true;
        scr.add(createIndex7);
    }

    schemaUpdate_24_25(scr) {
        var SQL = UM.config.sql;

        // HBSEDS-871 Fehlende MySQL-Indixe anlegen
        let columSpecs = " (keycol, valcol)";
        if (SQL.dbTypeName == 'mysql') {
            columSpecs = " (keycol, valcol(191))";
        }
        let createIndex2 = new SqlQuery("CREATE INDEX idx_users_attr_keycol_valcol ON " + SQL.qualifyTable('users_attr') + columSpecs);
        createIndex2.expectException = true;
        scr.add(createIndex2);
    }

    schemaUpdate_25_26(scr) {
        this.primaryAddColumn(scr, UM.config.getAttribute("active"));

        let update1 = new SqlQuery("UPDATE " + UM.config.sql.qualifyTable('users') + " SET p_active='1' WHERE p_entrytype='user'");
        scr.add(update1);
    }
}

// Export
de.pinuts.hbs.eds.DbSchemaMigration = DbSchemaMigration;