Search

Connecting to Required Services

cds.connect ⇢ service

Use cds.connect to connect to local or external services; the latter include databases.

cds.connect.to (name?, options?) ⇢ service

Connects to a required service and returns a Promise resolving to a corresponding Service instance. Subsequent invocations with the same service name all return the same instance.

Common Usage:

const srv = await cds.connect.to ('some-service')
const { Books } = srv.entities
srv.run (SELECT.from(Books))

Arguments:

If both, service and options are given, the ad-hoc options are merged with the configured ones (overriding the configured values on same properties). If service is omitted, this is an ad-hoc connection only.

Caching:

Service instances are cached in cds.services, thus subsequent connects with the same service name return the initially connected one. As services constructed by cds.serve are registered with cds.services as well, a connect finds and returns them as local service connections.

Alternative Usages:

Connect to a required service (→ standard for productive code)

cds.connect.to ('db')

Ad-hoc connection (→ only for tests)

cds.connect.to ({ kind:'sqlite', credentials:{database:'my.db'} })

Shortcut for ad-hoc connections

cds.connect.to ('sqlite:my.db')

Configuring Required Services

When connecting to services using cds.connect, the provided service names are used to look up service implementation classes, as well as other details and credentials, from respective configurations in cds.requires sections in your package.json or in .cdsrc.json (omitting the cds. prefix). These configurations are constructed as follows.

↳ cds.requires.<service>.impl

Service implementations are ultimately configured in cds.requires like that:

"cds": { "requires": {
  "some-service": { "impl": "some/node/module/path" },
  "another-service": { "impl": "./local/module/path" }
}}

Given that configuration, a cds.connect.to('some-service') would load the specific service implementation from some/node/module/path. Prefix the module path in impl with ./ to refer to a file relative to your project root.

↳ cds.requires.<service>.kind

As service configurations inherit from each other along kind chains, we can refer to default configurations shipped with @sap/cds, as you commonly see that in our cap/samples, like so:

"cds": { "requires": {
  "db": { "kind": "sqlite" },
  "remote-service": { "kind": "odata" }
}}

This is backed by these default configurations:

"cds": { "requires": {
  "sqlite": { "impl": "@sap/cds-runtime/.../sqlite/service" },
  "odata": { "impl": "@sap/cds-runtime/.../odata/service" },
}}

Run cds env get requires to see all default configurations.
Run cds env get requires.db.impl to see the impl used for your database.

Given that configuration, a cds.connect.to('db') would load the generic service implementation.

Learn more about cds.env

↳ cds.requires.<service>.model

Specify (imported) models for remote services in this property. This allows the service runtime to reflect on the external API and add generic features. The value can be either a single string referring to a CDS model source, resolved as absolute node module, or relative to the project root, or an array of such.

"cds": { "requires": {
  "remote-service": { "kind": "odata", "model":"some/imported/model" }
}}

Upon bootstrapping, all these required models will be loaded and compiled into the effective cds.model as well.

Service Bindings

In addition to the static configuration of requires services documented above, additional information, such as urls, secrets, or passwords are required to actually send requests to remote endpoints. These are dynamically filled into property credentials from process environments as explained below.

↳ cds.requires.<service>.credentials

All service binding information goes into this property. It’s filled in from process environment when starting server processes, managed by deployment environments. For example, they’re filled in via VCAP_SERVICES if Cloud Foundry, or via direct process env assignments in other environments.

For development purposes, you can pass them on the command line or add them to a .env or default-env.json file like so:

# .env file
cds.requires.remote-service.credentials = { "url":"http://...", ... }

❗ Warning

  • Never ever add secrets or passwords to package.json or .cdsrc.json!
  • General rule of thumb: .credentials are always filled (and overridden) from process environment on process start.

One prominent exception of that, which you would frequently add to your package.json is the definition of a database file for persistent sqlite database during development:

  "cds": { "requires": {
    "db": {
      "kind": "sql",
      "[development]": {
        "kind": "sqlite",
        "credentials": {
          "database": "db/bookshop.db"
        }
      }
    }
  }}
✉
Show/Hide Beta Features