cds9-migration

CDS 9 Migration — CAP Best Practices

Primary reference: https://cap.cloud.sap/docs/releases/2025/may25
Breaking changes: https://cap.cloud.sap/docs/releases/jan25 (preparation)

Version requirements

// package.json — minimum for CDS 9
{
  "engines": { "node": ">=20" },
  "dependencies": {
    "@sap/cds": "^9",
    "@sap/cds-dk": "^9"
  }
}

⚠️ EOL notice: @sap/cds 7 and below are end of life as of May 2025. CDS CLI commands will error on cds < 8.

Step-by-step migration checklist

Step 1: Upgrade packages

npm install @sap/cds@latest @sap/cds-dk@latest
npm install @sap/xssec@latest  # must be v4+

Step 2: Upgrade to @sap/xssec v4

// Remove compat flag if you had it:
// "cds": { "requires": { "auth": { "xssec_compat": true } } }  ← remove

// package.json — ensure xssec v4
{
  "dependencies": {
    "@sap/xssec": "^4"
  }
}

Step 3: Switch to @cap-js database services

Old package → new package:

@sap/cds-hana     → @cap-js/hana
@sap/cds-sqlite   → @cap-js/sqlite  (or native Node.js SQLite in Node 22.5+)
@sap/cds-pg       → @cap-js/postgres

npm uninstall @sap/cds-hana
npm install @cap-js/hana

// package.json — update kind:
{
  "cds": {
    "requires": {
      "db": {
        "kind": "hana"       // ← was "hana" pointing to @sap/cds-hana, now to @cap-js/hana
      }
    }
  }
}

Step 4: Enable the new CDS parser

// package.json — opt in before upgrading (recommended for gradual migration)
{
  "cds": {
    "cdsc": {
      "newParser": true
    }
  }
}

The new parser is stricter about some syntax. Common issues:

• Annotation expressions must be wrapped in ( ): @restrict: [{ where: (buyer = $user) }]
• Security annotation typos are now errors, not warnings

Step 5: Switch to new protocol adapters

// Remove compat flags:
// "cds": { "odata": { "compat": true } }  ← remove

Step 6: Migrate old MTX to @sap/cds-mtxs

npm uninstall @sap/cds-mtx
npm install @sap/cds-mtxs

Update package.json profile:

{
  "cds": {
    "requires": {
      "multitenancy": true  // @sap/cds-mtxs now auto-activates
    }
  }
}

Step 7: Update deprecated APIs

Deprecated (< CDS 9)	Replacement (CDS 9+)
cds.User.tokenInfo	cds.User.authInfo
cds.security.draftProtection.enabled	cds.security.authorization.draftProtection.enabled
@attachments.disable_facet	@UI.Hidden expression
@protocols: ['odata'] (Java array syntax)	@odata service Foo {}
ctz containerize tool	cds up --to k8s (ctz discontinued)
listOf() / streamOf() (Java)	list() / stream() with typed results
result.single(Books.class) (Java)	result.single() (auto-typed)

Step 8: Update unique constraint handling

CDS 9 no longer assumes which column caused a unique violation:

// Before CDS 9: ENTITY_ALREADY_EXISTS was thrown on INSERT unique violations
// After CDS 9: raw DB error propagated — handle explicitly:
try {
  await INSERT.into(Products).entries(data)
} catch (err) {
  if (err.code === 'SQLITE_CONSTRAINT' || err.originalError?.message?.includes('unique')) {
    req.reject(409, 'PRODUCT_ALREADY_EXISTS', [data.ID])
  }
  throw err
}

Step 9: Update ESLint configuration

npm install @sap/eslint-plugin-cds@latest  # v4 requires ESLint 9 or 10
npm install eslint@10 --save-dev

// eslint.config.js (flat config — ESLint 9+)
import cdslint from '@sap/eslint-plugin-cds'
export default [
  ...cdslint.configs.recommended,
  ...cdslint.configs.js.all,  // includes JS handler checks (new in Aug 2025)
]

The JS checks (new in CAP Aug 2025) detect SQL injection risks:

// ❌ Bad — flagged by ESLint
SELECT`ID`.from`Authors`.where(`name = ${name}`)

// ✅ Good — name is validated by template literal
SELECT`ID`.from`Authors`.where`name = ${name}`

Quick health check after migration

# Check version
cds --version

# Compile project — should have 0 errors
cds compile srv/ --to json > /dev/null

# Run tests
npm test

# Lint
npx eslint srv/ db/

Common migration mistakes to avoid

• ❌ Skipping @sap/xssec v4 upgrade — auth will break in production
• ❌ Not testing with the new parser before upgrading — syntax errors surface
• ❌ Keeping compat flags indefinitely — they're removed in CDS 9
• ❌ Forgetting to update @cap-js/sqlite in package.json devDependencies too (for tests)
• ❌ Not checking for the ENTITY_ALREADY_EXISTS assumption removal in handlers with INSERT

---

Upgrade to cds 10 (released June 2026)

CDS 10 is now available. See the dedicated cds10-migration skill for a complete migration guide.

If you are already on CDS 9, start preparing for cds 10 now:

# Check your project for breaking changes (CDS 10)
cds upgrade

Run the new cds upgrade tool (requires @sap/cds-dk 10.x) for a checklist of what to fix:

npm install -g @sap/cds-dk@latest
cds upgrade

Reference: https://cap.cloud.sap/docs/releases/migration/cds10