Upgrade existing SAP HANA XSA .hdbtable to .hdbmigrationtable through the CI/CD pipeline

[Sharathmg]

Introduction

SAP HANA's XS Advanced (XSA) application server model introduced several design-time artifacts for database development. Among these artifacts, .hdbtable files have been traditionally used to define database tables. However, SAP has encouraged developers to transition to the newer .hdbmigrationtable format.

This article addresses the migration, especially when the existing code is maintained across the D/Q/P landscape and the deployment is managed through a CI/CD pipeline.

Scenario

We had an existing project using .hdbtables. The tables held business critical data and any modification to them had to be performed without any loss of data. As  such, to alter these tables, we had to resort to DBADMIN user directly altering the tables through SQL queries on the specific HANA DB instance. At many levels, this approach was fraught with danger.

The two key features of .hdbmigrationtable, which were critical and useful for our scenario were:

• Schema evolution support without any loss of the table data

• Future-proof, design-time support of table maintenance

We had our code maintained on Git with deployment to the HANA Landscape through the Jobs configured in CI/CD pipeline.

Approach

Ensure that the table or file is consistent across the three branches linked to three instances ( D/Q/P ) of HANA Cloud DB.

To check that, the file was compared between the three branches.

1. “git diff <develop_branch> <quality_branch> <file_name> > file_diff_01.txt

2. “git diff <quality_branch> <develop_branch> <file_name> > file_diff_02.txt

Review the file_diff files to identify differences between the files. Ensure the differences are reconciled and all three branches are on the same structure type.

Next, we have to create the first version of the .hdbmigrationtable from .hdbtables.

The current table name is XXXX_AAA.hdbtable.

1. Create a copy of the existing XXX_AAA.hdbtable in the project

2. Rename the copy to XXX_AAA.hdbmigrationtable and the existing table to XXX_AAA.hdbtable.txt – This will ensure no deployment of this object

hdbtable copy to hdbmigrationtable

Note: While we have .hdbmigrationtable files in the project, the BAS editor will prompt us to enable the development mode. Ensure that we enable it. This will help the editor to recognise the existence of versions in the file.

BAS dev mode

In the feature branch mapped to the branch linked to HCD, include the line at the top of the file:

Initial version of table

== version = 1

Move this initial version of the hdbmigrationtable across the landscape through Git and CI/CD pipeline.

We ensure that the initial version of the table exists across the three branches and is deployed on the relevant systems.

Check: Before the table was moved to P. we did a sanity check of the table in Q to ensure that the table data is intact after the deployment.

Check: A consistent state between the design-time and runtime objects ensures only one design-time object for the runtime object. Now, to check what you have deployed, you can recover your artifacts from HANA to check the blog:https://community.sap.com/t5/technology-blogs-by-sap/hdi-artifact-recovery-wizard/ba-p/13657688. (Courtesy Volker Saggau )

Introduce the changes to the table with version 2 of the table. The following changes are to be done in the hdbmigrationtable:

• Change the version in the first line to

== version = 2

• Perform the table alteration. In our case, we had to drop two columns. So, we removed the two columns(column_name_1 and column_name_2) in the table definition. Then, introduce the SQL statements needed to accomplish the drop of columns.

== migration = 2
ALTER TABLE "<table_name>" DROP ("<column_name_1>");
ALTER TABLE "<table_name>" DROP ("<column_name_2>");

• Test the table deployment in the local container.

Check: We encountered an issue while deployment with the error: The migrated table does not match the specified definition. We had made the mistake of introducing the migration SQL statement without actually removing the columns from the definition.

Error during deployment

Once the deployment was successful, we moved the changes to Q and P.

A final sanity check of the table data to ensure data is intact.

Any future changes can be introduced by adding migration steps in the same table definition at design-time which ensures a clean audited modification of table structures.

== migration = 3
ALTER TABLE "<table_name>" ADD "<column_name_3>" <data_type>;

== migration = 2
ALTER TABLE "<table_name>" DROP ("<column_name_1>");
ALTER TABLE "<table_name>" DROP ("<column_name_2>");

Conclusion:

Migrating from .hdbtable to .hdbmigrationtable through a CI/CD pipeline significantly reduces data loss risks and application downtime while enhancing operational efficiency across all environments.

The automated approach transforms what was once a challenging technical hurdle requiring dedicated maintenance windows into a streamlined, predictable process within standard deployment cycles. Organizations that establish these CI/CD practices for table migrations position themselves to adopt future SAP HANA innovations with minimal disruption while maintaining data integrity and meeting compliance requirements. The investment in automating this transformation ultimately delivers improved development velocity, reduced operational overhead, and a more resilient application landscape, making evolved data model management not just a technical improvement but a competitive necessity.