App Upgrade and Schema Migration

Introduction

In many cases, Helium app upgrades involve data model changes. To facilitate this Helium provides basic schema migration features.

Automated Migration

Whenever an app is loaded on the Helium back-end, Helium will compute a hash representing a natural ID for the object types, columns etc. that forms part of the app's data model.  This hash will be compared to the value stored in __he_data_version__ to determine if the model has changed since the previous version of the schema was created.  When data model changes are detected, Helium will attempt to make the least amount of schema changes required to make the schema compatible with the data model.  Specifically:

1. Tables will be created for new, persistent object types when the required tables do not exist.  Helium caters for the use of views instead of tables to back object types, therefore Helium won't attempt to create a table if a view exists with a name that matches the required name of the table.
2. Columns will be added for all fields in persistent object types for which columns do not already exist.  The exception here is that Helium won't attempt to add any columns if an existing view is found that matches the name of the required table for an object type.
3. Columns (and potentially tables) will be added for all relationships in persistent object types for which columns (or tables) do not already exist.
4. Foreign key constraints will be added for all relationships for which columns did not already exist.
5. All functions and triggers described under Design above will be recreated, to ensure that these functions and triggers are compatible with the new version of the schema.

Caveats

1. Except for legacy change tracking records, Helium won't migrate any data during schema migration - Helium will only create the necessary structures.  This must be kept in mind when renaming fields or relationships, or when changing the multiplicity of relationships.
2. Helium will only migrate change tracking records that are relevant to Journey or Helium App datasets that are less than two weeks old.
3. Schema migration will fail when a field with a Not Null validator gets added to an object type for which an existing table already contains records.

Disabling Automated Schema Migration / Upgrade

Since Helium 1.22, a feature has been included in Helium to prevent the automatic schema creation / upgrade / migration as described in this article. This gives developers more flexibility if they want be in full control of the schema upgrade / migration externally to a DSL app. Note that this is an advanced feature that should not be attempted if there is any uncertainty.

In order to do this, the app config for the specific app needs to updated with the field preventSchemaGeneration set to true. In this case Helium will still create the schema and admin, reader and writer roles for the schema, if not already done, but will not make any changes to the structure of the schema.

To get or update the app config for an app, the app-get-config.py  and app-update-config.py  scripts included in the Helium source code can be used. Note that client credentials with the relevant roles will also be needed.

For assistance in updating any values for an app config, the following process can be followed: App Config Support Request

Related Documentation

Automatic schema migration makes use of the Helium change tracking strategy for the app persistence tier. This is described in more detail here.