@cap-js/change-tracking 2.0.0-beta.4 → 2.0.0-beta.6

package/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
-## Version 2.0.0-beta.5 - tbd
+## Version 2.0.0-beta.7 - tbd
 
 ### Added
 
@@ -12,6 +12,30 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 
 ### Changed
 
+## Version 2.0.0-beta.6 - 26.03.26
+
+### Added
+- Provide detailed plan for v1 to v2 HANA migration
+- Generation of `.hdbmigrationtable` and updating `undeploy.json` via `cds add change-tracking-migration`
+- HANA procedure `SAP_CHANGELOG_RESTORE_BACKLINKS` to restore parent-child hierarchy for composition changes
+
+### Fixed
+- Explicit type casts for Date, DateTime, Time, Timestamp and Decimal fields in `ChangeView` to avoid conversion errors
+- Lazy load database adapters to prevent crashes when optional dependencies are not installed
+- Skip changelogs referencing association targets annotated with `@cds.persistence.skip`
+- Cast single entity keys to `cds.String` to prevent type conversion errors
+- Dynamic localization now verifies `.texts` entity existence before attempting localized lookup
+
+
+## Version 2.0.0-beta.5 - 17.03.26
+
+### Added
+- Support dynamic localized label lookup, meaning if for example a property is change tracked and its change tracking label (@changelog : [<association>.<localized_prop>]) points to one localized property from its code list entity, the label is dynamically fetched when the change is read based on the users locale.
+
+### Fixed
+- Postgres considers `disable*Tracking` for children changes
+- Human-readable `@changelog` annotation supports combination of direct entity elements and association elements
+
 ## Version 2.0.0-beta.4 - 16.03.26
 
 ### Added

package/README.md

@@ -177,12 +177,44 @@ customer @changelog: [customer.name];
 
 <img width="1300" alt="change-history-value-hr" src="_assets/changes-value-hr-wbox.png">
 
+#### Localized values
+If a human-readable value is annotated for the changelog, it will be localized.
+
+```cds
+extend Incidents with elements {
+  status: Association to one Status @changelog: [status.descr];
+}
+
+entity Status {
+  key code: String(1);
+      descr: localized String(20);
+}
+```
+
+By default the value label stored for the change is localized in the language of the user who caused the change. Meaning if a German speaking user changes the status, the human-readable value would be by default in German.
+
+In cases, like above, where the human-readable value only consists of one field, targets a localized property and goes along the (un-)managed association, a dynamic human-readable value is used, meaning if an English-speaking user looks at the changes, the value label will be shown in English, for a French-speaking user in French and so on.
+
 ### Tracing any kind of change
 
 Change tracking is implemented with Database triggers and supports HANA Cloud, SQLite, Postgres and H2.
 
 Leveraging database triggers means any change will be tracked no matter how it is represented in the service. Thus tracking changes made via unions, or via views with joins will still work.
 
+#### Tracking datetime fields with a fixed time zone
+
+The plugin supports tracking datetime field changes when the field has a time zone annotated.
+
+```cds
+extend Incidents with elements {
+  closedAt : DateTime @changelog @Common.Timezone : 'Europe/Berlin';
+  openedAt : DateTime @changelog @Common.Timezone : openedTimeZone;
+  openedTimeZone : String @Common.IsTimezone;
+}
+```
+
+In both cases the plugin will show the annotated time zone for change values in changes for the two fields. In the second case the time zone is dynamically fetched and modifications to the time zone field will also reflect in the change records for that field.
+
 ## Advanced Options
 
 ### Altered table view

package/cds-plugin.js

@@ -17,3 +17,5 @@ cds.once('served', async () => {
 registerH2CompilerHook();
 registerPostgresCompilerHook();
 registerHDICompilerHook();
+
+cds.add?.register?.('change-tracking-migration', require('./lib/addMigrationTable.js'));

package/index.cds

@@ -45,17 +45,11 @@ view ChangeView as
     key change.ID                                               @UI.Hidden,
         change.parent                            : redirected to ChangeView,
         change.children                          : redirected to ChangeView,
-        change.attribute,
-        change.valueChangedFrom,
-        change.valueChangedTo,
-        change.entity,
-        change.entityKey,
-        change.objectID,
-        change.modification,
-        change.valueDataType,
-        change.createdAt,
-        change.createdBy,
-        change.transactionID,
+        // Needed to make the * possible
+        attributeI18n.locale @UI.Hidden,
+        attributeI18n.text @UI.Hidden,
+        // * is important to allow for application extensions of Changes
+        *,
         COALESCE(
           attributeI18n.text, (
             select text from i18nKeys
@@ -89,9 +83,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.DateTime'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedFromLabel, change.valueChangedFrom
-                      )
+                      ) as DateTime)
             else null
           end
         )    as valueChangedFromLabelDateTime    : DateTime     @(title: '{i18n>Changes.valueChangedFrom}',
@@ -99,9 +93,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.DateTime' or valueDataType = 'cds.Timestamp'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedFromLabel, change.valueChangedFrom
-                      )
+                      ) as DateTime)
             else null
           end
         )    as valueChangedFromLabelDateTimeWTZ : DateTime     @(
@@ -111,9 +105,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.Time'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedFromLabel, change.valueChangedFrom
-                      )
+                      ) as Time)
             else null
           end
         )    as valueChangedFromLabelTime        : Time         @(title: '{i18n>Changes.valueChangedFrom}',
@@ -121,9 +115,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.Date'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedFromLabel, change.valueChangedFrom
-                      )
+                      ) as Date)
             else null
           end
         )    as valueChangedFromLabelDate        : Date         @(title: '{i18n>Changes.valueChangedFrom}',
@@ -131,9 +125,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.Timestamp'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedFromLabel, change.valueChangedFrom
-                      )
+                      ) as Timestamp)
             else null
           end
         )    as valueChangedFromLabelTimestamp   : Timestamp    @(title: '{i18n>Changes.valueChangedFrom}',
@@ -141,9 +135,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.Decimal'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedFromLabel, change.valueChangedFrom
-                      )
+                      ) as Decimal)
             else null
           end
         )    as valueChangedFromLabelDecimal     : Decimal      @(title: '{i18n>Changes.valueChangedFrom}',
@@ -157,9 +151,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.DateTime'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedToLabel, change.valueChangedTo
-                      )
+                      ) as DateTime)
             else null
           end
         )    as valueChangedToLabelDateTime      : DateTime     @(title: '{i18n>Changes.valueChangedTo}',
@@ -167,9 +161,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.DateTime' or valueDataType = 'cds.Timestamp'
-                 then COALESCE(
-                        change.valueChangedFromLabel, change.valueChangedTo
-                      )
+                 then cast(COALESCE(
+                        change.valueChangedToLabel, change.valueChangedTo
+                      ) as DateTime)
             else null
           end
         )    as valueChangedToLabelDateTimeWTZ   : DateTime     @(
@@ -179,9 +173,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.Time'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedToLabel, change.valueChangedTo
-                      )
+                      ) as Time)
             else null
           end
         )    as valueChangedToLabelTime          : Time         @(title: '{i18n>Changes.valueChangedTo}',
@@ -189,9 +183,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.Date'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedToLabel, change.valueChangedTo
-                      )
+                      ) as Date)
             else null
           end
         )    as valueChangedToLabelDate          : Date         @(title: '{i18n>Changes.valueChangedTo}',
@@ -199,9 +193,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.Timestamp'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedToLabel, change.valueChangedTo
-                      )
+                      ) as Timestamp)
             else null
           end
         )    as valueChangedToLabelTimestamp     : Timestamp    @(title: '{i18n>Changes.valueChangedTo}',
@@ -209,9 +203,9 @@ view ChangeView as
         (
           case
             when valueDataType = 'cds.Decimal'
-                 then COALESCE(
+                 then cast(COALESCE(
                         change.valueChangedToLabel, change.valueChangedTo
-                      )
+                      ) as Decimal)
             else null
           end
         )    as valueChangedToLabelDecimal       : Decimal      @(title: '{i18n>Changes.valueChangedTo}',

package/lib/addMigrationTable.js

@@ -0,0 +1,59 @@
+const cds = require('@sap/cds');
+const { fs, path } = cds.utils;
+const { join } = path;
+
+const MIGRATION_TABLE_PATH = join('db', 'src', 'sap.changelog.Changes.hdbmigrationtable');
+const UNDEPLOY_JSON_PATH = join('db', 'undeploy.json');
+
+const UNDEPLOY_ENTRIES = ['src/gen/**/sap.changelog.Changes.hdbtable', 'src/gen/**/sap.changelog.ChangeLog.hdbtable'];
+
+const LOG = cds.log('change-tracking');
+
+const { getMigrationTableSQL } = require('./hana/migrationTable.js');
+
+module.exports = class extends cds.add.Plugin {
+	async run() {
+		if (fs.existsSync(MIGRATION_TABLE_PATH)) {
+			const existing = fs.readFileSync(MIGRATION_TABLE_PATH, 'utf8');
+			const versionMatch = [...existing.matchAll(/==\s*version=(\d+)/g)];
+			const latestVersion = versionMatch.length > 0 ? Math.max(...versionMatch.map((m) => parseInt(m[1]))) : 1;
+
+			if (latestVersion >= 2) {
+				LOG.warn(`Migration table already exists at ${MIGRATION_TABLE_PATH} (latest version: ${latestVersion}). ` + `Only the initial v1 -> v2 migration is supported by this command. ` + `Please add new migration steps manually.`);
+				return;
+			}
+
+			// Rewrite file with v2 DDL and migration (replaces v1 content)
+			fs.writeFileSync(MIGRATION_TABLE_PATH, getMigrationTableSQL());
+			LOG.info(`Updated ${MIGRATION_TABLE_PATH} with v2 migration`);
+		} else {
+			// Write the migration table file
+			const dir = join('db', 'src');
+			if (!fs.existsSync(dir)) {
+				fs.mkdirSync(dir, { recursive: true });
+			}
+			fs.writeFileSync(MIGRATION_TABLE_PATH, getMigrationTableSQL());
+			LOG.info(`Created ${MIGRATION_TABLE_PATH}`);
+		}
+
+		// Update undeploy.json
+		let undeploy = [];
+		if (fs.existsSync(UNDEPLOY_JSON_PATH)) {
+			undeploy = JSON.parse(fs.readFileSync(UNDEPLOY_JSON_PATH, 'utf8'));
+		}
+		if (!Array.isArray(undeploy)) undeploy = [];
+
+		let changed = false;
+		for (const entry of UNDEPLOY_ENTRIES) {
+			if (!undeploy.includes(entry)) {
+				undeploy.push(entry);
+				changed = true;
+			}
+		}
+
+		if (changed) {
+			fs.writeFileSync(UNDEPLOY_JSON_PATH, JSON.stringify(undeploy, null, 4) + '\n');
+			LOG.info(`Updated ${UNDEPLOY_JSON_PATH} with old .hdbtable entries`);
+		}
+	}
+};

package/lib/csn-enhancements/dynamicLocalization.js

@@ -0,0 +1,106 @@
+const cds = require('@sap/cds');
+const { isChangeTracked, getBaseEntity, getBaseElement } = require('../utils/entity-collector');
+const DEBUG = cds.debug('change-tracking');
+
+/**
+ * Dynamic localization, primarily for code list scenarios, where a status field is change tracked but its localized label should be shown.
+ * @param {*} serviceName
+ * @param {*} m
+ */
+function collectTrackedPropertiesWithDynamicLocalization(serviceName, m) {
+	const dynamicLocalizationProperties = [];
+	for (const name in m.definitions) {
+		if (!name.startsWith(serviceName) || m.definitions[name].kind !== 'entity' || !isChangeTracked(m.definitions[name])) {
+			continue;
+		}
+		const entity = m.definitions[name];
+		const base = getBaseEntity(entity, m);
+		if (!base) continue;
+		for (const ele in entity.elements) {
+			const element = entity.elements[ele];
+			if (!Array.isArray(element['@changelog']) || element['@changelog'].length !== 1 || !element['@changelog'][0]?.['='] || element._foreignKey4) {
+				continue;
+			}
+			const segments = element['@changelog'][0]['='].split('.');
+			const baseEleInfo = getBaseElement(ele, entity, m);
+			const basePropertyName = baseEleInfo?.baseElement ?? ele;
+			// Managed association target or as fallback unmanaged association target
+			const target = element.target ?? m.definitions[base.baseRef ?? name].elements[segments[0]].target;
+			const basePropertyInUnmanagedOnCondition = m.definitions[base.baseRef ?? name].elements[segments[0]].on?.some((r) => r.ref && r.ref[0] === basePropertyName);
+			const isLocalizedField = m.definitions[target].elements?.[segments[1]]?.localized;
+			const amountOfKeys = Object.keys(m.definitions[target].elements).filter((e) => m.definitions[target].elements[e].key).length;
+			if (!target || (segments[0] !== basePropertyName && !basePropertyInUnmanagedOnCondition) || segments.length !== 2 || !isLocalizedField || amountOfKeys > 1) {
+				DEBUG &&
+					DEBUG(
+						`Dynamic localization lookup is not performed on ${ele} of ${name} for the path "${element['@changelog'][0]['=']}". Only paths which follow the properties association, which only navigate one level deep and where the last property is localized are supported.`
+					);
+				continue;
+			}
+
+			if (!dynamicLocalizationProperties.some((prop) => prop.property === basePropertyName && prop.entity === base.baseRef) && m.definitions[target + '.texts']) {
+				dynamicLocalizationProperties.push({
+					property: basePropertyName,
+					entity: base.baseRef,
+					dynamicLabel: SELECT.from(target + '.texts')
+						.alias('localizationSubSelect')
+						.where('1 = 1')
+						.columns(segments[1])
+				});
+			}
+			DEBUG && DEBUG(`${ele} of ${name} is change tracked and its logs are visualized using a dynamic localized label lookup targeting ${target + '.texts'} for the label ${segments[1]}.`);
+		}
+	}
+	return dynamicLocalizationProperties;
+}
+
+function enhanceChangeViewWithLocalization(serviceName, changeViewName, m) {
+	const changeView = m.definitions[changeViewName];
+	if (changeView['@changelog.internal.localizationEnhanced']) return;
+	DEBUG && DEBUG(`Enhance change view ${changeViewName} with dynamic localization setup.`);
+	const localizationProperties = collectTrackedPropertiesWithDynamicLocalization(serviceName, m);
+	if (!localizationProperties.length) return;
+	const changeViewCqn = changeView.projection ?? changeView.query.SELECT;
+	changeViewCqn.columns ??= ['*'];
+	changeViewCqn.from.as ??= 'change';
+	let valueChangedFromLabel = changeViewCqn.columns.find((c) => c.as && c.as === 'valueChangedFromLabel');
+	if (!valueChangedFromLabel) {
+		changeViewCqn.columns.push({
+			cast: { type: 'cds.String' },
+			xpr: [{ ref: ['valueChangedFromLabel'] }],
+			as: 'valueChangedFromLabel'
+		});
+		valueChangedFromLabel = changeViewCqn.columns.at(-1);
+	}
+	let valueChangedToLabel = changeViewCqn.columns.find((c) => c.as && c.as === 'valueChangedToLabel');
+	if (!valueChangedToLabel) {
+		changeViewCqn.columns.push({
+			cast: { type: 'cds.String' },
+			xpr: [{ ref: ['valueChangedToLabel'] }],
+			as: 'valueChangedToLabel'
+		});
+		valueChangedToLabel = changeViewCqn.columns.at(-1);
+	}
+	const originalValueChangedFrom = valueChangedFromLabel.xpr;
+	const originalValueChangedTo = valueChangedToLabel.xpr;
+	valueChangedFromLabel.xpr = ['case'];
+	valueChangedToLabel.xpr = ['case'];
+	for (const localizationProp of localizationProperties) {
+		valueChangedFromLabel.xpr.push('when', { ref: ['attribute'] }, '=', { val: localizationProp.property }, 'and', { ref: ['entity'] }, '=', { val: localizationProp.entity }, 'then');
+		const subSelect = structuredClone(localizationProp.dynamicLabel);
+		const keys = Object.keys(m.definitions[localizationProp.dynamicLabel.SELECT.from.ref[0]].elements).filter((e) => e !== 'locale' && m.definitions[localizationProp.dynamicLabel.SELECT.from.ref[0]].elements[e].key);
+		subSelect.SELECT.where = [{ ref: [changeViewCqn.from.as, 'valueChangedFrom'] }, '=', { ref: ['localizationSubSelect', keys[0]] }, 'and', { ref: ['localizationSubSelect', 'locale'] }, '=', { ref: ['$user', 'locale'] }];
+		valueChangedFromLabel.xpr.push({ func: 'COALESCE', args: [subSelect, { xpr: originalValueChangedFrom }] });
+
+		valueChangedToLabel.xpr.push('when', { ref: ['attribute'] }, '=', { val: localizationProp.property }, 'and', { ref: ['entity'] }, '=', { val: localizationProp.entity }, 'then');
+		const subSelect2 = structuredClone(localizationProp.dynamicLabel);
+		subSelect2.SELECT.where = [{ ref: [changeViewCqn.from.as, 'valueChangedTo'] }, '=', { ref: ['localizationSubSelect', keys[0]] }, 'and', { ref: ['localizationSubSelect', 'locale'] }, '=', { ref: ['$user', 'locale'] }];
+		valueChangedToLabel.xpr.push({ func: 'COALESCE', args: [subSelect2, { xpr: originalValueChangedTo }] });
+	}
+	valueChangedFromLabel.xpr.push('else', { xpr: originalValueChangedFrom }, 'end');
+	valueChangedToLabel.xpr.push('else', { xpr: originalValueChangedTo }, 'end');
+	changeView['@changelog.internal.localizationEnhanced'] = true;
+}
+
+module.exports = {
+	enhanceChangeViewWithLocalization
+};

package/lib/csn-enhancements/index.js

@@ -4,6 +4,7 @@ const DEBUG = cds.debug('change-tracking');
 const { isChangeTracked, getBaseEntity, analyzeCompositions, getService } = require('../utils/entity-collector.js');
 const { addSideEffects, addUIFacet } = require('./annotations.js');
 const { enhanceChangeViewWithTimeZones } = require('./timezoneProperties.js');
+const { enhanceChangeViewWithLocalization } = require('./dynamicLocalization.js');
 
 /**
  * Returns a CQN expression for the composite key of an entity.
@@ -20,7 +21,7 @@ function entityKey4(entity) {
 			keys.push({ ref: [k] });
 		}
 	}
-	if (keys.length <= 1) return keys;
+	if (keys.length <= 1) return keys.map((k) => ({ ...k, cast: { type: 'cds.String' } }));
 
 	const xpr = [];
 	for (let i = 0; i < keys.length; i++) {
@@ -173,6 +174,7 @@ function enhanceModel(m) {
 							}
 						}
 					}
+					enhanceChangeViewWithLocalization(serviceName, `${serviceName}.ChangeView`, m);
 				}
 
 				DEBUG?.(

package/lib/csn-enhancements/timezoneProperties.js

@@ -46,9 +46,9 @@ function enhanceChangeViewWithTimeZones(changeView, m) {
 			? compositeKeyExprHANA
 			: isDeploy2Check('postgres') && m.meta.creator.match(/v6/)
 				? compositeKeyExprPG
-				: cds.env.requires?.db.kind === 'sqlite' && !cds.build
+				: cds.env.requires?.db?.kind === 'sqlite' && !cds.build
 					? compositeKeyExprSqlite
-					: cds.env.requires?.db.kind === 'postgres' && (!cds.build || cds.env.profiles.includes('pg'))
+					: cds.env.requires?.db?.kind === 'postgres' && (!cds.build || cds.env.profiles.includes('pg'))
 						? compositeKeyExprPG
 						: compositeKeyExprHANA;
 	const timezoneProperties = collectTrackedPropertiesWithTimezone(m);

package/lib/h2/java-codegen.js

@@ -18,7 +18,7 @@ function _toSQL(query, model) {
 	return cqn2sql.SELECT(sqlCQN);
 }
 
-function handleAssocLookup(column, refRow, model) {
+function handleAssocLookup(column, assocPaths, refRow, model) {
 	let bindings = [];
 	let where = {};
 
@@ -36,11 +36,11 @@ function handleAssocLookup(column, refRow, model) {
 		bindings = column.on.map((assoc) => `${refRow}.getString("${assoc}")`);
 	}
 
-	const alt = column.alt.map((s) => s.split('.').slice(1).join('.'));
+	const alt = assocPaths.map((s) => s.split('.').slice(1).join('.'));
 	const columns = alt.length === 1 ? alt[0] : utils.buildConcatXpr(alt);
 
 	// Check if target entity has localized data
-	const localizedInfo = utils.getLocalizedLookupInfo(column.target, column.alt, model);
+	const localizedInfo = utils.getLocalizedLookupInfo(column.target, assocPaths, model);
 
 	if (localizedInfo) {
 		// Build locale-aware lookup: try .texts table first, fall back to base entity
@@ -676,12 +676,40 @@ function _prepareValueExpression(col, rowVar) {
 
 // Returns label expression for a column
 function _prepareLabelExpression(col, rowVar, model) {
-	if (col.target && col.alt) {
-		const { sql, bindings } = handleAssocLookup(col, rowVar, model);
-		return { sqlExpr: sql, bindings: bindings };
+	if (!col.alt || col.alt.length === 0) {
+		return { sqlExpr: 'NULL', bindings: [] };
 	}
-	// No label for scalars or associations without @changelog override
-	return { sqlExpr: 'NULL', bindings: [] };
+
+	const sqlParts = [];
+	const allBindings = [];
+	let assocBatch = [];
+
+	const flushAssocBatch = () => {
+		if (assocBatch.length > 0) {
+			const { sql, bindings } = handleAssocLookup(col, assocBatch, rowVar, model);
+			sqlParts.push(sql);
+			allBindings.push(...bindings);
+			assocBatch = [];
+		}
+	};
+
+	for (const entry of col.alt) {
+		if (entry.source === 'assoc') {
+			assocBatch.push(entry.path);
+		} else {
+			flushAssocBatch();
+			sqlParts.push('?');
+			allBindings.push(`${rowVar}.getString("${entry.path}")`);
+		}
+	}
+	flushAssocBatch();
+
+	if (sqlParts.length === 0) {
+		return { sqlExpr: 'NULL', bindings: [] };
+	}
+
+	const sqlExpr = sqlParts.length === 1 ? sqlParts[0] : sqlParts.join(" || ', ' || ");
+	return { sqlExpr, bindings: allBindings };
 }
 
 function _wrapInTryCatch(sql, bindings) {

package/lib/hana/migrationTable.js

@@ -0,0 +1,69 @@
+/**
+ * Returns the .hdbmigrationtable content for migrating sap.changelog.Changes from v1 to v2.
+ */
+
+function getMigrationTableSQL() {
+	return `== version=2
+COLUMN TABLE sap_changelog_Changes (
+  ID NVARCHAR(36) NOT NULL,
+  parent_ID NVARCHAR(36),
+  attribute NVARCHAR(127),
+  valueChangedFrom NVARCHAR(5000),
+  valueChangedTo NVARCHAR(5000),
+  valueChangedFromLabel NVARCHAR(5000),
+  valueChangedToLabel NVARCHAR(5000),
+  entity NVARCHAR(150),
+  entityKey NVARCHAR(5000),
+  objectID NVARCHAR(5000),
+  modification NVARCHAR(6),
+  valueDataType NVARCHAR(5000),
+  createdAt TIMESTAMP,
+  createdBy NVARCHAR(255),
+  transactionID BIGINT,
+  PRIMARY KEY(ID)
+)
+
+== migration=2
+RENAME COLUMN sap_changelog_Changes.entityID TO objectID;
+
+ALTER TABLE sap_changelog_Changes ADD (parent_ID NVARCHAR(36), valueChangedFromLabel NVARCHAR(5000), valueChangedToLabel NVARCHAR(5000), transactionID BIGINT);
+
+-- Adjust entityKey structure
+RENAME COLUMN sap_changelog_Changes.keys TO entityKey;
+UPDATE SAP_CHANGELOG_CHANGES
+SET entityKey =
+    CASE
+        WHEN LOCATE(entityKey, '=') > 0 THEN
+              TRIM(SUBSTRING(entityKey, LOCATE(entityKey, '=') + 1))
+        ELSE
+            NULL
+    END;
+
+-- Copy changelog_ID into transactionID
+UPDATE SAP_CHANGELOG_CHANGES SET transactionID = CAST(SECONDS_BETWEEN(createdAt, TO_TIMESTAMP('1970-01-01 00:00:00')) * -1000 AS BIGINT);
+
+-- Column migration for attribute, entity and modification
+ALTER TABLE sap_changelog_Changes ADD (attribute_tmp NVARCHAR(127), entity_tmp NVARCHAR(150), modification_tmp NVARCHAR(6));
+
+-- Copy data into temp columns
+UPDATE sap_changelog_Changes SET attribute_tmp = attribute;
+UPDATE sap_changelog_Changes SET entity_tmp = entity;
+UPDATE sap_changelog_Changes SET modification_tmp = modification;
+
+ALTER TABLE sap_changelog_Changes DROP (attribute, entity, modification);
+
+ALTER TABLE sap_changelog_Changes ADD (attribute NVARCHAR(127), entity NVARCHAR(150), modification NVARCHAR(6));
+
+-- Restore data from temp columns
+UPDATE sap_changelog_Changes SET attribute = attribute_tmp;
+UPDATE sap_changelog_Changes SET entity = entity_tmp;
+UPDATE sap_changelog_Changes SET modification = modification_tmp;
+
+ALTER TABLE sap_changelog_Changes DROP (attribute_tmp, entity_tmp, modification_tmp);
+
+-- Drop columns that are no longer needed
+ALTER TABLE sap_changelog_Changes DROP (serviceEntity, parentEntityID, parentKey, serviceEntityPath, changeLog_ID);
+`;
+}
+
+module.exports = { getMigrationTableSQL };

package/lib/hana/register.js

@@ -3,6 +3,12 @@ const cds = require('@sap/cds');
 const { prepareCSNForTriggers, generateTriggersForEntities, ensureUndeployJsonHasTriggerPattern } = require('../utils/trigger-utils.js');
 const { getLabelTranslations } = require('../localization.js');
 
+const MIGRATION_TABLE_PATH = cds.utils.path.join('db', 'src', 'sap.changelog.Changes.hdbmigrationtable');
+
+function hasMigrationTable() {
+	return cds.utils.fs.existsSync(MIGRATION_TABLE_PATH);
+}
+
 function registerHDICompilerHook() {
 	const _hdi_migration = cds.compiler.to.hdi.migration;
 	cds.compiler.to.hdi.migration = function (csn, options, beforeImage) {
@@ -38,20 +44,37 @@ function registerHDICompilerHook() {
 			);
 		}
 
+		const config = cds.env.requires?.['change-tracking'];
+
+		// Generate restore backlinks procedure if enabled via feature flag
+		if (config?.procedureForRestoringBacklinks) {
+			const { generateRestoreBacklinksProcedure } = require('./restoreProcedure.js');
+			const procedure = generateRestoreBacklinksProcedure(runtimeCSN, hierarchy, entities);
+			if (procedure) data.push(procedure);
+		}
+
+		// Auto-detect migration table created by `cds add change-tracking`
+		if (hasMigrationTable()) {
+			csn.definitions['sap.changelog.Changes']['@cds.persistence.journal'] = true;
+		}
+
 		const ret = _hdi_migration(csn, options, beforeImage);
 		ret.definitions = ret.definitions.concat(triggers).concat(data);
 		return ret;
 	};
 
-	// REVISIT: Remove once time casting is fixed in cds-dbs
-	cds.on('serving', async () => {
-		if (cds.env.requires?.db.kind !== 'hana') return;
-		const db = await cds.connect.to('db');
-		db.before('*', () => {
-			// to_time conversion is necessary else HANA tries to convert to timestamp implicitly causing an SQL crash
-			db.class.CQN2SQL.OutputConverters.Time = (e) => `to_char(to_time(${e}), 'HH24:MI:SS')`;
-		});
-	});
+	// When a migration table file exists in db/src/, strip compiler-generated changesets for sap.changelog.Changes
+	// Prevent auto-generation of additional migration steps by the build
+	const _compile_to_hana = cds.compile.to.hana;
+	cds.compile.to.hana = function (csn, o, beforeCsn) {
+		if (hasMigrationTable() && beforeCsn) {
+			// Remove the Changes entity from the beforeImage so the compiler
+			const beforeClone = structuredClone(beforeCsn);
+			delete beforeClone.definitions?.['sap.changelog.Changes'];
+			return _compile_to_hana.call(this, csn, o, beforeClone);
+		}
+		return _compile_to_hana.call(this, csn, o, beforeCsn);
+	};
 }
 
 module.exports = { registerHDICompilerHook };