37 · HDI Containers & Deployer

Understand HDI container architecture, artifact types, safe vs unsafe schema changes, and the HDI deployer.

Episode 37 — HDI Containers & Deployment

What you'll learn

• HDI container lifecycle and isolation model
• Design-time artifact types generated by CAP
• How cds build produces deployable artifacts
• The HDI deployer package and how it's wired in MTA
• Incremental schema evolution — what HDI allows and what it doesn't

Why this matters

HDI is how CAP gets schema changes into HANA Cloud safely. Understanding the artifact lifecycle explains why some schema changes work silently and others fail with cryptic errors — knowing the rules means zero surprises at deployment time.

HDI container model

BTP CF Space
├── CAP Application (Node.js app)          ← your service code
├── HDI Container service instance         ← schema + data
└── HDI Deployer (one-off task)            ← applies changes to HDI

• The HDI Container is a HANA Cloud schema with its own technical user
• The HDI Deployer is a separate Node.js app (@sap/hdi-deploy) that runs at deploy time
• The CAP app connects to the HDI container via a service binding (injected as VCAP_SERVICES)

Artifact types generated by cds build --for hana

Build output structure

gen/db/
├── package.json            ← HDI deployer entry point
└── src/
    ├── gen/
    │   ├── my.bookshop.Books.hdbcds
    │   ├── my.bookshop.Authors.hdbcds
    │   └── my.bookshop.Orders.hdbcds
    └── data/
        └── my.bookshop-Books.hdbtabledata

HDI deployer package.json

// gen/db/package.json (generated by cds build)
{
  "name": "bookshop-db",
  "version": "1.0.0",
  "dependencies": {
    "@sap/hdi-deploy": "^4"
  },
  "scripts": {
    "start": "node node_modules/@sap/hdi-deploy/deploy.js"
  }
}

What happens during deployment

1. cf push bookshop-db (or mbt build + cf deploy)
2. HDI deployer starts
3. Compares current gen/db/src/ with what's in HDI
4. Determines delta (added, changed, removed artifacts)
5. Applies delta in dependency order
6. Exits 0 on success, non-zero on failure
7. CF task completes; CAP app now uses updated schema

Safe vs unsafe schema changes

Safe (HDI handles automatically)

✓ Add a new entity (table)
✓ Add a nullable column
✓ Add a new view
✓ Change a view definition
✓ Add an index

Unsafe (HDI rejects or data loss risk)

✗ Remove a column          → HDI rejects by default
✗ Rename a column          → treated as drop + add = data loss
✗ Change NOT NULL column   → fails if existing rows have nulls
✗ Change column type       → rejected if incompatible

Workarounds for unsafe changes

-- For a rename: add new column, migrate data, deprecate old
ALTER TABLE BOOKS ADD (NEW_TITLE NVARCHAR(200));
UPDATE BOOKS SET NEW_TITLE = TITLE;
-- Then annotate old column @deprecated in CDS

Forced undeploy (development only!)

# Nuclear option — drops and recreates the HDI container
# ALL DATA IS LOST
cds deploy --to hana --auto-undeploy

Only use on dev containers. Never on production.

HDI roles and permissions

// gen/db/src/roles/app_user.hdbrole
{
  "role": {
    "name": "app_user",
    "schema_privileges": [{ "privileges": ["SELECT","INSERT","UPDATE","DELETE"] }]
  }
}

HDI manages grants automatically for the app's technical user. You don't need to GRANT manually.

Hands-on exercise

1. Run cds build --for hana and inspect gen/db/src/gen/ — find the .hdbcds files
2. Add a new notes: String field to an entity and rebuild — verify the new artifact
3. Try removing a column from CDS, rebuild, and observe the HDI error message
4. Add @deprecated annotation to a field instead of removing it

Checkpoint ✓

• [ ] HDI deployer is a separate package that runs at deploy time (@sap/hdi-deploy)
• [ ] cds build --for hana generates .hdbcds artifacts in gen/db/src/gen/
• [ ] Adding columns is safe; removing/renaming columns requires manual migration
• [ ] --auto-undeploy resets the schema but destroys all data — dev only