36 · SAP HANA Cloud Basics

Provision a HANA Cloud free tier instance, configure cds build --for hana, and connect from local dev.

Episode 36 — SAP HANA Cloud Fundamentals

What you'll learn

HANA Cloud architecture relevant to CAP developers
HDI (HANA Deployment Infrastructure) — what it is and why CAP uses it
Provisioning a HANA Cloud free tier instance
Connecting a CAP app to HANA Cloud locally
Verifying the connection with cds deploy --to hana

Why this matters

HANA Cloud is the production database for CAP apps on BTP. HDI is the deployment model that keeps schema changes safe, repeatable, and auditable — understanding it prevents the common mistakes that cause deployments to fail.

HANA Cloud architecture

┌─────────────────────────────────────────┐
│           SAP HANA Cloud                │
│                                         │
│  ┌─────────────┐    ┌────────────────┐  │
│  │ System DB   │    │  Tenant DB     │  │
│  │ (admin)     │    │  (your app)    │  │
│  └─────────────┘    │                │  │
│                     │  ┌──────────┐  │  │
│                     │  │  HDI     │  │  │
│                     │  │ Container│  │  │
│                     │  └──────────┘  │  │
│                     └────────────────┘  │
└─────────────────────────────────────────┘

Tenant DB: isolated database per BTP subaccount
HDI Container: schema within the tenant DB, fully isolated per application
HDI: the deployment engine that manages CDS-generated artifacts

What is HDI?

HDI (HANA Deployment Infrastructure) manages design-time vs runtime artifacts:

Design-time (your code)	Runtime (HDI deploys)
`.hdbcds` / `.hdbtable` files	Tables in HANA
`.hdbview` files	Views
`.hdbprocedure` files	Stored procedures
`.hdbsequence` files	Sequences

CAP runs cds build --for hana to generate these from your CDS model, then HDI deploys them.

Free tier provisioning

BTP Cockpit → Subaccount → Service Marketplace → SAP HANA Cloud → Create
Choose SAP HANA Cloud, SAP HANA Database (free tier = 30GB, 16vCPU)
Set admin password, allow access from your IP (or BTP CF space)
Wait ~5 minutes for provisioning
Open SAP HANA Database Explorer to verify

Creating a service key

# Create HANA Cloud service instance (if via CF CLI)
cf create-service hana-cloud hana myapp-hana \
  -c '{"data": {"edition": "cloud", "memory": 30, "systempassword": "YourPassword1"}}'

# Create a service key for local development
cf create-service-key myapp-hana myapp-hana-key
cf service-key myapp-hana myapp-hana-key

Local connection via .env

# Copy credentials to local .env (never commit!)
cat > .env << 'EOF'
VCAP_SERVICES={"hana":[{"credentials":{"host":"...","port":"443","user":"...","password":"...","schema":"..."}}]}
EOF

// .cdsrc.json
{
  "requires": {
    "db": {
      "[development]": {
        "kind": "hana",
        "vcap": { "label": "hana" }
      }
    }
  }
}

Deploy schema to HANA

# Build CDS → HANA artifacts
cds build --for hana

# Deploy to HANA Cloud (uses .env credentials)
cds deploy --to hana

# Or use HDI deployer (production)
npm run deploy

cds build --for hana generates:

gen/
└── db/
    ├── src/
    │   ├── gen/
    │   │   ├── Books.hdbcds
    │   │   └── Authors.hdbcds
    └── package.json

Verify connection

# In HANA Database Explorer
SELECT TABLE_NAME FROM TABLES WHERE SCHEMA_NAME = CURRENT_SCHEMA;
-- Should list: BOOKS, AUTHORS, ORDERS, etc.

# Or via cds REPL
cds repl --profile development
> const db = await cds.connect.to('db')
> await db.run(SELECT.from('Books').limit(3))

Common provisioning mistakes

Mistake	Symptom	Fix
IP not in allowlist	Connection timeout	Add your IP in HANA Cloud cockpit
Wrong credentials in .env	Auth failure	Regenerate service key
Schema not created	Table not found	Run `cds deploy --to hana`
CAP version mismatch	Build errors	`npm update @sap/cds`

Hands-on exercise

Provision a free-tier HANA Cloud instance in your BTP trial account
Create a service key and add credentials to .env
Run cds build --for hana and inspect the gen/db/ output
Run cds deploy --to hana and open HANA Database Explorer to verify tables

Checkpoint ✓

[ ] HDI manages design-time artifacts; CAP generates them from CDS
[ ] Service key credentials go in .env as VCAP_SERVICES — never commit this file
[ ] cds build --for hana generates .hdbcds files; cds deploy --to hana applies them
[ ] Free-tier HANA Cloud: 30GB, 16vCPU, no expiry (trial subaccount limit applies)