From 5506165fe392c5c54e7978f9b98d9d32a4b2fe43 Mon Sep 17 00:00:00 2001 From: Eckart Liemke Date: Fri, 10 Jul 2026 13:35:15 +0200 Subject: [PATCH 1/4] more details about t0 tenant --- guides/multitenancy/index.md | 63 +++++++++++++++++++++++++++++++----- 1 file changed, 55 insertions(+), 8 deletions(-) diff --git a/guides/multitenancy/index.md b/guides/multitenancy/index.md index 09600d962..28bd62f3c 100644 --- a/guides/multitenancy/index.md +++ b/guides/multitenancy/index.md @@ -316,7 +316,7 @@ In a first terminal, start the MTX sidecar process: [cds] - serving cds.xt.JobsService { path: '/-/cds/jobs' } ``` - In addition, we can see a `t0` tenant being deployed, which is used by the MTX services for book-keeping tasks. + In addition, we can see a [`t0` tenant](#about-technical-tenant-t0) being deployed, which is used by the MTX services for book-keeping tasks. ```log [cds] - loaded model from 1 file(s): @@ -894,7 +894,7 @@ To help ensure that the generated SAP HANA tenant UUID is unique within a region like `prefix-${org}-${space}` in Cloud Foundry. :::warning Prefix is mandatory -The cds/requires/cds.xt.DeploymentService/hdi/create/hana_tenant_prefix configuration is mandatory to ensure that the internal tenant `t0` is created with its own SAP HANA tenant. +The cds/requires/cds.xt.DeploymentService/hdi/create/hana_tenant_prefix configuration is mandatory to ensure that the internal tenant [`t0`](#about-technical-tenant-t0) is created with its own SAP HANA tenant. ::: :::warning Length restriction @@ -925,7 +925,7 @@ To group the tenant containers of many applications or microservices in a common **Option 2: Pass the SAP HANA Tenant ID with a Subscription** : **... in CAP Node.js** - + If you want to control the ID of the SAP HANA tenant ID on your own, you can pass it as subscription payload as parameters, for example, using a handler for the [`SaasRegistryService`](./mtxs#put-tenant): ```jsonc { @@ -943,12 +943,12 @@ To group the tenant containers of many applications or microservices in a common } ``` The `hana_tenant_id` must be a valid UUID and must be unique per subscriber tenant. Specifying `hana_tenant_id` overrides the prefix settings mentioned earlier, - except for the internal tenant `t0`. Also ensure that the ID is unique within a region. - + except for [the internal tenant `t0`](#about-technical-tenant-t0). Also ensure that the ID is unique within a region. + : **... in CAP Java** To specify the ID of the SAP HANA tenant in **CAP Java** applications you can register a custom handler for the `before` phase of the `SUBSCRIBE` event that sets the `hana_tenant_id` within the provisioning parameters: - + ```java @Before public void beforeSubscription(SubscribeEventContext context) { @@ -956,9 +956,9 @@ To group the tenant containers of many applications or microservices in a common Collections.singletonMap("hana_tenant_id", "")); } ``` - + This will affect every new [tenant subscription](../../java/multitenancy.md#subscribe-tenant) and will set the specified SAP HANA tenant ID. - +
@@ -1276,3 +1276,50 @@ In these MTX sidecar setups, a subproject is added in _./mtx/sidecar_, which ser The main task for the MTX sidecar is to serve `subscribe` and `upgrade` requests. The CAP services runtime requests models from the sidecar only when you apply tenant-specific extensions. For Node.js projects, you have the option to run the MTX services embedded in the main app, instead of in a sidecar. + +## About technical Tenant `t0`` + +`t0` is ta technical tenant used by `@sap/cds-mtxs`. It is a dedicated database container that stores operational metadata. The application's domain model is **not** deployed to `t0`. + +#### What `t0` stores + +| Entity | Purpose | +|--------|---------| +| `cds.xt.Tenants` | Registry of all subscribed tenants with their metadata, schema info, and version | +| `cds.xt.Jobs` | Async job state for operations like subscribe, upgrade, extend | +| `cds.xt.Tasks` | Individual tasks within a job (one per tenant per operation) | + + +#### Lifecycle of `t0` + +The `t0` tenant is automatically created or updated at startup of the MTX Sidecar. + +##### Schema evolution + +Each startup checks if `t0` needs redeployment. If the schema is up-to-date, no action is taken. + +##### Special constraints for `t0` + +- Never uses `hana_tenant_id` from subscription parameters for [SAP HANA TMS v2](#sap-hana-tms-v2) +- Never applies `dataEncryption` +- Never applies the application's `cdsc` compiler options (always uses `assertIntegrity: false`) + + +#### Configuring a different Tenant Name for `t0` + +The default tenant name is `'t0'`. It can be customized via configuration cds/requires/multitenancy/t0 or environment variable `CDS_REQUIRES_MULTITENANCY_T0=my-custom-t0`. + +This is useful for scenarios where the t0 name must vary per deployment (e.g., when multiple apps share the same Service Manager instance and need distinct t0 containers). + +#### Default `database_id` and `lazyT0` + +By default, `t0` is created on server startup without an explicit `database_id`. This means it uses the Service Manager's default (primary) HANA database associated with the service instance or the database that is configured for the cds/requires/cds.xt.DeploymentService/hdi/create/database_id + +[Learn more about DeploymentService configuration.](./mtxs.md#deployment-config){.learn-more} + +##### `lazyT0` configuration + +The creation of the `t0` tenant can be deferred using configuration cds/requires/cds.xt.DeploymentService/lazyT0. + +With that, the `t0` Tenant is only created together with the first subscription. Before the first tenant is subscribed, `t0` is created with the same onboarding parameters (including `database_id`) as the subscribing tenant. This can be useful if the `database_id` is not known when deploying the MTX Sidecar. + From 2e3b72dab77fc4818d7eb2fd0dd0e61e34ac1618 Mon Sep 17 00:00:00 2001 From: Eckart Liemke Date: Thu, 16 Jul 2026 17:22:57 +0200 Subject: [PATCH 2/4] move t0 to reference --- guides/multitenancy/index.md | 51 ++---------------------------------- guides/multitenancy/mtxs.md | 47 +++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 49 deletions(-) diff --git a/guides/multitenancy/index.md b/guides/multitenancy/index.md index 62d1bb074..0bf16d0e7 100644 --- a/guides/multitenancy/index.md +++ b/guides/multitenancy/index.md @@ -894,7 +894,7 @@ To help ensure that the generated SAP HANA tenant UUID is unique within a region like `prefix-${org}-${space}` in Cloud Foundry. :::warning Prefix is mandatory -The cds/requires/cds.xt.DeploymentService/hdi/create/hana_tenant_prefix configuration is mandatory to ensure that the internal tenant [`t0`](#about-technical-tenant-t0) is created with its own SAP HANA tenant. +The cds/requires/cds.xt.DeploymentService/hdi/create/hana_tenant_prefix configuration is mandatory to ensure that the internal tenant [`t0`](./mtxs#about-technical-tenant-t0) is created with its own SAP HANA tenant. ::: :::warning Length restriction @@ -953,7 +953,7 @@ To group the tenant containers of many applications or microservices in a common } ``` The `hana_tenant_id` must be a valid UUID and must be unique per subscriber tenant. Specifying `hana_tenant_id` overrides the prefix settings mentioned earlier, - except for [the internal tenant `t0`](#about-technical-tenant-t0). Also ensure that the ID is unique within a region. + except for [the internal tenant t0](./mtxs#about-technical-tenant-t0). Also ensure that the ID is unique within a region. : **... in CAP Java** @@ -1286,50 +1286,3 @@ In these MTX sidecar setups, a subproject is added in _./mtx/sidecar_, which ser The main task for the MTX sidecar is to serve `subscribe` and `upgrade` requests. The CAP services runtime requests models from the sidecar only when you apply tenant-specific extensions. For Node.js projects, you have the option to run the MTX services embedded in the main app, instead of in a sidecar. - -## About technical Tenant `t0`` - -`t0` is ta technical tenant used by `@sap/cds-mtxs`. It is a dedicated database container that stores operational metadata. The application's domain model is **not** deployed to `t0`. - -#### What `t0` stores - -| Entity | Purpose | -|--------|---------| -| `cds.xt.Tenants` | Registry of all subscribed tenants with their metadata, schema info, and version | -| `cds.xt.Jobs` | Async job state for operations like subscribe, upgrade, extend | -| `cds.xt.Tasks` | Individual tasks within a job (one per tenant per operation) | - - -#### Lifecycle of `t0` - -The `t0` tenant is automatically created or updated at startup of the MTX Sidecar. - -##### Schema evolution - -Each startup checks if `t0` needs redeployment. If the schema is up-to-date, no action is taken. - -##### Special constraints for `t0` - -- Never uses `hana_tenant_id` from subscription parameters for [SAP HANA TMS v2](#sap-hana-tms-v2) -- Never applies `dataEncryption` -- Never applies the application's `cdsc` compiler options (always uses `assertIntegrity: false`) - - -#### Configuring a different Tenant Name for `t0` - -The default tenant name is `'t0'`. It can be customized via configuration cds/requires/multitenancy/t0 or environment variable `CDS_REQUIRES_MULTITENANCY_T0=my-custom-t0`. - -This is useful for scenarios where the t0 name must vary per deployment (e.g., when multiple apps share the same Service Manager instance and need distinct t0 containers). - -#### Default `database_id` and `lazyT0` - -By default, `t0` is created on server startup without an explicit `database_id`. This means it uses the Service Manager's default (primary) HANA database associated with the service instance or the database that is configured for the cds/requires/cds.xt.DeploymentService/hdi/create/database_id - -[Learn more about DeploymentService configuration.](./mtxs.md#deployment-config){.learn-more} - -##### `lazyT0` configuration - -The creation of the `t0` tenant can be deferred using configuration cds/requires/cds.xt.DeploymentService/lazyT0. - -With that, the `t0` Tenant is only created together with the first subscription. Before the first tenant is subscribed, `t0` is created with the same onboarding parameters (including `database_id`) as the subscribing tenant. This can be useful if the `database_id` is not known when deploying the MTX Sidecar. - diff --git a/guides/multitenancy/mtxs.md b/guides/multitenancy/mtxs.md index f7c9ce043..eb962c349 100644 --- a/guides/multitenancy/mtxs.md +++ b/guides/multitenancy/mtxs.md @@ -1597,6 +1597,53 @@ The job and task status can take on the values `QUEUED`, `RUNNING`, `FINISHED` a +## About technical Tenant `t0` + +`t0` is ta technical tenant used by `@sap/cds-mtxs`. It is a dedicated database container that stores operational metadata. The application's domain model is **not** deployed to `t0`. + +#### What `t0` stores + +| Entity | Purpose | +|--------|---------| +| `cds.xt.Tenants` | Registry of all subscribed tenants with their metadata, schema info, and version | +| `cds.xt.Jobs` | Async job state for operations like subscribe, upgrade, extend | +| `cds.xt.Tasks` | Individual tasks within a job (one per tenant per operation) | + + +#### Lifecycle of `t0` + +The `t0` tenant is automatically created or updated at startup of the MTX Sidecar. + +##### Schema evolution + +Each startup checks if `t0` needs redeployment. If the schema is up-to-date, no action is taken. + +##### Special constraints for `t0` + +- Never uses `hana_tenant_id` from subscription parameters for [SAP HANA TMS v2](#sap-hana-tms-v2) +- Never applies `dataEncryption` +- Never applies the application's `cdsc` compiler options + + +#### Configuring a different Tenant Name for `t0` + +The default tenant name is `'t0'`. It can be customized via configuration cds/requires/multitenancy/t0 or environment variable `CDS_REQUIRES_MULTITENANCY_T0=my-custom-t0`. + +This is useful for scenarios where the t0 name must vary per deployment (e.g., when multiple apps share the same Service Manager instance and need distinct t0 containers). + +#### Default `database_id` and `lazyT0` + +By default, `t0` is created on server startup without an explicit `database_id`. This means it uses the Service Manager's default (primary) HANA database associated with the service instance or the database that is configured for the cds/requires/cds.xt.DeploymentService/hdi/create/database_id + +[Learn more about DeploymentService configuration.](./mtxs.md#deployment-config){.learn-more} + +##### `lazyT0` configuration + +The creation of the `t0` tenant can be deferred using configuration cds/requires/cds.xt.DeploymentService/lazyT0. + +With that, the `t0` Tenant is only created together with the first subscription. Before the first tenant is subscribed, `t0` is created with the same onboarding parameters (including `database_id`) as the subscribing tenant. This can be useful if the `database_id` is not known when deploying the MTX Sidecar. + + ## [Old MTX Reference](old-mtx-apis) {.toc-redirect} [See Reference docs for former 'old' MTX Services.](old-mtx-apis){.learn-more} From 89bbd1728259e5c0ace7993a0b52ba5143667b31 Mon Sep 17 00:00:00 2001 From: Eckart Liemke Date: Thu, 16 Jul 2026 17:33:34 +0200 Subject: [PATCH 3/4] fix links --- guides/multitenancy/index.md | 2 +- guides/multitenancy/mtxs.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/multitenancy/index.md b/guides/multitenancy/index.md index 0bf16d0e7..d386e72e5 100644 --- a/guides/multitenancy/index.md +++ b/guides/multitenancy/index.md @@ -316,7 +316,7 @@ In a first terminal, start the MTX sidecar process: [cds] - serving cds.xt.JobsService { path: '/-/cds/jobs' } ``` - In addition, we can see a [`t0` tenant](#about-technical-tenant-t0) being deployed, which is used by the MTX services for book-keeping tasks. + In addition, we can see a [`t0` tenant]./mtxs#about-technical-tenant-t0) being deployed, which is used by the MTX services for book-keeping tasks. ```log [cds] - loaded model from 1 file(s): diff --git a/guides/multitenancy/mtxs.md b/guides/multitenancy/mtxs.md index eb962c349..cd964d824 100644 --- a/guides/multitenancy/mtxs.md +++ b/guides/multitenancy/mtxs.md @@ -1620,7 +1620,7 @@ Each startup checks if `t0` needs redeployment. If the schema is up-to-date, no ##### Special constraints for `t0` -- Never uses `hana_tenant_id` from subscription parameters for [SAP HANA TMS v2](#sap-hana-tms-v2) +- Never uses `hana_tenant_id` from subscription parameters for [SAP HANA TMS v2](./index#sap-hana-tms-v2) - Never applies `dataEncryption` - Never applies the application's `cdsc` compiler options From 6a07072bb037460be2893672a6f5f729d7404125 Mon Sep 17 00:00:00 2001 From: ecklie <52252271+ecklie@users.noreply.github.com> Date: Fri, 17 Jul 2026 16:54:43 +0200 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Steffen Waldmann --- guides/multitenancy/mtxs.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/guides/multitenancy/mtxs.md b/guides/multitenancy/mtxs.md index cd964d824..61dff7e99 100644 --- a/guides/multitenancy/mtxs.md +++ b/guides/multitenancy/mtxs.md @@ -1599,20 +1599,20 @@ The job and task status can take on the values `QUEUED`, `RUNNING`, `FINISHED` a ## About technical Tenant `t0` -`t0` is ta technical tenant used by `@sap/cds-mtxs`. It is a dedicated database container that stores operational metadata. The application's domain model is **not** deployed to `t0`. +`t0` is a technical tenant used by `@sap/cds-mtxs`. It is a dedicated database container that stores operational metadata. The application's domain model is **not** deployed to `t0`. #### What `t0` stores | Entity | Purpose | |--------|---------| | `cds.xt.Tenants` | Registry of all subscribed tenants with their metadata, schema info, and version | -| `cds.xt.Jobs` | Async job state for operations like subscribe, upgrade, extend | +| `cds.xt.Jobs` | Async job state for operations like `subscribe`, `upgrade`, `extend` | | `cds.xt.Tasks` | Individual tasks within a job (one per tenant per operation) | #### Lifecycle of `t0` -The `t0` tenant is automatically created or updated at startup of the MTX Sidecar. +The `t0` tenant is automatically created or updated at startup of the MTX sidecar. ##### Schema evolution @@ -1629,7 +1629,7 @@ Each startup checks if `t0` needs redeployment. If the schema is up-to-date, no The default tenant name is `'t0'`. It can be customized via configuration cds/requires/multitenancy/t0 or environment variable `CDS_REQUIRES_MULTITENANCY_T0=my-custom-t0`. -This is useful for scenarios where the t0 name must vary per deployment (e.g., when multiple apps share the same Service Manager instance and need distinct t0 containers). +This is useful for scenarios where the `'t0'` name must vary per deployment (e.g., when multiple apps share the same Service Manager instance and need distinct `t0` containers). #### Default `database_id` and `lazyT0` @@ -1641,7 +1641,7 @@ By default, `t0` is created on server startup without an explicit `database_id`. The creation of the `t0` tenant can be deferred using configuration cds/requires/cds.xt.DeploymentService/lazyT0. -With that, the `t0` Tenant is only created together with the first subscription. Before the first tenant is subscribed, `t0` is created with the same onboarding parameters (including `database_id`) as the subscribing tenant. This can be useful if the `database_id` is not known when deploying the MTX Sidecar. +With that, the `t0` tenant is only created together with the first subscription. Before the first tenant is subscribed, `t0` is created with the same onboarding parameters (including `database_id`) as the subscribing tenant. This can be useful if the `database_id` is not known when deploying the MTX sidecar. ## [Old MTX Reference](old-mtx-apis) {.toc-redirect}