Search

Using Databases

This guide is about defining, providing, implementing, deploying and publishing services — so about Service Providers in general.

Content

Providing Initial Data

CSV files in your project are picked up by deployments for both SQLite and SAP HANA. The following conventions apply:

  • The files must be located in folders db/csv, db/data/, or db/src/csv.
  • They contain data for one entity each. File names must follow the pattern <namespace>-entity.csv, for example, my.bookshop-Books.csv.
  • They must start with a header line that lists the needed element names.

SQLite

The fastest way to let your application run is using a local SQLite database via the npm module [sqlite3, which is a devDependency of your project. Using the command line cds deploy --to sqlite helps you deploy the database parts of the project to a local SQLite database. It

  • Creates an SQLite database file in your project.
  • Drops existing tables and views, and re-creates them according the CDS model.
  • Deploys CSV files with initial data.

See it in action

SAP HANA

Enhance Project Configuration for SAP HANA Cloud

On SAP HANA Cloud, CDS models are deployed through the hdbtable and hdbview formats instead of hdbcds. That way, you can still deploy on any SAP HANA but are ready to switch to SAP HANA Cloud at any time.

Add the following in the package.json file:

{
  "cds": {
    "hana" : { "deploy-format": "hdbtable" }
  }
}

As an effect, .hdbtable and .hdbview files are generated in the (gen/)db/src/gen/ folder.

For Java

See here for the rest of the configuration.

For Node.js

Back in package.json, make sure that there’s a db data source of kind sql:

"cds": {
  "requires": {
    "db": {
      "kind": "sql"
    }
  }
}

kind:sql declares the requirement for an SQL database. It evaluates to sqlite in the development profile (active by default), while in production it equals hana. This way you don’t need to modify this file if you want to switch between the two databases. Use the --production parameter in commands like cds build to enforce the production profile.

For the Node.js runtime system to connect to an SAP HANA instance, add the hdb driver for SAP HANA as a dependency to your project:

npm add hdb --save

With @sap/hana-client, there’s a more feature-rich Node.js driver available, which can be installed in the same way. See here for a feature comparison.

Deploying with cds deploy

cds deploy --to hana lets you deploy just the database parts of the project to an SAP HANA instance. The server application (the Node.js or Java part) still runs locally and connects to the remote database instance, allowing for fast development roundtrips.

Make sure that you’re logged in to Cloud Foundry. Then in the project root folder, just execute:

cds deploy --to hana

Behind the scenes, cds deploy --to hana does the following:

  • Compiles the CDS model to SAP HANA files (usually in gen/db, or db/gen)
  • Generates hdbtabledata files for the CSV files in the project. If an hdbtabledata file is already present next to the CSV files, no new file is generated.
  • Creates a Cloud Foundry service of type hdi-shared, which creates an HDI container. Also, you can explicitly specify the name like so: cds deploy --to hana:<myService>
  • Starts @sap/hdi-deploy locally. Should you need a tunnel to access the database, you can specify its address with --tunnel-address <host:port>.
  • Puts default-env.json in the project root. With this information cds watch/run can connect to the HDI container at runtime.

If you run into issues, see the Troubleshooting guide.

How to Continue

See the Deploying to Cloud chapter for how to deploy the complete application to SAP Cloud Platform.