Manage Versions

Matillion ETL has versioning features to help you manage versions of your ETL transformation and orchestration jobs. Versioning supports many use cases, but perhaps the most common use is to capture and freeze your development at a point in time to designate as "live" or "production" versions, and to then continue working on your default version. This article discusses the basic versioning concepts and steps.

Warning

This note applies to Git integration users.

When creating a new version, Matillion ETL makes a clone of the project and the jobs. This means that new job IDs are created for each job. If you are using Git integration with Matillion ETL, checkout the branch you are using to avoid merge conflicts for each job.

Note

We recommend that you should keep only one version per developer on a project. If you keep many versions, it can cause migrations and API exports to be significantly slower.
If you also use Git integration on a project, you can store a full history of your job changes. Watch this video for more information.

Versioning concepts

Matillion ETL's versioning system creates a copy of all of the jobs in your current project at that point in time.

All projects have a Default Version, which is the main working version. It is possible to create multiple new versions that branch from your default version at different points in your project's development. Those versions can, in turn, have new versions branched from them. Changes can then be made to either your default version or to any non-default version you have created, as long as the version is in an unlocked state.

Note

A new version does not include the undo history for the project (although that history is maintained in the version it branches from), but any subsequent changes made in the new version will be tracked.
Subsequent new versions are based on the currently selected version (read Switching versions), which may be the previous version, the default version, or any other version.

Creating a new version

Click Project → Manage Versions.

Warning

If you have more than one version listed in the Manage Versions dialog, ensure that the version that you wish to base the new version on is selected before continuing.
As you can see in the above example, we currently only have one version of our project, which is the Default Version. To create a new version, click the + button in the lower-left of the dialog. This will open the Create Version dialog.
Give your new version a Version Name and, optionally, a Description. The Version Name can only include the following characters: alphanumerics, underscores, single spaces, parentheses, and hyphens. You cannot use a space as the final character in your Version Name.
You can choose to lock or unlock your version (read Version locking) by selecting or deselecting the Lock Version checkbox. When the padlock icon is red, the version is locked. When the padlock is green, the version is unlocked. By default, new versions are locked.

Version locking

Version locking allows you to protect a version of your project, This feature can prevent accidental changes to important versions such as a "production" or "live" version. The version can be unlocked if you later decide you need to make changes to the job.

When the padlock icon in the Status column of the Manage Versions dialog is red, the version is locked. When the padlock is green, the version is unlocked. Read Managing versions for details of how to lock and unlock versions.

Switching versions

When you have created a new version, you will see all versions of the project listed in the Manage Versions dialog.

![Versions list](https://matillion-docs.s3-eu-west-1.amazonaws.com/images/2261221/Version+Locking.png)

To switch to the version named Test-Version in the above example, click on the square icon next to Test-Version in the Switch Version column, and then click OK to confirm the switch.

Deleting a version

To delete a version, click the - icon next to the version you want to delete in the Manage Versions dialog. Click OK to confirm the deletion.

Note

It is not possible to delete the Default Version.

Managing versions

Use the edit icon (pencil) in the Manage Versions dialog to edit a version's properties. You can edit the version name and description, and lock or unlock the version.

Note

It is not possible to rename the Default Version
You can edit a version's name and description regardless of whether the version is locked or unlocked.

Using and running a version

Once versions are set up, there are numerous places in Matillion ETL where that version can be referenced and used:

Using Queues: When launching from an SQS Queue, specify the version name in the JSON message. Read Manage SQS configuration.
In the Scheduler: When scheduling jobs, ensure the version is selected.
Task History: In the Task History, the version is displayed so that you can easily see which version of the project has been run.
By URL: If you wish to "deep-link" or bookmark a project version, the version can be referenced in the URL:

https://<server name>/#<Group Name>/<Project Name>/<Version Name>

For example:

https://server1.matillion.com/#Matillion-Samples/Version-Example/Production