Data migration
Introduction to Data migration​
A very important step in preparing a database upgrade for your end-application is setting up the data migration between two model versions. This adds information to the upgrade script about renamed and changed tables and columns.
If data migration is not applied correctly, it can ruin the database. In a best-case scenario, the upgrade script will fail, and a backup has to be restored. Yet, in the worst case, the upgrade is carried out without an error message but with data lost.
Source model version​
menu Data > Data migration
Always check the selected source model version. This ensures that the new version is created from the correct branch and model version.
You can compare two branches or two points in time within one branch based on the temporal history. If you obtain the latest model version of your end-product, the branch's source branch and model version will be set to that version. This allows easy generation of upgrade scripts for different end-products.
You can set the source 
for data migration and upgrade by obtaining it from the database
or manual selection. This task also generates new objects, if applicable.
To prevent problems, you cannot execute this task when jobs for definition generation or validation, or for source code generation are queued or active.
Update the previous version
Rebuilding a table​
Even if nothing has changed, it can still be desirable to rebuild a complete table. For example, when the structure of a table can no longer be guaranteed.
menu Data > Data migration > tab Tables
- Execute the task Rebuild table
. - Answer Yes to the question "Are you sure you want to mark this table to rebuild?".
Table mapping​
Update a table mapping​
Data migration automatically attempts to map the old tables and new tables based on naming. If the match is successful, From table and To table are filled, and the Status is set to 'Changed'. It is also possible to create your own table mapping.
menu Data > Data migration > tab Tables
- Execute the task Update table mapping
. - Where necessary, specify the From table or To table.
Update a table mapping
Disconnect a table mapping​
Sometimes a table has the same name as before but a different function. Therefore, the data is no longer correct, and the table needs to be emptied after the upgrade. In this case, it is possible to disconnect a table mapping. The target table will be considered 'New' and not receive data during data migration.
menu Data > Data migration > tab Tables
- Execute the task Disconnect table mapping
. - Answer Yes to the question "Are you sure you want to disconnect the mapping of [table]".
Now, the record with a from and to table is split into two records. The to table gets the Status 'New' and the from table gets the Status 'Removed'.
Reset a table mapping​
It is possible to reset a specific table for the configured source back to the default mapping. This can only be done when the table mapping has been updated manually (the generated checkbox is cleared).
menu Data > Data migration > tab Tables
- Execute the task Reset table mapping
. - Answer Yes to the question "Are you sure you want to reset the mapping of [table]?".
To reset the entire data migration for the configured source back to the default mapping, execute the task Fully reset data migration 
.
Table changes​
If a table has been changed, this may result in an upgrade. You can view the changes regarding aspects of a column that will result in an upgrade:
menu Data > Data migration > tab Tables > tab Table changes
This overview may include one or more of the following aspects:
- Description
- Table
- Table alias
- Database settings
- Partition settings
- Partition scheme
- Partition boundary added
- Partition boundary removed
- Related objects
- Index added
- Index removed
- Column order changed: becomes selected if the order of existing columns has changed while no columns have been added or removed. It indicates why an upgrade is required, since this change is not reflected in the Column changes as the column content itself remains unchanged. The checkbox is not affected by changing the order of expression columns, as this never results in an upgrade.
Column mapping​
Update a column mapping​
To map two columns within a table:
menu Data > Data migration > tab Columns or tab All columns
- Execute the task Update column mapping .
- Where necessary, specify the From column and To column.
- Optional: set a Default value type. This can be a constant value or an expression. These fields are only mandatory if the column in To column is mandatory. The difference between the default values in data migration and the data model is that the default value in data migration is used only during the upgrade.
Update a column mapping
Disconnect a column mapping​
Sometimes a column has the same name as before but a different function. Therefore, the data is no longer correct, and the column needs to be emptied after the upgrade. In this case, it is possible to disconnect a column mapping. The target column will be considered 'New' and not receive data during data migration, unless a default value is configured.
menu Data > Data migration > tab Columns or tab All columns
- Execute the task Disconnect column mapping .
- Answer Yes to the question "Are you sure you want to disconnect the mapping of [column]?".
Now, the record with a from and to column is split into two records. The to column gets the Status 'New' and the from column gets the Status 'Removed'.
Reset a column mapping​
It is possible to reset a specific column for the configured source back to the default mapping. This can only be done when the column mapping has been updated manually (the generated checkbox is cleared).
menu Data > Data migration > tab Columns or tab All columns
- Execute the task Reset column mapping .
- Answer Yes to the question "Are you sure you want to reset the mapping of [column]?".
Column changes​
If a column has been changed, this may result in an upgrade. You can view the changes regarding aspects of a column that will result in an upgrade:
menu Data > Data migration > tab Tables > tab Columns > tab Column changes
This overview may include one or more of the following aspects:
- General
- Column
- Column alias
- Domain
- Domain
- Domain length
- Domain scale
- Database data type
- Model settings
- Identity
- Identity seed
- Identity increment
- Primary key
- Mandatory
- Default value
- Default value type
- Default constant value
- Default value query
- Calculated field
- Calculation type
- Calculated field query
Re-apply intermediate mappings​
menu Data > Data migration > tab Tables
When you set the source to an earlier version (for example, when releasing a major version), all mapping for the development versions in between
will not be included by default.
In that case, you can re-apply intermediate mappings 
that have an earlier configured
source or a different branch further down the origin chain.
The task shows which intermediate versions contain mapping information that could be applied.
This includes all the intermediate mappings up to the last state of any branches that were merged into the current branch.
These will be combined and applied to the new model version created in the target branch after the merge.
See also Include data migration mappings during merge.
When you execute the task, these mappings will be applied recursively. Mappings configured directly to the target branch will be favored over mappings between a source branch and other intermediate versions in this source branch.
After having re-applied intermediate mappings, always verify the results.
Re-apply the intermediate mappings
Data migration for complex situations​
The data migration settings are intended for simple scenarios, where records are moved from one table to another or columns are filled using default values.
For more complex scenarios, i.e., merging tables, changing primary keys, normalizing or denormalizing, you can add scripts into the upgrade process. See Model version specific update scripts in the Functionality manual.