Providing initial data to your tenants in your multi-tenant application (CAP JAVA)

[NicholasArefta]

🟥 The Problem

We all know that we can use .csv files to populate our tables, but as recommended by capire doc, we should only use .csv files as ‘configuration data’. This is because when it comes to deploying to SAP HANA these .csv files completely overwrite all previous data as per the Danger Label on capire.

capire tipcapire danger label

This poses the question, how do we provide initial data to our tenants while also letting them modifying the data for their use?

📘Instructions

1. Navigate to your tenant upgrade hook, for this example we will run the upgrade task as a Cloud Foundry hook located in the sidecar module of your mta.yaml file.
   https://cap.cloud.sap/docs/guides/multitenancy/?impl-variant=node#update-database-schema

2. Instead of using the default cds-mtx upgrade command, we will use the exclude_filter option to prevent your CSV files from being included in the upgrade. This option will allow us to choose the csv files that we would like to exclude from future upgrades in-order to prevent overwriting data.
   Refer to https://www.npmjs.com/package/@sap/hdi-deploy for more details.

3. Make sure to update your configuration as follows:

   # --- HOOKS ------
   hooks:
   # ----------------
     - name: upgrade-tenants
       type: task
       parameters:
         name: upgrade
         memory: 512M
         disk-quota: 768M
         command: cds-mtx upgrade "*" --body '{"_":{"hdi":{"deploy":{"exclude_filter":["src/gen/data/"] } } } }'

Ensure that you copy the upgrade options accurately!

Once you have deployed the latest version of your application with new initial data, all newly subscribing tenants will receive the updated initial data. Meanwhile, existing tenants using the upgrade hook command will retain their initial data along with any modifications they have made.

What if you have created a brand new table that you want to deliver to existing tenants?

Simple, we shall use the include_filter option to select both the .hdbtabledata and .csv files that you want to add. Be careful not to include any tables or csv files that already exist as you will just overwrite that data.

In the diagram above Tenant 1 is subscribed before the 2nd deploy (this deploy includes changes to schema + data). Tenant 1 will only receive the database schema changes and none of the data, while Tenant 2 will receive the latest changes (schema changes + data).

sequence diagram

The scenario above shows the same sequence of events as described as previously.