- Created by Jacques Marais , last modified on Jun 19, 2017
You are viewing an old version of this page. View the current version.
Compare with Current View Version History
« Previous Version 4 Next »
Introduction and Design
Schema Migration
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:
- 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.
- 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.
- Columns (and potentially tables) will be added for all relationships in persistent object types for which columns (or tables) do not already exist.
- Foreign key constraints will be added for all relationships for which columns did not already exist.
- 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.
- Data from legacy change tracking tables will be migrated when those tables haven't yet been renamed to the new __legacy_... standard.
Caveats
- 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.
- Helium will only migrate change tracking records that are relevant to Journey or Helium App datasets that are less than two weeks old.
- 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.
| Table | Helium < 1.3.4 | Helium >= 1.3.4 |
|---|---|---|
| __version__ | Kept track of changes to records that occurred within the same Helium transactions. Changes generated within the same transaction could be split across multiple __version__ entries depending on the caching strategies on the server. | Retired. The table is automatically renamed to __legacy___version__ after data has been migrated. |
| __change__ | Kept track of insert, update, delete, link & unlink changes to records. | Retired. The table is automatically renamed to __legacy___change__ after data has been migrated. |
| __syncclient__ | Kept track of Helium Android synchronisation clients - app / role / user / device combinations | Retired. The table is automatically renamed to __legacy___syncclient__ after data has been migrated. |
| __syncclient_request__ | Kept track of Helium Android synchronisation requests | Retired. The table is automatically renamed to __legacy___syncclient_request__ after data has been migrated |
| __he_sync_transaction_log__ | Similar to __version__ in Helium < 1.3.4. Keeps track of transactions during which data were changed in Helium. This table is not populated when changes do not flow via the Helium platform, but is not required to be populated for synchronisation (Journey + Helium Android) to work properly. | |
| __he_sync_obj_change__ | Similar to __change__ in Helium < 1.3.4. Keeps track of create, update & delete changes to records. link & unlink of relationships, excluding many-to-many relationships, are tracked as create or update, depending on when they occur. | |
| __he_sync_client__ | Similar to __syncclient__ in Helium < 1.3.4. | |
| __he_sync_client_request_log__ | Similar to __syncclient_request__ in Helium < 1.3.4. | |
| __he_sync_many_to_many_unlink__ | Tracks unlink changes to many-to-many relationships | |
| <table>._tx_id_ | Tracks the transaction ID during which the record was last changed. This ID will be the same as the ID from __he_sync_transaction_log__ when the transaction is recorded in the __he_sync_transaction_log__ by Helium. This column will still be populated when changes are made directly in the database, but the __he_sync_transaction_log__ entries will be absent. It is therefore important to realise that not all transaction IDs can be joined to the __he_sync_transaction_log__ table. | |
| <table>._change_type_ | Tracks whether the last change to the record was a create or and update change. | |
| <table>._change_seq_ | Tracks the sequential number (within the specific app's schema) for the last change that affected the record | |
| __he_sync_obj_insert_after__ | Function that records create __he_sync_obj_change__ for records. Triggers, calling this function, with the same name exist for all object types (except those marked with @NotTracked) in the data model. | |
| __he_sync_obj_update_before__ | Function that updates <table>._tx_id_, <table>._change_type_ and <table>._change_seq_ Triggers, calling this function, with the same name exist for all object types in the data model. | |
| __he_sync_obj_update_after__ | Function that records update __he_sync_obj_change__ for records. Triggers, calling this function, with the same name exist for all object types (except those marked with @NotTracked) in the data model. | |
| __he_sync_obj_delete_after__ | Function that records delete __he_sync_obj_change__ for records. Triggers, calling this function, with the same name exist for all object types (except those marked with @NotTracked) in the data model. | |
| __he_sync_<table>_insert_after__ | Function that records update __he_sync_obj_change__ for records owning many-to-many relationships. Triggers, calling this function, with the same name exist for all many-to-many relationships (except those belonging to object types marked with @NotTracked) in the data model. | |
| __he_sync_<table>_delete_after_a__ | Function that records __he_sync_many_to_many_unlink__ for many-to-many relationships. Triggers, calling this function, with the same name exists for all many-to-many relationships (except those belonging to object types marked with @NotTracked) in the data model. | |
| __he_sync_<table>_delete_after_a__ | Function that records update __he_sync_obj_change__ for records owning many-to-many relationships. Triggers, calling this function, with the same name exist for all many-to-many relationships (except those belonging to object types marked with @NotTracked) in the data model. | |
| __he_data_version__ | Tracks the version of the schema. This version number is a hash generated by Helium and should not be used in any other way than to determine if two versions are the same. | |
| __he_meta_data_version__ | Tracks the meta data version of the schema - currently that is the version of change tracking present in the schema. |
- No labels
0 Comments