This chapter describes the modifications that are possible on data models, as well as potential limitations. The restrictions and/or potential impacts of data model evolutions depend on the persistence mode. The principles for each mode are the following:
Semantic mode: flexible and non-blocking. Can lead to a loss of data; for instance, a primary key definition can freely evolve, but all existing records in any dataspace and snapshot that violate the primary key constraint will no longer be loaded.
Any mapped mode: restrictive and thus blocking if data exists and if the evolution would violate their integrity according to the new data model.
Whenever the data modeler performs an evolution on the data model, it is important to anticipate the fact that it could lead to a loss of data. In such cases, if existing data must be preserved in some ways, a data migration plan must be set up and operated before the new data model is published or deployed. It can also be noted that data is not destroyed immediately after the data model evolution; in semantic mode, as long as no update is performed on a table whose definition has evolved, if the data model is rolled back to its previous state, then the previous data is retrieved.
Certain types of data model evolutions cannot be performed directly in the user interface, and thus the data model must be exported, modified in XSD format, then re-imported. For changes to a data model that impact its configuration, not just its structure, the XSD must be imported into TIBCO EBX® from a module. Otherwise, the configuration modifications are not taken into account.
This section describes the possible modifications to data models after their creation.
The following modifications can be made to existing data models:
A data model in semantic mode can be declared to be in relational mode. Data should be manually migrated, by exporting then re-importing an XML or archive file.
Relational mode can be disabled on the data model. Data should be manually migrated, by exporting then re-importing an XML or archive file.
Replication units can be added to the data model. If their refresh policy is 'onCommit', the corresponding replica tables will be created and refreshed on next schema compilation.
Replication units can be removed from the data model. The corresponding replica tables will be dropped immediately.
The data model can be deleted. If it declares replication units, the corresponding replica tables will be dropped immediately. If it is relational or contains historized tables, this change marks the associated mapped tables as disabled. See Database mapping for the actual removal of associated database objects.
The following modifications can be made to a data model at the table-level:
A new table can be added. Upon creation, the table can also declare one or more mapped modes.
An existing table can be deleted. If it declares replication units, the corresponding replica tables will be dropped immediately. If it historized or relational, this change marks the mapped table as disabled. See Database mapping for the actual removal of associated database objects.
An existing table in semantic mode can be declared to be in relational mode. Data should be manually migrated, by exporting then re-importing an XML or archive file.
History can be enabled or disabled on a table. History will not take into account the operations performed while it is disabled.
A table can be renamed. Data should be manually migrated, by exporting then re-importing an XML or archive file, because this change is considered to be a combination of deletion and creation.
The following modifications can be made to a data model at the field-level:
A new field can be added.
An existing field can be deleted. In semantic mode, the data of the deleted field will be removed from each record upon its next update. For a replica table, the corresponding column is automatically removed. In history or relational mode, the field is marked as disabled.
A field can be specifically disabled from the history or replication which applies to its containing table, by using the attribute disable="true". For a replica table, the corresponding column is automatically removed. For a history table, the column remains but is marked as disabled. See Disabling history on a specific field or group and Disabling replication on a specific field or group.
The facets of a field can be modified, except for the facets listed under Limitations/restrictions.
The above-mentioned changes are accepted, but they can lead to a loss of data. Data should be migrated manually, by exporting then re-importing an XML or archive file, since these changes are considered to be a combination of deletion and creation.
A field can be renamed.
The type of a field can be changed.
An index can be added or renamed.
An index can be modified, by changing or reordering its fields. In mapped mode, the existing index is deleted and a new one is created.
An index can be deleted. In mapped mode, a deleted index is also deleted from the database.
All limitations listed in this section that affect mapped mode can be worked around by purging the mapped table database resources. For the procedure to purge mapped table database resources, see Database mapping.
When a primary key definition is modified:
In semantic mode, the existing records are only loaded into the cache if they:
Respect the uniqueness constraint of the primary key,
Comply with the new structure of the primary key.
In mapped mode, the underlying RDBMS only accepts a primary key modification if all table records respect its uniqueness and non-nullity constraints. In particular, if a table already has existing records:
Adding a new field to the primary key requires assigning a default value to this field. Workaround for replicated or relational tables: first add the field, value it for the existing records, then add the field to the primary key.
Removing an existing field from the primary key will be rejected if it would cause the existing records to no longer have a unique primary key (assigning a default value makes no change in this case).
It is generally not possible to rename a field of the primary key; more formally, it is only possible if the field was not needed for making all primary keys unique. Indeed, renaming a field translates to a combination of deletion and creation; consequently, the operation will be rejected if it would cause the existing records to no longer have a unique primary key (assigning a default value makes no change in this case).
When the declaration of a facet osd:tableRef is added or modified, or the primary key of the target table of a facet osd:tableRef is modified:
In semantic mode, the existing values for this field are only loaded into the cache if they comply with the new structure of the target primary key.
In mapped mode, the structure of a foreign key field is set to match that of the target primary key. A single field declaring an osd:tableRef constraint may then be split into a number of columns, whose number and types correspond to that of the target primary key. Hence, the following cases of evolutions will have an impact on the structure of the mapped table:
declaring a new osd:tableRef constraint on a table field;
removing an existing osd:tableRef constraint on a table field;
adding (resp. removing) a column to (resp. from) a primary key referenced by an existing osd:tableRef constraint;
modifying the type or path for any column of a primary key referenced by an existing osd:tableRef constraint.
These cases of evolution will translate to a combination of field deletions and/or creations. Consequently, the existing data should be migrated manually.
In mapped mode, when a maxLength, length, totalDigits or fractionDigits facet is modified:
Whether or not this modification is accepted depends on the underlying DBMS, as well as the field type and the contents of the table.
For example, Oracle will accept changing a VARCHAR(20) to a VARCHAR(50), but will only change a VARCHAR(50) to a VARCHAR(20) if the table does not contain any values over 20 characters long.
PostgreSQL has the same limitations, but additionally, any modification of a field type (including modifications of its length) will invalidate all related prepared statements, and require restarting the application server.
When a cardinality of an element is modified:
In semantic mode, this change is supported. However, two cases are distinguished:
When changing a single element to an aggregated list, the previous single value is preserved and added to the new aggregated list.
When changing an aggregated list to a single element, only the last value of the aggregated list is preserved in the single element. Other values are lost.
In relational mode, aggregated lists are not supported. An error message is added to the compilation report of the data model if an element is changed to an aggregated list.
In historized mode, when changing a single element to an aggregated list, the modification is taken into account, but the previous single value is lost.