UI5 모드
CAP for Node

cds deploy 생략 금지 — 90%가 겪는 HANA Cloud 오류 #shorts #SAP #CAP

수정: 2026년 7월 9일 👁 0 · ♥ 0
▶ YouTube에서 보기

CAP 프로젝트에서 HANA Cloud 연결이 실패하는 진짜 이유

SAP CAP(Cloud Application Programming) 프로젝트를 처음 HANA Cloud에 연결하려는 개발자들이 공통으로 겪는 상황이 있다. cds watch로 로컬에서 잘 돌아가던 서비스가 HANA Cloud를 연결하는 순간 "no database schema found" 또는 "HDI container error" 메시지와 함께 멈춰버리는 것이다. 문제의 원인은 단순하다. CAP은 HANA Cloud에 연결하기 전 반드시 스키마(Schema)를 먼저 배포해야 하며, 이 작업을 수행하는 명령이 바로 cds deploy --to hana다.

이 글은 HANA Cloud 스키마 배포가 왜 필수인지, cds deploy 3단계를 실무에서 어떻게 적용하는지 코드와 오류 메시지를 통해 단계별로 설명한다. SQLite로만 작업해 왔다면 HANA Cloud로의 전환 시 반드시 읽어야 할 내용이다.

HANA Cloud HDI Container와 스키마의 동작 원리

CAP이 로컬에서 SQLite와 통신할 때는 .db 파일에 테이블을 자동으로 생성한다. 하지만 HANA Cloud는 다르다. HANA Cloud는 HDI(HANA Deployment Infrastructure) Container를 통해 데이터베이스 객체를 관리한다. HDI Container는 단순한 스키마가 아니라, 테이블·뷰·계산 뷰 등의 데이터베이스 아티팩트를 버전 관리하는 격리된 컨테이너다.

CAP 엔진은 CDS(Core Data Services) 모델을 읽어 .hdbcds, .hdbtable, .hdbview 같은 HDI 아티팩트 파일을 생성하고, 이를 HDI Container에 배포해 실제 데이터베이스 구조를 만든다. 이 과정 없이 애플리케이션을 실행하면 CAP 런타임은 테이블을 찾을 수 없어 오류를 던진다.

즉, HANA Cloud 연결 전 반드시 수행해야 하는 작업 순서는 다음과 같다:

  1. HANA Cloud 인스턴스 + HDI Container 서비스 인스턴스 생성
  2. cds add hana로 프로젝트에 HANA 지원 추가
  3. cds deploy --to hana로 스키마 배포

사전 준비 — HANA Cloud 인스턴스와 서비스 인스턴스 확인

BTP 서브어카운트에서 HANA Cloud 인스턴스가 실행 중이어야 한다. BTP Cockpit에서 Cloud Foundry → Space → Service Instances로 이동해 hana 서비스 플랜으로 생성된 인스턴스가 있는지 확인한다.

CF CLI를 통해 현재 스페이스의 서비스 인스턴스 목록을 확인하는 방법:

# CF 로그인 및 스페이스 지정
cf login -a https://api.cf.eu10.hana.ondemand.com --sso

# 현재 스페이스의 서비스 인스턴스 목록 확인
cf services

# 출력 예시
name                   service   plan          bound apps   last operation
cap-hana-db            hana      hdi-shared    -            create succeeded

hdi-shared 플랜의 서비스 인스턴스가 create succeeded 상태여야 한다. 아직 없다면 BTP Cockpit에서 생성하거나 CF CLI로 직접 생성한다:

cf create-service hana hdi-shared cap-hana-db

서비스 생성에는 수 분이 소요될 수 있다. cf service cap-hana-db로 상태를 확인한다.

STEP 1 — cds add hana로 프로젝트 구성 변경

cds add hana는 CAP 프로젝트에 HANA 지원을 위한 패키지와 설정을 자동으로 추가한다. 이 명령 하나가 여러 파일을 동시에 변경한다.

cd ~/projects/sales-order-app
cds add hana --for production

--for production 옵션을 사용하면 개발 환경(default profile)은 SQLite를 유지하면서, 프로덕션 환경에서만 HANA를 사용하도록 package.json을 구성한다.

명령 실행 후 package.json에 다음과 같은 변경이 생긴다:

{
  "name": "sales-order-app",
  "dependencies": {
    "@sap/cds": "^7",
    "@sap/hana-client": "^2",
    "hdb": "^0.19"
  },
  "cds": {
    "requires": {
      "db": {
        "kind": "sqlite",
        "[production]": {
          "kind": "hana",
          "deploy-format": "hdbtable"
        }
      }
    }
  }
}

동시에 db/ 디렉터리 아래에 .hdiconfig와 .hdinamespace 파일이 생성된다. 이 파일들은 HDI Container에 어떤 종류의 아티팩트를 배포할지 정의하는 설정 파일이다. 수동으로 수정할 필요는 거의 없다.

STEP 2 — 환경 변수와 서비스 바인딩 설정

cds deploy --to hana를 실행하려면 CAP이 HANA Cloud 인스턴스에 접근할 수 있어야 한다. 로컬 환경에서는 CF의 서비스 바인딩 정보를 직접 가져와야 한다.

가장 권장되는 방식은 cds bind를 이용하는 방법이다:

# CF 스페이스의 HANA 서비스 인스턴스를 로컬 프로젝트에 바인딩
cds bind -2 cap-hana-db

# 바인딩 결과 확인
cat .cdsrc-private.json

cds bind는 .cdsrc-private.json 파일에 서비스 자격 증명을 저장한다. 이 파일은 절대로 git에 커밋하면 안 된다. .gitignore에 반드시 추가해야 한다:

# .gitignore에 추가
echo ".cdsrc-private.json" >> .gitignore
echo "default-env.json" >> .gitignore

.cdsrc-private.json의 구조는 다음과 같다:

{
  "requires": {
    "db": {
      "binding": {
        "type": "cf",
        "apiEndpoint": "https://api.cf.eu10.hana.ondemand.com",
        "org": "my-org",
        "space": "dev",
        "instance": "cap-hana-db",
        "key": "cap-hana-db-key"
      },
      "vcap": {
        "label": "hana",
        "credentials": {
          "host": "xxxxxxxx.hana.prod-eu10.hanacloud.ondemand.com",
          "port": "443",
          "schema": "XXXXXXXXXXXXXXXXXXXXXXXX",
          "hdi_user": "XXXXXXXX_RT",
          "hdi_password": "****"
        }
      }
    }
  }
}

만약 cds bind가 동작하지 않는다면 수동으로 default-env.json을 생성하는 방법도 있다. CF CLI에서 서비스 키를 직접 조회해 붙여넣는다:

# 서비스 키 생성
cf create-service-key cap-hana-db local-dev-key

# 서비스 키 확인
cf service-key cap-hana-db local-dev-key

STEP 3 — cds deploy --to hana 실행과 스키마 생성

이제 실제 배포를 실행한다. cds deploy --to hana는 CDS 모델을 컴파일해 HDI 아티팩트를 생성하고, HANA Cloud HDI Container에 배포해 실제 테이블과 뷰를 만든다.

cds deploy --to hana --vcap-file .cdsrc-private.json

또는 cds bind로 바인딩한 경우 더 간단하게 실행 가능하다:

cds deploy --to hana:cap-hana-db

배포가 시작되면 다음과 같은 로그가 출력된다:

[cds] - connect to db > {
  kind: 'hana',
  vcap: { ... }
}
Deploying to HANA...
  [hdi] - Building...
  [hdi] - Compiling CDS models...
  [hdi] - Generating HDI artifacts...
  [hdi] - Deploying table: my.salesorder.SalesOrders
  [hdi] - Deploying table: my.salesorder.OrderItems
  [hdi] - Deploying view: my.salesorder.SalesOrderView
  [hdi] - Deploy successful
Successfully deployed to HANA in 38.4s

배포가 성공하면 HANA Cloud에 실제 테이블이 생성된 것이다. 이 시점부터 CAP 애플리케이션은 HANA Cloud를 DB로 사용할 수 있다.

자주 만나는 오류 패턴과 해결 방법

실무에서 cds deploy --to hana를 실행할 때 빈번하게 마주치는 오류들과 해결법을 정리했다.

오류 1: "Error: No service instance found"

Error: No service instance found for 'cap-hana-db' in space 'dev'

CF 스페이스에 서비스 인스턴스가 없거나, cf login한 org/space가 다른 경우다. cf services로 올바른 스페이스에 있는지 확인한다.

오류 2: "HDI deployment failed — invalid artifact"

[hdi] ERROR: Invalid artifact type '.hdbcds' — plugin not registered

.hdiconfig 파일에 사용하는 아티팩트 타입이 등록되지 않았을 때 발생한다. cds add hana를 다시 실행하거나 .hdiconfig를 초기화한다.

오류 3: "ETIMEDOUT" 또는 연결 타임아웃

connect ETIMEDOUT 12.34.56.78:443

HANA Cloud 인스턴스의 IP Allow List에 현재 개발 머신의 IP가 등록되지 않은 경우다. BTP Cockpit → HANA Cloud Central에서 Manage Configuration → Allow All IP Addresses를 임시로 활성화하거나, 개발 머신 IP를 직접 등록한다.

오류 4: "Schema already exists" 또는 테이블 충돌

[hdi] ERROR: Cannot drop table SALES_ORDERS — data exists

기존 HDI Container에 데이터가 있는데 스키마를 변경하려 할 때 발생한다. 개발 단계에서는 --auto-undeploy 옵션을 추가하면 기존 객체를 삭제하고 재생성한다. 단, 이 옵션은 데이터를 삭제하므로 프로덕션에서는 절대 사용하면 안 된다.

# 개발 환경 전용 — 데이터 삭제 후 재배포
cds deploy --to hana:cap-hana-db --auto-undeploy

로컬 개발과 CF 배포 환경의 핵심 차이

많은 개발자가 혼란스러워하는 부분이 로컬 개발과 CF 배포 시 cds deploy 동작 방식의 차이다.

로컬 개발 시: cds bind로 CF 서비스에 접근하여 cds deploy --to hana를 명시적으로 실행해야 한다. 이 작업은 스키마 초기화 또는 모델 변경 시에만 한 번 실행하면 된다. 이후 cds watch --profile production으로 로컬 서버를 실행하면 HANA Cloud에 연결된다.

CF/BTP 배포 시: mta.yaml에 hdi-deploy모듈이 포함되어 있으면 cf deploy 또는 mbt build && cf deploy 과정에서 스키마 배포가 자동으로 이루어진다. 즉 수동으로 cds deploy를 실행할 필요가 없다.

# mta.yaml 예시 — hdi-deploy 모듈이 자동으로 스키마를 배포
modules:
  - name: sales-order-app-db-deployer
    type: hdb
    path: gen/db
    requires:
      - name: sales-order-app-hana
    parameters:
      buildpack: nodejs_buildpack

  - name: sales-order-app-srv
    type: nodejs
    path: gen/srv
    requires:
      - name: sales-order-app-hana
    provides:
      - name: srv-api
        properties:
          srv-url: ${default-url}

resources:
  - name: sales-order-app-hana
    type: com.sap.xs.hdi-container
    parameters:
      service: hana
      service-plan: hdi-shared

배포 후 데이터 검증 및 HANA Cloud Explorer 활용

cds deploy --to hana가 성공한 이후 실제로 테이블이 생성됐는지, 데이터가 올바르게 들어가는지 확인하는 방법을 알아야 한다.

가장 직관적인 방법은 SAP HANA Cloud Central에서 Open in SAP HANA Database Explorer를 통해 SQL로 직접 확인하는 것이다.

-- HDI 스키마에 생성된 테이블 목록 확인
SELECT TABLE_NAME, RECORD_COUNT, TABLE_SIZE
FROM M_TABLES
WHERE SCHEMA_NAME = CURRENT_SCHEMA
ORDER BY TABLE_NAME;

-- 실제 데이터 확인
SELECT TOP 10 * FROM "MY_SALESORDER_SALESORDERS";

CAP 서비스 레벨에서 확인하려면 cds watch --profile production으로 로컬 서버를 HANA Cloud에 연결해 실행한 뒤, OData 엔드포인트로 GET 요청을 보내본다:

curl -X GET "http://localhost:4004/odata/v4/sales/SalesOrders" \
  -H "Accept: application/json"

응답에 빈 배열 {"value": []}이 반환되면 테이블이 생성됐고 서비스가 정상 연결된 것이다. 오류 대신 빈 배열이 오는 것 자체가 성공의 증거다.

이 글의 핵심 요약 — cds deploy 3단계 체크리스트

HANA Cloud 연결 실패를 막기 위한 체크리스트를 정리한다:

  1. 서비스 준비: BTP Space에 hdi-shared 플랜 서비스 인스턴스가 create succeeded 상태인지 확인
  2. 프로젝트 설정: cds add hana --for production 실행 → package.json과 db/.hdiconfig 자동 생성 확인
  3. 자격 증명 바인딩: cds bind -2 {서비스명} 실행 → .cdsrc-private.json이 .gitignore에 등록됐는지 확인
  4. 스키마 배포: cds deploy --to hana:{서비스명} 실행 → 로그에 "Deploy successful" 확인
  5. 검증: HANA Database Explorer 또는 OData 엔드포인트로 테이블 존재 확인

CAP 로컬 개발에서 SQLite는 즉시 사용 가능하지만, HANA Cloud는 반드시 이 사전 배포 단계를 거쳐야 한다. 이 절차를 건너뛰면 항상 "no schema" 오류로 돌아온다. 한 번 배포해두면 모델이 변경될 때만 다시 실행하면 되므로, 이 3단계를 프로젝트 초기 설정 루틴으로 습관화하는 것을 권장한다.

댓글 0

아직 댓글이 없습니다.