Skip to Content

Release management

This article walks through best practices, prerequisites to building a Release, and steps to follow for general Release Management in Vinyl. For detailed instructions on how to build the Vinyl Release within Vinyl itself, see the Build a release article.

Best practices

The Development environment is not a sandbox. Vinyl is capturing each database change, tracking them, and will replay them in QA when the database is shipped. As such, the developer should apply changes to the development environment in the same way they would expect the changes to be applied in QA and Prod. There are two types of changes that Vinyl captures in development and applies during an upgrade of QA and PROD:

Schema Changes

  1. Renaming a table
  2. Adding/Modifying/Deleting a column
  3. Modifying a primary key
  4. Adding/Modifying/Deleting a foreign key
  5. Adding/Modifying/Deleting a unique constraint

Migration Rules - Migration rules are defined similarly to an Create/Update/Delete rule and run in the development environment. Vinyl records the rule and runs it during an upgrade.

Transport all dependent applications and data sources

Shipping just an application or just a data source

While it is possible to ship a single application or a single data source from Dev to QA, it should only be done by advanced administrators with detailed knowledge of the changes that are being shipped with the object. In general, it is best to include all dependent objects when shipping a solution from Dev to QA and Prod. Following are some scenarios to consider when not including all dependent objects:

A designer adds a column to a data object in Data Source A. They then add a control to to a panel in Application X that is bound to the new column. If the developer attempts to ship Data Source A to QA, the upgrade will succeed. The data object will havea new column, though it is not used by the application. However, if the developer shipped Application X to QA, not including Data Source A in their solution, then the upgrade will fail. While upgrading the application, Vinyl wlll attempt to add the new control, but the column it is bound to does not exist in the current data source in QA and therefore it fails to be added.

Multiple applications using the same data source

Assume Application X and Application Y both reference Data Source A. One team is working on Application X and another team is working on Application Y. Both teams have added a columns to a data objects in Data Source A, and both teams have added controls to Applications X and Y that are bound to those columns. One of the teams also removed a control from Application X and removed the column, Column Z, which the control was bound to. If a developer attempts to ship Application Y and Data Source A to QA, the upgrade will fail. Vinyl will attempt to remove Column Z from Data Source A, but the column is still referenced by Application X in QA and therefore the upgrade will fail to remove the column. It is best to include any applications and data sources that are referenced in the solution to ensure that the upgrade will be successful.

Adding a non-null column

Take advantage of migration rules. Assume a table "Employee" has been shipped to QA and PROD and has been populated with production data. A developer then removes all of the rows from that table in order to add a NON NULL Column (Active Boolean Allow Nulls = False). This operation will succeed in the development environment because there are no employee records. When this changeset is applied in QA or PROD however, it will fail. An RDMBs database will not allow a non-null column to be added to a table that contains rows.

Instead, in the development environment, do not delete the employee records. Leave them so that the environment is representative of the QA and PROD target environments. Add the new column to the Employee table, but allow null values (Active Boolean Allow Nulls = True). Create a migration rule that updates the value of Employee.Active to true/false for all employees. Run the rule. Change the new column to be Allow Nulls = False. This operation will succeed in development, and will succeed when shipped to QA and PROD. Vinyl will perform the following steps during the upgrade:

  1. Add Active to Employee table Allow Nulls = True
  2. Update all Employee rows to have Active = true/false
  3. Modify the Active column to be Allow Nulls = False


Use supported Expressions to set the Active bit to true/false based on practical conditions. Typically, when adding a column to a table, all rows aren't expected to have the same value for that column. In this scenario, the migration rule might set Active to False for contract employees who have not been contracted in the past year, while setting all other employee rows to have Active = true.

Modifying the primary key of a table

Take precaution when modifying a primary key on a table that has already been shipped to QA and contains data. Again, it is best to ensure that the development environment has data in the table, so it best represents the QA and Prod environments. There are several ways a primary key might change. Following is one example:

Assume Employee has a column EmployeeId Integer Primary Key. Also assume that EmployeeAccrual has a column EmployeeId Integer (foreign key references Employee.EmployeeId). The Employee table also has a column SocialSecurity (String Unique Allow Nulls = False).

The developer has decided to change the primary key of Employee from EmployeeId to SocialSecurity. These are the recommended steps:

  1. Add SocialSecurity String Allow Null = True to EmployeeAccrual.
  2. Create a migration rule that updates EmployeeAccrual.SocialSecurity to be Employee.SocialSecurity joining to the two tables together on EmployeeId. Run the migration rule.
  3. Change SocialSecurity in EmployeeAccrual to be Allow Nulls = False
  4. Drop the relationship between Employee and EmployeeAccrual on EmployeeId
  5. Drop the column EmployeeId from EmployeeAccrual
  6. Change primary key of Employee to SocialSecurity
  7. Drop the column EmployeeId from Employee table
  8. Create relationship between Employee and EmployeeAccrual on SocialSecurity

Vinyl will record these steps, and successfully execute them while upgrading QA and Prod.


While performing steps 1 through 8, it is expected that the developer will be making changes to Data Objects, Actions, Panels, Controls, and so on. Feel free to make these changes at any time. In the example above, it is possible that the 8 steps listed are performed over a period of 8 hours during which several pages, data objects, and controls are also changed at various stages. The important point is to perform the steps listed in the correct order, so they are performed in the correct order during an upgrade. It is expected and fine to perform any number of changes to the logical data source or application while performing these steps.

Avoid importing schema

If the intention is to move a physical a database from Dev to Qa to Prod, and to further modify that physical database through the Vinyl UI and ship those changes to QA and Prod, then do not use the import feature for Vinyl Data Sources. In order to push changes made in development, Vinyl captures those changes as they are made through its UI. Importing a data source bypasses the Vinyl UI, synching the Vinyl logical model to match the imported data source's physical model. Therefore, no changes in the imported data source would be propogated during an upgrade. There are situations where importing is supported with release management:

  1. If the physical database is maintained and modified outside of Vinyl in all environments, then importing the data source throughout the development life cycle is supported.
  2. If the physical database is shared by Dev/Qa/Prod, then importing the data source throughout the development life cycle is supported.

Prerequisites to building a release

The following items should be considered and completed prior to building a Vinyl Release:

  1. Ensure that the Vinyl db User has Table and database Create permissions in the environment you are installing into.
  2. Ensure that a Database Administrator completes a database backup of both the Vinyl database and any database undergoing physical and/or schema changes.
  3. Ensure the environment package that will be installed is running on the same Version of Vinyl that the source environment is running on.

Steps to follow for release management

  1. Using your company standards for testing, verify the functionality of the Vinyl application.
  2. Create a list of all attached Data Sources for the application you're building a release for. This information is available from the Vinyl IDE, Build your application, click on your application and review the resultant Data Sources Panel.
  3. Create an application Release Template, and ensure all applications that should be promoted are included.
  4. Ensure that all linked Data Sources identified in step 2 are included in the Template.
  5. Verify the Template configuration for Data Sources. Only set Logical and Physical for data sources that you will manage schema changes for with Vinyl.
  6. Review and commit any open database change management steps for databases that are marked as Logical and Physical Install.
  7. Configure the Data Config for tables in databases that have been marked for Logical and Physical Install.
  8. Once Data Config is complete, confirm Data Config.
  9. Build the release. For detailed instructions on building a Release within Vinyl itself, see the Build a release article.