From 2d1e36ba485272aad2d3aa46668b55fc47bccca3 Mon Sep 17 00:00:00 2001 From: Simon Oswald <126768147+simonoswald@users.noreply.github.com> Date: Fri, 12 Apr 2024 10:10:22 +0200 Subject: [PATCH 01/28] Rough draft of guide --- cds/compiler-hdbcds-to-hdbtable.md | 139 +++++++++++++++++++++++++++++ 1 file changed, 139 insertions(+) create mode 100644 cds/compiler-hdbcds-to-hdbtable.md diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md new file mode 100644 index 000000000..1c029763a --- /dev/null +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -0,0 +1,139 @@ +--- +shorty: Moving from .hdbcds to .hdbtable +synopsis: > + This document describes the issues to expect when migrating from .hdbcds-based HDI deployment to .hdbtable-based HDI deployment. + +# layout: cds-ref +redirect_from: releases/compiler-v2 +status: internal +--- + +# Moving from .hdbcds to .hdbtable + +{{ $frontmatter.synopsis }} + +With @sap/cds-compiler@5 we've deprecated the `to.hdbcds` function. We will not be developing new features for it. + +In order to move from `to.hdbcds` to the .hdbtable-based `to.hdi` three steps need to be done: + +- ensure your current datamodel is actually the deployed datamodel +- switch the deployment format from `hdbcds` to `hdbtable` using option `cds.requires.db.deploy-format` +- set `undeploy.json` to undeploy all the CAP-generated .hdbcds-files + +::: code-group + +```json [db/undeploy.json] +[ + "src/gen/**/*.hdbcds" +] +``` +::: + +- build and deploy your datamodel + +In theory, there is an intelligent handover mechanism when following the above steps that inside of HDI simply switches ownership of the tables to the .hdbtable plugin and does not require a full table migration. In practice, there are some scenarios where the .hdbcds we generate and the .hdbtable we generate do not allow a seamless migration. + +If the tables do not contain much data, it should not make that much of a difference. With huge amounts of data, expect a longer and more resource intensive deployment! + +So far we've identified the following scenarios where a seamless migration is not possible - one of them with a workaround: + +## `WITH ASSOCIATIONS` + +Unfortunately associations cause issues in our .hdbcds to .hdbtable handover. With the option `withHanaAssociations`, you can ensure that associations will not be part of the .hdbcds and .hdbtable files and therefore not hinder the migration. + +This only works if your custom coding does not use these associations on the database. + +::: code-group + +```json [cdsrc.json] +{ + "cdsc": { + "withHanaAssociations": false + } +} +``` +::: + +Once you've set this option, run a new build of your .hdbcds artifacts. The should not contain the associations anymore. Deploy these newly generated files and then proceed with the steps described initially. + + + + +## timesliced temporal/@cds.valid.key + +```cds +aspect temporal { + validFrom : Timestamp @cds.valid.from; + validTo : Timestamp @cds.valid.to; +}; + +aspect timesliced_temporal : temporal { + sliceId : UUID @cds.valid.key; // time slice ID +} + +entity TemporalWithTimeSliceId : timesliced_temporal { + key id : UUID; // logical record ID +} +``` + +In the above sample, the entity `TemporalWithTimeSliceId` canot be seamlessly migrated and a full table migration will take place. + +## Multiline doc comments + +```cds +service Service { + + entity BaseEntity { + /** + * I am the element description. + * Has a description + * + * With multiple paragraphs - I should not be part of the HANA comment + */ + key id: Integer; + }; +} +``` + +In the above sample, the entity `Service.BaseEntity` canot be seamlessly migrated and a full table migration will take place. This is due to a difference in the way `doc`-comments are passed to the database. + +::: code-group + +```json [cdsrc.json] +{ + "hana": { + "comments": true + } +} +``` +::: + + + +If you don't actually need the comments on database-level, then you can disable them with option `hana.comments`. Once you've set this option, run a new build of your .hdbcds artifacts. The should not contain the associations anymore. Deploy these newly generated files and then proceed with the steps described initially. + +## Stored calculated elements with `not null` + +```cds +entity OnWrite.Base { + key id : String; + + @annoKey: 'key' + field: Integer not null default 42; + + // Explicit casts (/ normal type mechanism) + calcCastField = cast(field as OnWrite.Base:field) stored; + calcExplicitTypeField : OnWrite.Base:field = field stored; + + // Same as above, but we want a string and no properties from OnWrite.Base:field + calcCast = cast(field as String) stored; + calcExplicitType : String = field stored; +}; +``` + +In the above sample, the entity `OnWrite.Base` canot be seamlessly migrated and a full table migration will take place. + +## @sql.append and @sql.prepend + +Native database features added via `@sql.append` and `@sql.prepend` might work or might not - we cannot offer any guidance here. + From 68fd104d7e4c146867aa2edf26f8d5407ba2d5ba Mon Sep 17 00:00:00 2001 From: Simon Oswald <126768147+simonoswald@users.noreply.github.com> Date: Mon, 15 Apr 2024 13:22:22 +0200 Subject: [PATCH 02/28] Remove part about calculated elements --- cds/compiler-hdbcds-to-hdbtable.md | 21 --------------------- 1 file changed, 21 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 1c029763a..48879f47c 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -112,27 +112,6 @@ In the above sample, the entity `Service.BaseEntity` canot be seamlessly migrate If you don't actually need the comments on database-level, then you can disable them with option `hana.comments`. Once you've set this option, run a new build of your .hdbcds artifacts. The should not contain the associations anymore. Deploy these newly generated files and then proceed with the steps described initially. -## Stored calculated elements with `not null` - -```cds -entity OnWrite.Base { - key id : String; - - @annoKey: 'key' - field: Integer not null default 42; - - // Explicit casts (/ normal type mechanism) - calcCastField = cast(field as OnWrite.Base:field) stored; - calcExplicitTypeField : OnWrite.Base:field = field stored; - - // Same as above, but we want a string and no properties from OnWrite.Base:field - calcCast = cast(field as String) stored; - calcExplicitType : String = field stored; -}; -``` - -In the above sample, the entity `OnWrite.Base` canot be seamlessly migrated and a full table migration will take place. - ## @sql.append and @sql.prepend Native database features added via `@sql.append` and `@sql.prepend` might work or might not - we cannot offer any guidance here. From 82471ad1b96780a5e19fa0a170762dbcc9bb6b07 Mon Sep 17 00:00:00 2001 From: Simon Oswald <126768147+simonoswald@users.noreply.github.com> Date: Mon, 15 Apr 2024 13:22:34 +0200 Subject: [PATCH 03/28] Typo --- cds/compiler-hdbcds-to-hdbtable.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 48879f47c..667400a23 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -76,7 +76,7 @@ entity TemporalWithTimeSliceId : timesliced_temporal { } ``` -In the above sample, the entity `TemporalWithTimeSliceId` canot be seamlessly migrated and a full table migration will take place. +In the above sample, the entity `TemporalWithTimeSliceId` can't be seamlessly migrated and a full table migration will take place. ## Multiline doc comments @@ -95,7 +95,7 @@ service Service { } ``` -In the above sample, the entity `Service.BaseEntity` canot be seamlessly migrated and a full table migration will take place. This is due to a difference in the way `doc`-comments are passed to the database. +In the above sample, the entity `Service.BaseEntity` can't be seamlessly migrated and a full table migration will take place. This is due to a difference in the way `doc`-comments are passed to the database. ::: code-group From 885db97b311c3d6d09cd7764021b7fd04f14d3bf Mon Sep 17 00:00:00 2001 From: Simon Oswald <126768147+simonoswald@users.noreply.github.com> Date: Mon, 15 Apr 2024 13:28:31 +0200 Subject: [PATCH 04/28] Use temporal sample model + add @cds.valid.key --- cds/compiler-hdbcds-to-hdbtable.md | 27 +++++++++++++++++++-------- 1 file changed, 19 insertions(+), 8 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 667400a23..f7725088d 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -62,17 +62,28 @@ Once you've set this option, run a new build of your .hdbcds artifacts. The shou ## timesliced temporal/@cds.valid.key ```cds -aspect temporal { - validFrom : Timestamp @cds.valid.from; - validTo : Timestamp @cds.valid.to; -}; +namespace com.acme.hr; +using { temporal } from '@sap/cds/common'; +using { com.acme.common.Persons } from './common'; -aspect timesliced_temporal : temporal { - sliceId : UUID @cds.valid.key; // time slice ID +entity Employees : Persons { + jobs : Composition of many WorkAssignments on jobs.empl=$self; + job1 : Association to one /*of*/ WorkAssignments; } -entity TemporalWithTimeSliceId : timesliced_temporal { - key id : UUID; // logical record ID +entity WorkAssignments: temporal { + key ID : UUID; + sliceId : UUID @cds.valid.key; // ID of the time slice + role : String(111); + empl : Association to Employees; + dept : Association to Departments; +} + +entity Departments { + key ID : UUID; + name : String(111); + head : Association to Employees; + members : Association to many Employees on members.jobs.dept = $self; } ``` From b48414faf8d472c26ae9577ff4e2c2a3221703be Mon Sep 17 00:00:00 2001 From: Simon Oswald <126768147+simonoswald@users.noreply.github.com> Date: Mon, 15 Apr 2024 13:29:52 +0200 Subject: [PATCH 05/28] Bit better sample for doc comments --- cds/compiler-hdbcds-to-hdbtable.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index f7725088d..c0799cfe0 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -92,17 +92,15 @@ In the above sample, the entity `TemporalWithTimeSliceId` can't be seamlessly mi ## Multiline doc comments ```cds -service Service { - - entity BaseEntity { - /** - * I am the element description. - * Has a description - * - * With multiple paragraphs - I should not be part of the HANA comment - */ - key id: Integer; - }; +entity Employees { + key ID : Integer; + /** + * I am the description for "name". + * I span across multiple lines. + * + * With multiple paragraphs. + */ + name : String; } ``` From ffcf268e6f70c20a54ebd026b978b55e6d0aff43 Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Fri, 14 Jun 2024 18:20:47 +0200 Subject: [PATCH 06/28] some changes --- cds/compiler-hdbcds-to-hdbtable.md | 34 ++++++++++++++++++++++++------ node.js/cds-compile.md | 12 +++++------ 2 files changed, 33 insertions(+), 13 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index c0799cfe0..d64e94a02 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -8,28 +8,46 @@ redirect_from: releases/compiler-v2 status: internal --- -# Moving from .hdbcds to .hdbtable +# Moving from deploy format `hdbcds` to `hdbtable` {{ $frontmatter.synopsis }} -With @sap/cds-compiler@5 we've deprecated the `to.hdbcds` function. We will not be developing new features for it. +With @sap/cds-compiler@5 and @sap/cds@8, we have deprecated the deploy format `hdbcds` for SAP HANA, +together with the function [`to.hdbcds`](../node.js/cds-compile#hdbcds). +New CDS features will not be available for deploy format `hdbcds`, and it is going to be removed with one of the +next major releases. -In order to move from `to.hdbcds` to the .hdbtable-based `to.hdi` three steps need to be done: +In case your database deployment is still based on `hdbcds`, you should move to the default format `hdbtable` +with the following 4 steps. This guide assumes you use @sap/cds@7 or higher. -- ensure your current datamodel is actually the deployed datamodel -- switch the deployment format from `hdbcds` to `hdbtable` using option `cds.requires.db.deploy-format` -- set `undeploy.json` to undeploy all the CAP-generated .hdbcds-files +Info: The deploy format determines only the "medium" how your database model is brought to the database. +The resulting database tables and views are the same, independent of the deploy format. + +1. Ensure your current data model is actually the deployed data model. + **TBD** must it be exactly the same? Does it also work if the current model + is changed in comparison to the last deployed model. + +2. Switch the deploy format from `hdbcds` to the default `hdbtable` by removing option `cds.requires.db.deploy-format` + from your configuration file(s). + + + +3. Add an entry to `db/undeploy.json` to undeploy the CAP-generated `.hdbcds` files: ::: code-group ```json [db/undeploy.json] [ + ..., "src/gen/**/*.hdbcds" ] ``` ::: -- build and deploy your datamodel +**TODO** Without this entry, during HDI deployment you will get errors like ... + +4. Build and re-deploy your data model. + In theory, there is an intelligent handover mechanism when following the above steps that inside of HDI simply switches ownership of the tables to the .hdbtable plugin and does not require a full table migration. In practice, there are some scenarios where the .hdbcds we generate and the .hdbtable we generate do not allow a seamless migration. @@ -56,6 +74,8 @@ This only works if your custom coding does not use these associations on the dat Once you've set this option, run a new build of your .hdbcds artifacts. The should not contain the associations anymore. Deploy these newly generated files and then proceed with the steps described initially. +**TODO** requires that for node the new db drivers are used + diff --git a/node.js/cds-compile.md b/node.js/cds-compile.md index 83aa51dcd..6c9fb12dc 100644 --- a/node.js/cds-compile.md +++ b/node.js/cds-compile.md @@ -185,14 +185,10 @@ for (let [edm,{file,suffix}] of all) - ### .hdbtable() {.method} -### .hdbcds() {.method} - - -Generates `hdbtable/view` or `hdbcds` output. -Returns a generator that yields `[ src, {file} ]` for each resulting `.hdbtable`, `.hdbview`, or `.hdbcds` file. +Generates `hdbtable/hdbview` output. +Returns a generator that yields `[ src, {file} ]` for each resulting `.hdbtable` or `.hdbview` file. For example, use it as follows: ```js @@ -201,6 +197,10 @@ for (let [src,{file}] of all) console.log (file,src) ``` +### .hdbcds() - deprecated {.method} + +Similar to `.hdbtable()`, but generates `hdbcds` output insted of `hdbtable/hdbview`. +This function is deprecated and is going to be removed in the next major release. ### .sql() {.method} From d5df56042332c26d1bd1483de9b1ff92fe14b71c Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Thu, 20 Jun 2024 17:12:35 +0200 Subject: [PATCH 07/28] update --- cds/compiler-hdbcds-to-hdbtable.md | 166 +++++++++++++++++++---------- 1 file changed, 112 insertions(+), 54 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index d64e94a02..5124df9aa 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -1,7 +1,7 @@ --- shorty: Moving from .hdbcds to .hdbtable synopsis: > - This document describes the issues to expect when migrating from .hdbcds-based HDI deployment to .hdbtable-based HDI deployment. + This document describes the migrating from .hdbcds-based HDI deployment to .hdbtable-based HDI deployment. # layout: cds-ref redirect_from: releases/compiler-v2 @@ -12,6 +12,10 @@ status: internal {{ $frontmatter.synopsis }} +::: info +Not relevant for SAP HANA Cloud. +::: + With @sap/cds-compiler@5 and @sap/cds@8, we have deprecated the deploy format `hdbcds` for SAP HANA, together with the function [`to.hdbcds`](../node.js/cds-compile#hdbcds). New CDS features will not be available for deploy format `hdbcds`, and it is going to be removed with one of the @@ -24,8 +28,8 @@ Info: The deploy format determines only the "medium" how your database model is The resulting database tables and views are the same, independent of the deploy format. 1. Ensure your current data model is actually the deployed data model. - **TBD** must it be exactly the same? Does it also work if the current model - is changed in comparison to the last deployed model. + 2. Switch the deploy format from `hdbcds` to the default `hdbtable` by removing option `cds.requires.db.deploy-format` from your configuration file(s). @@ -44,72 +48,111 @@ The resulting database tables and views are the same, independent of the deploy ``` ::: -**TODO** Without this entry, during HDI deployment you will get errors like ... + 4. Build and re-deploy your data model. -In theory, there is an intelligent handover mechanism when following the above steps that inside of HDI simply switches ownership of the tables to the .hdbtable plugin and does not require a full table migration. In practice, there are some scenarios where the .hdbcds we generate and the .hdbtable we generate do not allow a seamless migration. +There is a handover mechanism inside HDI that, when following the above steps, simply switches ownership of the tables +to the hdbtable plugin. There are some caveats, however: + +* If you used annotations `@sql.append` or `sql.prepend`, your model very likely needs to be adapted manually + before the migration can be done. See the corresponding section below for more details. +* In some scenarios, the generated hdbcds and hdbtable files do not allow a seamless switchover, + and a full migration is done for the respective tables. + The scenarios we have identified so far are explained in separate sections below, for two of them there is a workaround. + +::: info Full Table Migration + +If HDI detects a difference between the CREATE statement in a hdbtable file and the already deployed +version of a table, it creates a temporary shadow table based on the new structure and copies +existing data into this shadow table. + +If the table doesn't contain much data, that should not make that much of a difference. +With huge amounts of data, you have to expect a longer and more resource intensive deployment. + +::: + + +## @sql.append and @sql.prepend + +Annotations [`@sql.append/prepend`](../guides/databases#sql-prepend-append) allow to +add native SQL clauses to the generated .hdbtable files, +or to add "native" HANA CDS clauses to the generated .hdbcds files, respectively. -If the tables do not contain much data, it should not make that much of a difference. With huge amounts of data, expect a longer and more resource intensive deployment! +If you have used these annotations in your model, a simple switchover from hdbcds to hdbtable +very likely is not possible, as such an annotation written for hdbcds in general is not valid +for hdbtable. You have to adapt your model prior to the migration. + +As we don't know what clauses you have used, we cannot offer any further guidance here. -So far we've identified the following scenarios where a seamless migration is not possible - one of them with a workaround: ## `WITH ASSOCIATIONS` -Unfortunately associations cause issues in our .hdbcds to .hdbtable handover. With the option `withHanaAssociations`, you can ensure that associations will not be part of the .hdbcds and .hdbtable files and therefore not hinder the migration. +Associations cause issues in the .hdbcds to .hdbtable handover. +For each entity that has associations, the resulting table or view contains a `WITH ASSOCIATIONS` clause, +representing native HANA associations. +This clause slightly differs, depending on whether it originates from a .hdbcds or a .hdbtable/.hdbview file, +which would causes a full table migration. + +The CAP Java runtime and the CAP Nodejs runtime with the new SAP HANA service (`@cap-js/hana`, default in CDS 8) +don't need the `WITH ASSOCIATIONS` clause any more. The workaround is to remove the `WITH ASSOCIATIONS` clause +__before__ the actual hdbcds to hdbtable migration. -This only works if your custom coding does not use these associations on the database. +First switch of the generation of the `WITH ASSOCIATIONS` clause (both for hdbcds and hdbtable): ::: code-group ```json [cdsrc.json] { - "cdsc": { - "withHanaAssociations": false + "sql": { + "native_hana_associations": false } } ``` ::: + -Once you've set this option, run a new build of your .hdbcds artifacts. The should not contain the associations anymore. Deploy these newly generated files and then proceed with the steps described initially. +Then run a new build and deploy the newly generated `.hdbcds` files. +The resulting database tables and views shouldn't contain the `WITH ASSOCIATIONS` clause anymore. +In contrast to the hdbtable plugin, the hdbcds plugin is able to handle removal of the +native associations without a full table migration. -**TODO** requires that for node the new db drivers are used +::: warning Requirements - +This workaround requires +* CAP CDS 8, +* that you use CAP Java or the CAP Nodejs runtime with the new HANA database service `@cap-js/hana`, +* and that your custom coding doesn't use the native associations on the database. +::: -## timesliced temporal/@cds.valid.key -```cds -namespace com.acme.hr; -using { temporal } from '@sap/cds/common'; -using { com.acme.common.Persons } from './common'; + -entity Employees : Persons { - jobs : Composition of many WorkAssignments on jobs.empl=$self; - job1 : Association to one /*of*/ WorkAssignments; -} -entity WorkAssignments: temporal { - key ID : UUID; - sliceId : UUID @cds.valid.key; // ID of the time slice - role : String(111); - empl : Association to Employees; - dept : Association to Departments; -} +## Multiline Doc Comments -entity Departments { - key ID : UUID; - name : String(111); - head : Association to Employees; - members : Association to many Employees on members.jobs.dept = $self; +This is only relevant if you have switched on [Doc Comments](../cds/cdl#doc-comments-%E2%80%94) +and if you have enabled translation of doc comments to the `COMMENT` feature in the database. + + -In the above sample, the entity `TemporalWithTimeSliceId` can't be seamlessly migrated and a full table migration will take place. - -## Multiline doc comments +Doc comments can span across multiple lines: ```cds entity Employees { @@ -117,31 +160,46 @@ entity Employees { /** * I am the description for "name". * I span across multiple lines. - * - * With multiple paragraphs. */ name : String; } ``` -In the above sample, the entity `Service.BaseEntity` can't be seamlessly migrated and a full table migration will take place. This is due to a difference in the way `doc`-comments are passed to the database. +An entity with such a multi-line doc domment can't be seamlessly migrated, because +doc comments are passed to the database differently for hdbcds and hdbtable, respectively. +This would result in a full table migration when changing from hdbcds to hdbtable. -::: code-group +If you don't actually need the comments in the database, you can remove them as a preparation step +__before__ you do the hdbcds to hdbtable migration. +This is similar to the workaround described above for the `WITH ASSOCIATIONS` clause. +First disable the doc comments by setting option `hana.comments` to `false`. +Then run a new build and deploy the newly generated `.hdbcds` files. +The resulting database tables and views shouldn't contain the `COMMENT` clause anymore. +In contrast to the hdbtable plugin, the hdbcds plugin is able to handle removal of the +`COMMENT`s without a full table migration. -```json [cdsrc.json] -{ - "hana": { - "comments": true - } -} -``` -::: + - -If you don't actually need the comments on database-level, then you can disable them with option `hana.comments`. Once you've set this option, run a new build of your .hdbcds artifacts. The should not contain the associations anymore. Deploy these newly generated files and then proceed with the steps described initially. +## Temporal Data with Time Slice IDs -## @sql.append and @sql.prepend +Temporal Data with [Time Slice IDs](../guides/temporal-data#adding-time-slice-ids) +is a conceptual feature, thus it shouldn't occur in productive applications. +We nevertheless mention it here for completeness. -Native database features added via `@sql.append` and `@sql.prepend` might work or might not - we cannot offer any guidance here. +Example: +```cds +// usually taken from '@sap/cds/common' +aspect temporal { + validFrom : Timestamp @cds.valid.from; + validTo : Timestamp @cds.valid.to; +} + +entity TimeDependentData : temporal { + key ID : UUID; + sliceId : UUID @cds.valid.key; + someData : String; +} +``` +In this example, entity `TimeDependentData` can't be seamlessly migrated and a full table migration will take place. From c15a7e16e7156e3b49e2444fa43cfa0171ee8ec6 Mon Sep 17 00:00:00 2001 From: Patrice Bender Date: Tue, 25 Jun 2024 16:30:27 +0200 Subject: [PATCH 08/28] Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- cds/compiler-hdbcds-to-hdbtable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 5124df9aa..5ab038904 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -165,7 +165,7 @@ entity Employees { } ``` -An entity with such a multi-line doc domment can't be seamlessly migrated, because +An entity with such a multi-line doc comment can't be seamlessly migrated, because doc comments are passed to the database differently for hdbcds and hdbtable, respectively. This would result in a full table migration when changing from hdbcds to hdbtable. From 00d9a6a29a0f83c3cec5a5d242a7d9e370168455 Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Wed, 26 Jun 2024 08:54:40 +0200 Subject: [PATCH 09/28] Apply suggestions from code review Co-authored-by: Patrice Bender --- cds/compiler-hdbcds-to-hdbtable.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 5ab038904..243eaabb9 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -1,7 +1,7 @@ --- shorty: Moving from .hdbcds to .hdbtable synopsis: > - This document describes the migrating from .hdbcds-based HDI deployment to .hdbtable-based HDI deployment. + This document describes the migration from .hdbcds-based HDI deployment to .hdbtable-based HDI deployment. # layout: cds-ref redirect_from: releases/compiler-v2 @@ -96,14 +96,14 @@ This clause slightly differs, depending on whether it originates from a .hdbcds which would causes a full table migration. The CAP Java runtime and the CAP Nodejs runtime with the new SAP HANA service (`@cap-js/hana`, default in CDS 8) -don't need the `WITH ASSOCIATIONS` clause any more. The workaround is to remove the `WITH ASSOCIATIONS` clause -__before__ the actual hdbcds to hdbtable migration. +don't need the `WITH ASSOCIATIONS` clause anymore. The workaround is to remove the `associations` from the `hdbcds` sources +__before__ the actual `hdbcds` to `hdbtable` migration. -First switch of the generation of the `WITH ASSOCIATIONS` clause (both for hdbcds and hdbtable): +First switch of the generation of the `associations` (that option accounts for "associations" in the `hdbcds` sources as well as for the `WITH ASSOCIATIONS` found in the `hdbtable` sources): ::: code-group -```json [cdsrc.json] +```json [.cdsrc.json] { "sql": { "native_hana_associations": false @@ -114,7 +114,7 @@ First switch of the generation of the `WITH ASSOCIATIONS` clause (both for hdbcd Then run a new build and deploy the newly generated `.hdbcds` files. -The resulting database tables and views shouldn't contain the `WITH ASSOCIATIONS` clause anymore. +The resulting database tables and views shouldn't contain any `associations` anymore. In contrast to the hdbtable plugin, the hdbcds plugin is able to handle removal of the native associations without a full table migration. From e24db4a2d4fdaf86edeefe1fc4df474975688d1d Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:44:01 +0200 Subject: [PATCH 10/28] Rephrase section on associations ... hopefully increasing clarity --- cds/compiler-hdbcds-to-hdbtable.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 243eaabb9..bf978602e 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -92,14 +92,20 @@ As we don't know what clauses you have used, we cannot offer any further guidanc Associations cause issues in the .hdbcds to .hdbtable handover. For each entity that has associations, the resulting table or view contains a `WITH ASSOCIATIONS` clause, representing native HANA associations. -This clause slightly differs, depending on whether it originates from a .hdbcds or a .hdbtable/.hdbview file, -which would causes a full table migration. + +When deplyoing via hdbcds, associations in a CAP CDS entity are reflected by corresponding associations in +the `hdbcds` file generated by the compiler. Upon deployment, the hdbcds plugin of HDI generates a `CREATE TABLE` +statement, where the associations are represented in a `WITH ASSOCIATIONS` clause. +When deploying via hdbtable, the compiler directly writes the `CREATE TABLE` statements with the `WITH ASSOCIATIONS` +clause into the generated `hdbtable` files. +These clauses slightly differ, which causes a full table migration when switching from hdbcds to hdbtable. The CAP Java runtime and the CAP Nodejs runtime with the new SAP HANA service (`@cap-js/hana`, default in CDS 8) -don't need the `WITH ASSOCIATIONS` clause anymore. The workaround is to remove the `associations` from the `hdbcds` sources -__before__ the actual `hdbcds` to `hdbtable` migration. +don't need the `WITH ASSOCIATIONS` clause anymore. This allows us to avoid the full table migration by removing +the `associations` from the `hdbcds` sources __before__ the actual `hdbcds` to `hdbtable` migration. -First switch of the generation of the `associations` (that option accounts for "associations" in the `hdbcds` sources as well as for the `WITH ASSOCIATIONS` found in the `hdbtable` sources): +First switch off the generation of the `associations` (that option accounts for "associations" in the `hdbcds` +sources as well as for the `WITH ASSOCIATIONS` found in the `hdbtable` sources): ::: code-group @@ -114,9 +120,9 @@ First switch of the generation of the `associations` (that option accounts for " Then run a new build and deploy the newly generated `.hdbcds` files. -The resulting database tables and views shouldn't contain any `associations` anymore. In contrast to the hdbtable plugin, the hdbcds plugin is able to handle removal of the native associations without a full table migration. +The resulting database tables and views don't contain any `associations` anymore. ::: warning Requirements From 17f3b3ceaa1fe41c8b250d1cb0f6dac3f4656fb1 Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Wed, 26 Jun 2024 12:45:00 +0200 Subject: [PATCH 11/28] Update cds/compiler-hdbcds-to-hdbtable.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- cds/compiler-hdbcds-to-hdbtable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index bf978602e..648679f05 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -93,7 +93,7 @@ Associations cause issues in the .hdbcds to .hdbtable handover. For each entity that has associations, the resulting table or view contains a `WITH ASSOCIATIONS` clause, representing native HANA associations. -When deplyoing via hdbcds, associations in a CAP CDS entity are reflected by corresponding associations in +When deploying via hdbcds, associations in a CAP CDS entity are reflected by corresponding associations in the `hdbcds` file generated by the compiler. Upon deployment, the hdbcds plugin of HDI generates a `CREATE TABLE` statement, where the associations are represented in a `WITH ASSOCIATIONS` clause. When deploying via hdbtable, the compiler directly writes the `CREATE TABLE` statements with the `WITH ASSOCIATIONS` From c73e446d5e905e77d49f8b4618ae3d261af5ef7c Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Wed, 26 Jun 2024 13:46:37 +0200 Subject: [PATCH 12/28] rephrase section on doc comments --- cds/compiler-hdbcds-to-hdbtable.md | 42 +++++++++++++++--------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 648679f05..71869eb97 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -97,7 +97,7 @@ When deploying via hdbcds, associations in a CAP CDS entity are reflected by cor the `hdbcds` file generated by the compiler. Upon deployment, the hdbcds plugin of HDI generates a `CREATE TABLE` statement, where the associations are represented in a `WITH ASSOCIATIONS` clause. When deploying via hdbtable, the compiler directly writes the `CREATE TABLE` statements with the `WITH ASSOCIATIONS` -clause into the generated `hdbtable` files. +clause into the generated `hdbtable` and `hdbview` files. These clauses slightly differ, which causes a full table migration when switching from hdbcds to hdbtable. The CAP Java runtime and the CAP Nodejs runtime with the new SAP HANA service (`@cap-js/hana`, default in CDS 8) @@ -145,19 +145,6 @@ This workaround requires This is only relevant if you have switched on [Doc Comments](../cds/cdl#doc-comments-%E2%80%94) and if you have enabled translation of doc comments to the `COMMENT` feature in the database. - - Doc comments can span across multiple lines: ```cds @@ -171,21 +158,34 @@ entity Employees { } ``` -An entity with such a multi-line doc comment can't be seamlessly migrated, because -doc comments are passed to the database differently for hdbcds and hdbtable, respectively. -This would result in a full table migration when changing from hdbcds to hdbtable. +When deploying via hdbcds, doc comments in a CAP CDS entity are reflected by corresponding `@Comment` annotations in +the `hdbcds` file generated by the compiler. Upon deployment, the hdbcds plugin of HDI generates a `CREATE TABLE` +statement, where the doc comments are represented by `COMMENT` clauses. +When deploying via hdbtable, the compiler directly writes the `CREATE TABLE` statements with the `COMMENT` +clauses into the generated `hdbtable` and `hdbview` files. +These `COMMENT` clauses slightly differ, which causes a full table migration when switching from hdbcds to hdbtable. If you don't actually need the comments in the database, you can remove them as a preparation step __before__ you do the hdbcds to hdbtable migration. This is similar to the workaround described above for the `WITH ASSOCIATIONS` clause. -First disable the doc comments by setting option `hana.comments` to `false`. + +First disable the doc comments by adapting your `.cdsrc.json`: +::: code-group +```json [cdsrc.json] +{ + "hana": { + "comments": false + } +} +``` +::: + Then run a new build and deploy the newly generated `.hdbcds` files. -The resulting database tables and views shouldn't contain the `COMMENT` clause anymore. +The `@Comment` annotations have vanished from the `hdbcds` files, thus +the resulting database tables and views don't contain the `COMMENT` clause anymore. In contrast to the hdbtable plugin, the hdbcds plugin is able to handle removal of the `COMMENT`s without a full table migration. - - ## Temporal Data with Time Slice IDs From 12b14f06a77e225ef18c42cab0877b3b1ef494c9 Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Wed, 26 Jun 2024 14:42:38 +0200 Subject: [PATCH 13/28] add a note --- cds/compiler-hdbcds-to-hdbtable.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 71869eb97..219e49d3a 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -186,6 +186,8 @@ the resulting database tables and views don't contain the `COMMENT` clause anymo In contrast to the hdbtable plugin, the hdbcds plugin is able to handle removal of the `COMMENT`s without a full table migration. +Note: If you need the comments in the database, this workaround will not help, +because switching them back on after moving to hdbtable will then result in a full table migration. ## Temporal Data with Time Slice IDs From c9ab29e85c6d877732a3ecf98ff6a7f6b3054189 Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Thu, 27 Jun 2024 10:14:44 +0200 Subject: [PATCH 14/28] Update cds/compiler-hdbcds-to-hdbtable.md Co-authored-by: simonoswald <126768147+simonoswald@users.noreply.github.com> --- cds/compiler-hdbcds-to-hdbtable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 219e49d3a..4abde2ab3 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -13,7 +13,7 @@ status: internal {{ $frontmatter.synopsis }} ::: info -Not relevant for SAP HANA Cloud. +If you are using SAP HANA Cloud, you don't have to do anything, as there is no HANA CDS on SAP HANA Cloud. ::: With @sap/cds-compiler@5 and @sap/cds@8, we have deprecated the deploy format `hdbcds` for SAP HANA, From 3fc046e10769ff4bf645f004eac602ec052f93aa Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Fri, 28 Jun 2024 11:17:30 +0200 Subject: [PATCH 15/28] Update cds/compiler-hdbcds-to-hdbtable.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: René Jeglinsky --- cds/compiler-hdbcds-to-hdbtable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 4abde2ab3..b48e49187 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -1,7 +1,7 @@ --- shorty: Moving from .hdbcds to .hdbtable synopsis: > - This document describes the migration from .hdbcds-based HDI deployment to .hdbtable-based HDI deployment. +The deploy format `hdbcds` for SAP HANA has been deprecated with @sap/cds-compiler@5 and @sap/cds@8, and users are advised to switch to the default format `hdbtable`. This guide provides a step-by-step process for making the switch, including potential issues and workarounds, such as handling annotations `@sql.append` or `sql.prepend`, dealing with associations, multiline doc comments, and temporal data with time slice IDs. # layout: cds-ref redirect_from: releases/compiler-v2 From ee0a7fd0c176e484b69eff441831b6694adf2297 Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Fri, 28 Jun 2024 11:27:03 +0200 Subject: [PATCH 16/28] Some modifications * adapt AI generated synopsis * made some notes to infor or warn blocks --- cds/compiler-hdbcds-to-hdbtable.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index b48e49187..30edaf7c6 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -1,7 +1,10 @@ --- shorty: Moving from .hdbcds to .hdbtable synopsis: > -The deploy format `hdbcds` for SAP HANA has been deprecated with @sap/cds-compiler@5 and @sap/cds@8, and users are advised to switch to the default format `hdbtable`. This guide provides a step-by-step process for making the switch, including potential issues and workarounds, such as handling annotations `@sql.append` or `sql.prepend`, dealing with associations, multiline doc comments, and temporal data with time slice IDs. +The deploy format `hdbcds` for SAP HANA has been deprecated with @sap/cds-compiler@5 and @sap/cds@8. +Users are advised to switch to the default format `hdbtable`. This guide provides a step-by-step description +for making the switch, including potential issues and workarounds, such as handling annotations `@sql.prepend/append` +and dealing with associations. # layout: cds-ref redirect_from: releases/compiler-v2 @@ -21,11 +24,14 @@ together with the function [`to.hdbcds`](../node.js/cds-compile#hdbcds). New CDS features will not be available for deploy format `hdbcds`, and it is going to be removed with one of the next major releases. +::: info Deploy Format +The deploy format determines only the "medium" how your database model is brought to the database. +The resulting database tables and views are the same, independent of the deploy format. +::: + In case your database deployment is still based on `hdbcds`, you should move to the default format `hdbtable` with the following 4 steps. This guide assumes you use @sap/cds@7 or higher. - -Info: The deploy format determines only the "medium" how your database model is brought to the database. -The resulting database tables and views are the same, independent of the deploy format. +Please read the entire guide before starting the migration. 1. Ensure your current data model is actually the deployed data model. -2. Switch the deploy format from `hdbcds` to the default `hdbtable` by removing option `cds.requires.db.deploy-format` - from your configuration file(s). +2. Switch the deploy format from `hdbcds` to the default `hdbtable`. You can do this by removing option `cds.requires.db.deploy-format` from your configuration file(s). 3. Add an entry to `db/undeploy.json` to undeploy the CAP-generated `.hdbcds` files: -::: code-group - -```json [db/undeploy.json] -[ - ..., - "src/gen/**/*.hdbcds" -] -``` -::: - - + ::: code-group + + ```json [db/undeploy.json] + [ + ..., + "src/gen/**/*.hdbcds" + ] + ``` + ::: + + 4. Build and re-deploy your data model. -There is a handover mechanism inside HDI that, when following the above steps, simply switches ownership of the tables -to the hdbtable plugin. There are some caveats, however: +By following these steps, the HDI's internal handover mechanism automatically transfers ownership of the tables to the hdbtable plugin. There are some caveats, however: * If you used annotations `@sql.append` or `sql.prepend`, your model very likely needs to be adapted manually before the migration can be done. See the corresponding section below for more details. @@ -74,13 +65,12 @@ If HDI detects a difference between the CREATE statement in a hdbtable file and version of a table, it creates a temporary shadow table based on the new structure and copies existing data into this shadow table. -If the table doesn't contain much data, that should not make that much of a difference. -With huge amounts of data, you have to expect a longer and more resource intensive deployment. +If the table doesn't contain much data, this process won't significantly impact the system. However, if the table contains a large amount of data, be prepared for a more time-consuming and resource-intensive deployment. ::: -## @sql.append and @sql.prepend +## Annotations Annotations [`@sql.append/prepend`](../guides/databases#sql-prepend-append) allow to add native SQL clauses to the generated .hdbtable files, @@ -93,7 +83,7 @@ for hdbtable. You have to adapt your model prior to the migration. As we don't know what clauses you have used, we cannot offer any further guidance here. -## `WITH ASSOCIATIONS` +## Associations Associations cause issues in the .hdbcds to .hdbtable handover. For each entity that has associations, the resulting table or view contains a `WITH ASSOCIATIONS` clause, From 6d564a461b16d4985c6d8f50c4031b6d159415da Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 28 Jun 2024 14:40:43 +0200 Subject: [PATCH 20/28] consistent formatting for format vs file --- cds/compiler-hdbcds-to-hdbtable.md | 60 +++++++++++++++--------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index f74c98eb2..1c40935f7 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -6,13 +6,13 @@ redirect_from: releases/compiler-v2 #status: internal --- -# Moving from deploy format `hdbcds` to `hdbtable` +# Moving from _.hdbcds_ to _.hdbtable_ ::: info Not relevant for SAP HANA Cloud If you are already using SAP HANA Cloud, there is no SAP HANA CDS. ::: -The deploy format `hdbcds` for SAP HANA together with the function [`to.hdbcds`](../node.js/cds-compile#hdbcds) has been deprecated with @sap/cds-compiler@5 and @sap/cds@8. Users are advised to switch to the default format `hdbtable`. This guide provides a step-by-step description for making the switch, including potential issues and workarounds, such as handling annotations `@sql.prepend/append` and dealing with associations. +The deploy format `hdbcds` for SAP HANA together with the function [`to.hdbcds`](../node.js/cds-compile#hdbcds) have been deprecated with `@sap/cds-compiler@5` and `@sap/cds@8`. Users are advised to switch to the default format `hdbtable`. This guide provides step-by-step instructions for making the switch, including potential issues and workarounds, such as handling annotations `@sql.prepend/append` and dealing with associations. New CDS features will not be available for deploy format `hdbcds`, and it is going to be removed with one of the next major releases. @@ -24,7 +24,7 @@ The resulting database tables and views are the same, independent of the deploy ## Migration Procedure -If your database deployment currently uses hdbcds, it's recommended to switch to the default format, hdbtable. This guide assumes you use @sap/cds@7 or higher. Make sure to read the entire guide before starting the migration process. +If your database deployment currently uses `hdbcds`, it's recommended to switch to the default format, `hdbtable`. This guide assumes you use @sap/cds@7 or higher. Make sure to read the entire guide before starting the migration process. 1. Ensure your current data model matches the deployed data model. -3. Add an entry to `db/undeploy.json` to undeploy the CAP-generated `.hdbcds` files: +3. Add an entry to `db/undeploy.json` to undeploy the CAP-generated _.hdbcds_ files: ::: code-group @@ -51,17 +51,17 @@ If your database deployment currently uses hdbcds, it's recommended to switch to 4. Build and re-deploy your data model. -By following these steps, the HDI's internal handover mechanism automatically transfers ownership of the tables to the hdbtable plugin. There are some caveats, however: +By following these steps, the HDI's internal handover mechanism automatically transfers ownership of the tables to the `hdbtable` plugin. There are some caveats, however: * If you used annotations `@sql.append` or `sql.prepend`, your model very likely needs to be adapted manually before the migration can be done. See the corresponding section below for more details. -* In some scenarios, the generated hdbcds and hdbtable files do not allow a seamless switchover, +* In some scenarios, the generated _.hdbcds_ and _.hdbtable_ files do not allow a seamless switchover, and a full migration is done for the respective tables. The scenarios we have identified so far are explained in separate sections below, for two of them there is a workaround. ::: info Full Table Migration -If HDI detects a difference between the CREATE statement in a hdbtable file and the already deployed +If HDI detects a difference between the CREATE statement in a _.hdbtable_ file and the already deployed version of a table, it creates a temporary shadow table based on the new structure and copies existing data into this shadow table. @@ -73,28 +73,28 @@ If the table doesn't contain much data, this process won't significantly impact ## Annotations Annotations [`@sql.append/prepend`](../guides/databases#sql-prepend-append) allow to -add native SQL clauses to the generated .hdbtable files, -or to add "native" HANA CDS clauses to the generated .hdbcds files, respectively. +add native SQL clauses to the generated _.hdbtable_ files, +or to add "native" HANA CDS clauses to the generated _.hdbcds_ files, respectively. -If you have used these annotations in your model, a simple switchover from hdbcds to hdbtable -very likely is not possible, as such an annotation written for hdbcds in general is not valid -for hdbtable. You have to adapt your model prior to the migration. +If you have used these annotations in your model, a simple switchover from `hdbcds` to `hdbtable` +very likely is not possible, as such an annotation written for `hdbcds` in general is not valid +for `hdbtable`. You have to adapt your model prior to the migration. As we don't know what clauses you have used, we cannot offer any further guidance here. ## Associations -Associations cause issues in the .hdbcds to .hdbtable handover. +Associations cause issues in the _.hdbcds_ to _.hdbtable_ handover. For each entity that has associations, the resulting table or view contains a `WITH ASSOCIATIONS` clause, representing native HANA associations. -When deploying via hdbcds, associations in a CAP CDS entity are reflected by corresponding associations in -the `hdbcds` file generated by the compiler. Upon deployment, the hdbcds plugin of HDI generates a `CREATE TABLE` +When deploying via `hdbcds`, associations in a CAP CDS entity are reflected by corresponding associations in +the _.hdbcds_ file generated by the compiler. Upon deployment, the `hdbcds` plugin of HDI generates a `CREATE TABLE` statement, where the associations are represented in a `WITH ASSOCIATIONS` clause. -When deploying via hdbtable, the compiler directly writes the `CREATE TABLE` statements with the `WITH ASSOCIATIONS` -clause into the generated `hdbtable` and `hdbview` files. -These clauses slightly differ, which causes a full table migration when switching from hdbcds to hdbtable. +When deploying via `hdbtable`, the compiler directly writes the `CREATE TABLE` statements with the `WITH ASSOCIATIONS` +clause into the generated _.hdbtable_ and _.hdbview_ files. +These clauses slightly differ, which causes a full table migration when switching from `hdbcds` to `hdbtable`. The CAP Java runtime and the CAP Nodejs runtime with the new SAP HANA service (`@cap-js/hana`, default in @sap/cds@8) don't need the `WITH ASSOCIATIONS` clause anymore. This allows us to avoid the full table migration by removing @@ -115,8 +115,8 @@ sources as well as for the `WITH ASSOCIATIONS` found in the `hdbtable` sources): ::: -Then run a new build and deploy the newly generated `.hdbcds` files. -In contrast to the hdbtable plugin, the hdbcds plugin is able to handle removal of the +Then run a new build and deploy the newly generated _.hdbcds_ files. +In contrast to the `hdbtable` plugin, the `hdbcds` plugin is able to handle removal of the native associations without a full table migration. The resulting database tables and views don't contain any `associations` anymore. @@ -154,20 +154,20 @@ entity Employees { } ``` -When deploying via hdbcds, doc comments in a CAP CDS entity are reflected by corresponding `@Comment` annotations in -the `hdbcds` file generated by the compiler. Upon deployment, the hdbcds plugin of HDI generates a `CREATE TABLE` +When deploying via `hdbcds`, doc comments in a CAP CDS entity are reflected by corresponding `@Comment` annotations in +the _.hdbcds_ file generated by the compiler. Upon deployment, the `hdbcds` plugin of HDI generates a `CREATE TABLE` statement, where the doc comments are represented by `COMMENT` clauses. -When deploying via hdbtable, the compiler directly writes the `CREATE TABLE` statements with the `COMMENT` -clauses into the generated `hdbtable` and `hdbview` files. -These `COMMENT` clauses slightly differ, which causes a full table migration when switching from hdbcds to hdbtable. +When deploying via `hdbtable`, the compiler directly writes the `CREATE TABLE` statements with the `COMMENT` +clauses into the generated _.hdbtable_ and _.hdbview_ files. +These `COMMENT` clauses slightly differ, which causes a full table migration when switching from `hdbcds` to `hdbtable`. If you don't actually need the comments in the database, you can remove them as a preparation step -__before__ you do the hdbcds to hdbtable migration. +__before__ you do the `hdbcds` to `hdbtable` migration. This is similar to the workaround described above for the `WITH ASSOCIATIONS` clause. ::: warn If you need the comments in the database, this workaround will not help, -because switching them back on after moving to hdbtable will then result in a full table migration. +because switching them back on after moving to `hdbtable` will then result in a full table migration. ::: First disable the doc comments by adapting your `.cdsrc.json`: @@ -181,10 +181,10 @@ First disable the doc comments by adapting your `.cdsrc.json`: ``` ::: -Then run a new build and deploy the newly generated `.hdbcds` files. -The `@Comment` annotations have vanished from the `hdbcds` files, thus +Then run a new build and deploy the newly generated _.hdbcds_ files. +The `@Comment` annotations have vanished from the _.hdbcds_ files, thus the resulting database tables and views don't contain the `COMMENT` clause anymore. -In contrast to the hdbtable plugin, the hdbcds plugin is able to handle removal of the +In contrast to the `hdbtable` plugin, the `hdbcds` plugin is able to handle removal of the `COMMENT`s without a full table migration. From 20cdbd9938bc685ecabccf6bec66a31cd40d23ca Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 28 Jun 2024 15:02:15 +0200 Subject: [PATCH 21/28] edits --- cds/compiler-hdbcds-to-hdbtable.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 1c40935f7..9ab6fc34e 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -24,7 +24,7 @@ The resulting database tables and views are the same, independent of the deploy ## Migration Procedure -If your database deployment currently uses `hdbcds`, it's recommended to switch to the default format, `hdbtable`. This guide assumes you use @sap/cds@7 or higher. Make sure to read the entire guide before starting the migration process. +If your database deployment currently uses `hdbcds`, it's recommended to switch to the default format, `hdbtable`. This guide assumes you use cds7 or higher. Make sure to read the entire guide before starting the migration process. 1. Ensure your current data model matches the deployed data model. -2. Switch the deploy format from `hdbcds` to the default `hdbtable`. You can do this by removing option `cds.requires.db.deploy-format` from your configuration file(s). +2. Switch the deployment format from `hdbcds` to the default `hdbtable`. You can do this by removing option `cds.requires.db.deploy-format` from your configuration files. -3. Add an entry to `db/undeploy.json` to undeploy the CAP-generated _.hdbcds_ files: +3. Undeploy the CAP-generated _.hdbcds_ files by adding an entry to `db/undeploy.json`: ::: code-group @@ -54,16 +52,14 @@ If your database deployment currently uses `hdbcds`, it's recommended to switch By following these steps, the HDI's internal handover mechanism automatically transfers ownership of the tables to the `hdbtable` plugin. There are some caveats, however: * If you used annotations `@sql.append` or `sql.prepend`, your model very likely needs to be adapted manually - before the migration can be done. See the corresponding section below for more details. + before the migration can be done. See the corresponding section below for more details. * In some scenarios, the generated _.hdbcds_ and _.hdbtable_ files do not allow a seamless switchover, and a full migration is done for the respective tables. - The scenarios we have identified so far are explained in separate sections below, for two of them there is a workaround. + The scenarios we have identified so far are explained in separate sections below, for two of them there is a work-around. ::: info Full Table Migration -If HDI detects a difference between the CREATE statement in a _.hdbtable_ file and the already deployed -version of a table, it creates a temporary shadow table based on the new structure and copies -existing data into this shadow table. +If HDI detects a difference between the CREATE statement in a _.hdbtable_ file and the version of a table that is deployed already, it creates a temporary shadow table based on the new structure and copies existing data into this shadow table. If the table doesn't contain much data, this process won't significantly impact the system. However, if the table contains a large amount of data, be prepared for a more time-consuming and resource-intensive deployment. @@ -72,36 +68,24 @@ If the table doesn't contain much data, this process won't significantly impact ## Annotations -Annotations [`@sql.append/prepend`](../guides/databases#sql-prepend-append) allow to -add native SQL clauses to the generated _.hdbtable_ files, -or to add native SAP HANA CDS clauses to the generated _.hdbcds_ files, respectively. +Annotations [`@sql.append/prepend`](../guides/databases#sql-prepend-append) are used to generate native SQL clauses to the _.hdbtable_ files, or add native SAP HANA CDS clauses to the _.hdbcds_ files. -If you have used these annotations in your model, a simple switchover from `hdbcds` to `hdbtable` -very likely is not possible, as such an annotation written for `hdbcds` in general is not valid -for `hdbtable`. You have to adapt your model prior to the migration. +If you have used these annotations in your model, a simple switchover from `hdbcds` to `hdbtable` is unlikely as such an annotation written for `hdbcds` in general is not valid for `hdbtable`. You'll have to adapt your model before the migration. -As we don't know what clauses you have used, we cannot offer any further guidance here. +As these clauses are custom, we cannot offer any further guidance here. ## Associations -Associations cause issues in the _.hdbcds_ to _.hdbtable_ handover. -For each entity that has associations, the resulting table or view contains a `WITH ASSOCIATIONS` clause, -representing native SAP HANA associations. +Associations cause issues in the _.hdbcds_ to _.hdbtable_ handover. For each entity that has associations, the resulting table or view contains a `WITH ASSOCIATIONS` clause, representing native SAP HANA associations. -When deploying via `hdbcds`, associations in a CAP CDS entity are reflected by corresponding associations in -the _.hdbcds_ file generated by the compiler. Upon deployment, the `hdbcds` plugin of HDI generates a `CREATE TABLE` -statement, where the associations are represented in a `WITH ASSOCIATIONS` clause. -When deploying via `hdbtable`, the compiler directly writes the `CREATE TABLE` statements with the `WITH ASSOCIATIONS` -clause into the generated _.hdbtable_ and _.hdbview_ files. -These clauses slightly differ, which causes a full table migration when switching from `hdbcds` to `hdbtable`. +When deploying via `hdbcds`, the compiler writes associations in a CAP CDS entity with corresponding associations to the _.hdbcds_ file. Upon deployment, the `hdbcds` plugin of HDI generates a `CREATE TABLE` statement, where the associations are represented in a `WITH ASSOCIATIONS` clause. +When deploying via `hdbtable`, the compiler writes the `CREATE TABLE` statements with the `WITH ASSOCIATIONS` clause directly into the generated _.hdbtable_ and _.hdbview_ files. These clauses slightly differ, which causes a full table migration when switching from `hdbcds` to `hdbtable`. The CAP Java runtime and the CAP Nodejs runtime with the new SAP HANA service (`@cap-js/hana`, default in cds8) -don't need the `WITH ASSOCIATIONS` clause anymore. This allows us to avoid the full table migration by removing -the associations from the `hdbcds` sources __before__ the actual `hdbcds` to `hdbtable` migration. +don't need the `WITH ASSOCIATIONS` clause anymore. This can be used to avoid a full table migration by removing the associations from the `hdbcds` sources __before__ the actual `hdbcds` to `hdbtable` migration. -First switch off the generation of the associations (that option accounts for associations in the `hdbcds` -sources as well as for the `WITH ASSOCIATIONS` found in the `hdbtable` sources): +First switch off the generation of the associations (that option accounts for associations in the `hdbcds` sources as well as the `WITH ASSOCIATIONS` found in the `hdbtable` sources): ::: code-group @@ -116,14 +100,13 @@ sources as well as for the `WITH ASSOCIATIONS` found in the `hdbtable` sources): Then run a new build and deploy the newly generated _.hdbcds_ files. -In contrast to the `hdbtable` plugin, the `hdbcds` plugin is able to handle removal of the -native associations without a full table migration. -The resulting database tables and views don't contain any associations anymore. -::: warning Requirements for this workaround +In contrast to the `hdbtable` plugin, the `hdbcds` plugin is able to handle removal of the native associations without a full table migration. The resulting database tables and views won't contain any associations anymore. + +::: warning Requirements for this work-around * cds8 -* the new SAP HANA database service `@cap-js/hana` -* your custom coding doesn't use the native associations on the database +* The new SAP HANA database service `@cap-js/hana` +* Your custom coding doesn't use the native associations on the database ::: @@ -152,20 +135,13 @@ entity Employees { } ``` -When deploying via `hdbcds`, doc comments in a CAP CDS entity are reflected by corresponding `@Comment` annotations in -the _.hdbcds_ file generated by the compiler. Upon deployment, the `hdbcds` plugin of HDI generates a `CREATE TABLE` -statement, where the doc comments are represented by `COMMENT` clauses. -When deploying via `hdbtable`, the compiler directly writes the `CREATE TABLE` statements with the `COMMENT` -clauses into the generated _.hdbtable_ and _.hdbview_ files. -These `COMMENT` clauses slightly differ, which causes a full table migration when switching from `hdbcds` to `hdbtable`. +When deploying via `hdbcds`, doc comments in a CAP CDS entity are reflected by corresponding `@Comment` annotations in the _.hdbcds_ file generated by the compiler. Upon deployment, the `hdbcds` plugin of HDI generates a `CREATE TABLE` statement, where the doc comments are represented by `COMMENT` clauses. +When deploying via `hdbtable`, the compiler directly writes the `CREATE TABLE` statements with the `COMMENT` clauses into the generated _.hdbtable_ and _.hdbview_ files. These `COMMENT` clauses slightly differ, which causes a full table migration when switching from `hdbcds` to `hdbtable`. -If you don't actually need the comments in the database, you can remove them as a preparation step -__before__ you do the `hdbcds` to `hdbtable` migration. -This is similar to the workaround described above for the `WITH ASSOCIATIONS` clause. +If you don't actually need the comments in the database, you can remove them as a preparation step __before__ you do the `hdbcds` to `hdbtable` migration. This is similar to the work-around described above for the `WITH ASSOCIATIONS` clause. ::: tip Full table migration if you need the comments -If you need the comments in the database, this workaround will not help, -because switching them back on after moving to `hdbtable` will then result in a full table migration. +If you need the comments in the database, this work-around will not help, because switching them back on after moving to `hdbtable` will then result in a full table migration. ::: First disable the doc comments by adapting your `.cdsrc.json`: @@ -179,18 +155,12 @@ First disable the doc comments by adapting your `.cdsrc.json`: ``` ::: -Then run a new build and deploy the newly generated _.hdbcds_ files. -The `@Comment` annotations have vanished from the _.hdbcds_ files, thus -the resulting database tables and views don't contain the `COMMENT` clause anymore. -In contrast to the `hdbtable` plugin, the `hdbcds` plugin is able to handle removal of the -`COMMENT`s without a full table migration. +Then run a new build and deploy the newly generated _.hdbcds_ files. The `@Comment` annotations are removed from the _.hdbcds_ files and the resulting database tables and views won't contain the `COMMENT` clause anymore. Unlike the `hdbtable` plugin, the `hdbcds` plugin handles the removal of the `COMMENT`s without a full table migration. -## Temporal Data with Time Slice IDs +## Temporal Data With Time Slice IDs -Temporal Data with [Time Slice IDs](../guides/temporal-data#adding-time-slice-ids) -is a conceptual feature, thus it shouldn't occur in productive applications. -We nevertheless mention it here for completeness. +Temporal Data with [Time Slice IDs](../guides/temporal-data#adding-time-slice-ids) is a conceptual feature, thus it shouldn't occur in productive applications. Nevertheless, we mention it here for completeness. Example: ```cds From 2126ed4e3fd73959511d50c396d5a112343c76ef Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Mon, 8 Jul 2024 13:30:14 +0200 Subject: [PATCH 23/28] Do the TODOs --- cds/compiler-hdbcds-to-hdbtable.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 0e409c714..fab625dc6 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -25,17 +25,13 @@ The format only determines the "medium" through which your database model is bro If your database deployment currently uses `hdbcds`, it's recommended to switch to the default format, `hdbtable`. This guide assumes you use cds7 or higher. Make sure you read the entire guide before starting the migration process. 1. Ensure that your current data model matches the deployed data model. - 2. Switch the deployment format from `hdbcds` to the default `hdbtable`. You can do this by removing option `cds.requires.db.deploy-format` from your configuration files. 3. Undeploy the CAP-generated _.hdbcds_ files by adding an entry to `db/undeploy.json`: - ::: code-group - ```json [db/undeploy.json] [ ..., @@ -43,13 +39,18 @@ If your database deployment currently uses `hdbcds`, it's recommended to switch ] ``` ::: - - + Without this entry, during HDI deployment you will get errors like "the object cannot be provided more than once". + 4. Build and re-deploy your data model. -By following these steps, the HDI's internal handover mechanism automatically transfers ownership of the tables to the `hdbtable` plugin. There are some caveats, however: +By following these steps, the internal handover mechanism of HDI automatically transfers ownership of the tables to the `hdbtable` plugin. There are some caveats, however: * If you used annotations `@sql.append` or `sql.prepend`, your model very likely needs to be adapted manually before the migration can be done. See the corresponding section below for more details. From e375572fe41b52bdb4922670d5202739fba1fbdd Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 12 Jul 2024 10:08:22 +0200 Subject: [PATCH 24/28] add note on migration guide --- guides/databases-hana.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/guides/databases-hana.md b/guides/databases-hana.md index 09da83b5d..7e3a695d8 100644 --- a/guides/databases-hana.md +++ b/guides/databases-hana.md @@ -454,6 +454,12 @@ During the transition from _.hdbtable_ to _.hdbmigrationtable_ you have to deplo HDI supports the _hdbcds → hdbtable → hdbmigrationtable_ migration flow without data loss. Even going back from _.hdbmigrationtable_ to _.hdbtable_ is possible. Keep in mind that you lose the migration history in this case. For all transitions you want to execute in HDI, you need to specify an undeploy allowlist as described in [HDI Delta Deployment and Undeploy Allow List](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-developer-guide-for-cloud-foundry-multitarget-applications-sap-business-app-studio/hdi-delta-deployment-and-undeploy-allow-list?) in the SAP HANA documentation. +:::tip Moving From _.hdbcds_ To _.hdbtable_ +There a migration guide providing you step-by-step instructions for making the switch. + +[Learn more about Moving From _.hdbcds_ To _.hdbtable_](../cds/compiler-hdbcds-to-hdbtable){.learn-more} +::: + #### Enabling hdbmigrationtable Generation for Selected Entities During CDS Build {#enabling-hdbmigrationtable-generation} If you're migrating your already deployed scenario to _.hdbmigrationtable_ deployment, you've to consider the remarks in [Deploy Artifact Transitions as Supported by HDI](#deploy-artifact-transitions). From 4cf53d9f80e966573f9a1f8a8fcf84ce7be92cf8 Mon Sep 17 00:00:00 2001 From: Steffen Weinstock <79531202+stewsk@users.noreply.github.com> Date: Fri, 12 Jul 2024 10:16:15 +0200 Subject: [PATCH 25/28] Update cds/compiler-hdbcds-to-hdbtable.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: René Jeglinsky --- cds/compiler-hdbcds-to-hdbtable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index fab625dc6..49327795b 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -3,7 +3,7 @@ shorty: Moving from .hdbcds to .hdbtable # layout: cds-ref redirect_from: releases/compiler-v2 -#status: internal +status: released --- # Moving From _.hdbcds_ To _.hdbtable_ From 450027b05419c9cf02618a69755b8072d4579eb6 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 12 Jul 2024 10:18:29 +0200 Subject: [PATCH 26/28] added detail box for error message --- cds/compiler-hdbcds-to-hdbtable.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index fab625dc6..3f71a14b0 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -39,13 +39,16 @@ If your database deployment currently uses `hdbcds`, it's recommended to switch ] ``` ::: - Without this entry, during HDI deployment you will get errors like "the object cannot be provided more than once". - + + :::details Possible error message + Without this entry, during HDI deployment you get errors like the following: + ``` + Error: "db://E": the object cannot be provided more than once [8212002] + "src/E.hdbtable": the file would provide it + "$cds.merge/E": the deployed file already provides it + Merged from "src/E.hdbcds" + ``` + ::: 4. Build and re-deploy your data model. From 7081605c9b6c0d0c827d54bdf4b2db73e3a72e38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Jeglinsky?= Date: Fri, 12 Jul 2024 10:19:37 +0200 Subject: [PATCH 27/28] Update cds/compiler-hdbcds-to-hdbtable.md --- cds/compiler-hdbcds-to-hdbtable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 7c01cff3b..335ccbbf6 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -42,7 +42,7 @@ If your database deployment currently uses `hdbcds`, it's recommended to switch :::details Possible error message Without this entry, during HDI deployment you get errors like the following: - ``` + ```log Error: "db://E": the object cannot be provided more than once [8212002] "src/E.hdbtable": the file would provide it "$cds.merge/E": the deployed file already provides it From b4e775b25fa479cec1919ce51e594f9d6138ca01 Mon Sep 17 00:00:00 2001 From: Rene Jeglinsky Date: Fri, 12 Jul 2024 10:20:39 +0200 Subject: [PATCH 28/28] update to frontmatter --- cds/compiler-hdbcds-to-hdbtable.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/cds/compiler-hdbcds-to-hdbtable.md b/cds/compiler-hdbcds-to-hdbtable.md index 7c01cff3b..acb1b4e0f 100644 --- a/cds/compiler-hdbcds-to-hdbtable.md +++ b/cds/compiler-hdbcds-to-hdbtable.md @@ -1,8 +1,5 @@ --- -shorty: Moving from .hdbcds to .hdbtable - # layout: cds-ref -redirect_from: releases/compiler-v2 status: released ---