Convert merged changes into the parent polyglot model

Before we dive into the process, it is important to understand the concept of deviations.

 

Deviations in a model derived from polyglot

A deviation means that the user chooses to alter a model derived from polyglot. Deviations can be in the form of altering or deleting existing objects or adding new ones.  Meaning that the derived model can be a subset/superset of its parent polyglot model.  You may add one or more attributes in an entity.  You may add one or more entities.  You may change some properties of an existing attribute so the chosen property value overrides the inherited definition, etc...    All these deviations are tracked within the derived model so that the impact analysis screen takes them into account when updating polyglot references.

 

When comparing 2 models, it is possible that the same column exists in both the left and right models, but with a different property value. For example, the column is defined as varchar without length specified in the derived physical model on the right, while the reverse-engineered model from the database on the left defines it as varchar(30).

 

When merging, the user can choose to use the value from the left model (30) into the merged model. Doing so creates a deviation.

 

Warning: Data type of attributes cannot be altered in a derived model.  The datatype is treated as a fundamental property, on which other properties may depend, and must remain consistent with the source Polyglot model. This applies both when editing a derived model and when using the Compare & Merge feature: the datatype from the right-side model will always prevail. If the database defines a different datatype, this must be addressed at the Polyglot level. See advanced use case below.

 

For changes that cannot be handled as simple deviations (such as datatypes, or when you prefer to propagate the update into the Polyglot chain rather than creating a deviation in the physical model), a more advanced process is required.  This advanced use case is described below...

 

Convert merged changes into the parent polyglot model

Deviations are tracked in a model derived from polyglot whenever you add, alter, or delete objects compared to its parent.  While deviations are useful for flexibility, sometimes the intention is not to keep them as exceptions in the physical model, but to propagate the change into the polyglot model itself so it becomes part of the canonical definition.

 

At a high level, the process consists of reverse-engineering the database, merging updates into the derived physical model (as we did in the previous scenario), and finally converting and merging those changes back into the polyglot model to keep the whole chain aligned.

 

 

In the previous scenario, we updated a derived physical model by merging changes from the database.  At this point, the merged physical model contains the most recent structure, drawing from the database and from the polyglot.  However the polyglot model model is no longer in sync with the database changes merged into the derived physical model.  You therefore must take an additional action...

Warning: when saving the merged model, you may wonder what name to give to your model file.  Assuming that your models are stored in a Git repository, remember that Git performs automatic versioning of any changed file (after commit and push.)  We suggest that you save the merged model with the same file name as the right-side model, i.e. the derived physical model.  When you commit and push your merge operation, a new immutable version of the physical derived model is automatically created by Git.  In case you want to revert your operation, you can still go back to the previous commit.

 

If you want these changes made to the physical derived model to become part of the polyglot definition, as it may be needed when deriving into other target models, the nest step is to perform a Convert & Merge operation from the physical model into its Polyglot parent.

 

How to perform a Convert & Merge operation

The Convert & Merge operation reuses the existing Convert to Polyglot feature, but with a slightly different workflow.  Instead of creating a brand-new polyglot model, you need here to merge into the existing one. Here are the key steps:

 

1. From your derived physical model, launch the "Convert to Polyglot" action.️  A warning appears.  

 

 

You may proceed. At this stage, Hackolade Studio does not know yet whether you will save into a new file or merge into the existing polyglot model from which the derived model was originally derived.  Since you will later select the same Polyglot file and choose Merge, the original link will effectively be preserved and updated, not lost.

 

2. When prompted, specify that the derived model and the Polyglot should remain dependent, and select relative path (absolute path is rarely a good idea.)  This ensures that the new reference link is properly maintained.

 

3. Hackolade Studio then opens the OS file selection dialog to save the converted model.  Instead of creating a new file, you should point to the existing polyglot model file. Your Operating System will ask if you want to replace the file. Choose Yes.

 

4. Hackolade Studio will then detect that the target file already exists and will offer two choices:

Select Merge. This way, existing content in the polyglot model is preserved, and only the changes from the converted physical model are added.

5. The polyglot model is updated with all relevant changes:

• Existing entities keep their reference links, and their properties are enriched with the updates coming from the physical model.
• All new objects introduced in the physical model are added to the Polyglot. The corresponding objects in the physical model are then marked as derived from these new polyglot objects, with reference links automatically established.

 

What happens to deviations of type delete and alter?

In the above example, you may have noticed that the left model, issued from the reverse-engineering operation of the database, only contained additions: new table and new column in an existing table.  

 

What if in the database, an object has been deleted?  During the merge operation, the impact analysis screen for the merge operation will, by default, propose that the object be reinstated.  It takes an action by the user to deselect it (by unchecking the box) in the merged model pane.  As a result of the deselection, the object will be removed from the merged model, and hence become a deviation, in the resulting physical derived model, versus the existing object in the parent polyglot model.   During the Convert & Merge operation however, we do not want to be destructive.  The object remains in the Polyglot model, and it remains as a deviation in the derived model.

 

What if in the database, an object has been altered?  During the merge operation, the derived physical model gets updated with the changes in the database, and become a deviation versus the properties in the polyglot model.  During the Convert & Merge operation, the changed properties are pushed to the polyglot model.  As a result, the deviation disappears from the physical derived model, since the derived model and the polyglot models are aligned.