This chapter describes the modifications that are possible on data models, as well as potential limitations.
Whenever the data modeler performs an evolution on the primary key of a table, the resulting definition is considered as a new table. 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; 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:
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 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, this change marks the mapped table as disabled. See Database mapping for the actual removal of associated database objects.
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. 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 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 following 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.
When a primary key definition is modified:
The content of the table will be reset to an empty content, in all datasets and dataspaces.
If the new primary key has been used in the past, the content of the table will be reset to the previous data existing at the time this primary key was used, in all datasets and dataspaces.
Type conversion is not supported for a primary key field. Thus, the content of the table will always be reset to empty when changing the type of a primary key even when reusing a type already used in previous primary key definition.
The modification will be rejected if the table has - or has had - history activated in the existing dataspaces. A possible workaround: first drop the history table associated with the dedicated table, then proceed to modifying the primary key. For the procedure to purge mapped table database resources, see Database mapping.
If the modified primary key is referenced in the primary key of another table, all the limitations mentioned above apply to the target table.
When the declaration of a osd:tableRef facet is added or modified, or when the primary key of its target table is modified, the existing values will restart from empty (except if this modification is reverting to a previous definition; in this case, the previous content will be retrieved).
In replication 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.
When changing the type of a field to an incompatible type or cardinality, the field will be considered as a new one, and start with an empty content. The previous content will be retrieved if the model is rolled back to a previous definition.
The following types are fully inter-convertible (meaning these types have the same exact persistent representation, and can be substituted to each other in the following charts):
xs:string
osd:color
osd:datasetName
osd:dataspaceKey
osd:email
osd:html
osd:local
osd:resource
xs:nmtoken
xs:nmtokens
osd:text
xs:anyUri
xs:name
The following conversions are fully supported (that is, regardless of their cardinalities):
xs:decimal to xs:string
xs:datetime to xs:string
xs:date to xs:string
xs:integer to xs:string
xs:int to xs:decimal
xs:integer to xs:decimal
xs:decimal to xs:integer (losing the decimal part)
xs:int to xs:integer
xs:datetime to xs:date (losing the time part)
xs:date to xs:datetime (defaulting the time part to 0)
The following conversions are possible only if the original type is single-valued:
xs:boolean to xs:string
xs:time to xs:string
xs:int to xs:string
xs:long to xs:string
The cardinality of a type can be changed; when the conversion is supported, it has the following behavior:
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.
Groups and complex types do not support conversion to (and from) any other types. Moreover, when a group or complex type changes between single-occurrenced and multi-occurrenced, the conversion is supported only if the group or complex type is terminal.