Search

    Project-Specific Configurations

    Learn here about using cds.env to specify and access configuration options for the Node.js runtimes as well as the @sap/cds-dk CLI commands.

    Content

    CLI cds env Command

    Run the cds env command in the root folder of your project to see the effective configuration. The listed settings include global defaults as well as project-specific settings and process environment settings.

    Here’s a brief intro how to use it:

    cds env               #> shortcut to `cds env ls`
    cds env ls            #> lists all settings in properties format
    cds env ls folders    #> lists the `requires.sql` settings 
    cds env get           #> prints all settings in JSON-like format
    cds env get folders   #> prints the `requires.sql` settings 
    cds env get defaults  #> prints defaults only
    cds env ?             #> get help 
    

    For example:

    > cds env ls requires.sql
    requires.sql.credentials.database = :memory:
    requires.sql.impl = @sap/cds/lib/db/sql-service
    requires.sql.kind = sqlite
    
    > cds env get requires.sql
    {
      credentials: { database: ':memory:' },
      impl: '@sap/cds/lib/db/sql-service',
      kind: 'sqlite'
    }
    

    Alternatively, you can also use the cds eval or cds repl CLI commands to access the cds.env property, which provides programmatic access to the effective settings:

    cds -e .env.requires.sql
    {
      credentials: { database: ':memory:' },
      impl: '@sap/cds/lib/db/sql-service',
      kind: 'sqlite'
    }
    
    cds -r
    Welcome to cds repl v4.0.1
    > cds.env.requires.sql
    {
      credentials: { database: ':memory:' },
      impl: '@sap/cds/lib/db/sql-service',
      kind: 'sqlite'
    }
    

    The cds.env Module

    The cds env CLI command and all configuration-related tasks and features in Node.js-based tools and runtimes are backed by the cds.env module, which can be accessed through the central cds facade. For example, you can use it as follows:

    const cds = require('@sap/cds')
    console.log (cds.env.requires.sql)
    

    This would print the same output as the one above for cds env get requires.sql.

    As depicted in the figure below cds.env provides one-stop convenient and transparent access to the effective configuration read from various sources, including global defaults, static, project-specific configuration as well as dynamic settings from process environment and service bindings. Different environments, for example, dev vs prod can be identified and selected by profiles.

    Sources for cds.env

    cds.env is actually a getter property, which on first usage loads and merges settings from these sources, in reverse order of precedence:

    1. @sap/cds built-in defaults
    2. ~/.cdsrc.json → defaults
    3. ./.cdsrc.json → static
    4. ./package.json → static
    5. ./default-env.json → env
    6. ./.env → env in properties format
    7. process.env from shell/launcher
    8. process.env.VCAP_SERVICES → bindings
    9. ~/.cds-services.json → bindings (in development profile only)

    ./ represents a project’s root directory.
    ~/ represents a user’s home directory.

    Settings read from the lower have precedence over settings read from an upper source in the above list. For example, given the following sources:

    ./.cdsrc.json

    {
      "requires": {
        "db": {
          "kind": "sql",
          "model": "./db",
          "credentials": { "database": ":memory:" }
        }
      }
    }
    

    ./package.json

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

    ./.env

    cds.requires.db.credentials.database = my.db
    

    This would result in the following effective configuration:

    cds.env = { ..., 
      requires: {
        db: { 
          kind: "sqlite", 
          model: "./db", 
          credentials: { database:"my.db" }
        }
      }
    }
    

    Programmatic Settings

    Node.js programs can also add and change settings by simply assigning values like so:

    const cds = require('@sap/cds')
    cds.env.requires.sql.kind = 'sqlite'
    cds.env.requires.sql.credentials = { database:'my.db' }
    

    This would change the respective settings in the running program only, without writing back to the sources listed above.

    Global Defaults

    Built-In to @sap/cds

    The lowest level of settings is read from built-in defaults, which comprise settings for these top-level properties:

    Settings Description
    build for build-related settings
    features to switch on/off cds features
    folders locations for app, srv, and db folders
    i18n for i18n-related settings
    odata for OData protocol-related settings
    requires to configure required services

    As these properties are provided in the defaults, apps can safely access them, for example, through cds.env.requires.sql, without always checking for null values on the top-level entries.

    User-Specific Defaults in ~/.cdsrc.json

    You can also create a .cdsrc.json file in your user’s home folder to specify settings to be used commonly across several projects.

    Project Configuration

    Settings, which are essential to your project topology go into static project settings. Examples are the folders layout of your project, specific build tasks, or the list of required services in requires — most frequently your primary database configured under requires.db.

    The settings described here are part of your project’s static content and delivery. They’re checked in to your git repos and used also in productive deployments. Don’t add environment-specific options as static settings but use one of the dynamic process environment options for that.

    In ./package.json

    You can provide static settings in a "cds" section of your project’s package.json as in the following example:

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

    In ./.cdsrc.json

    Alternatively, you can put static settings in .cdsrc.json file in your project root:

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

    .cdsrc goes without an enclosing "cds" section.

    Process Environment

    On the Command Line

    On UNIX-based systems (Mac, Linux) you can specify individual process env variables as prefixes to the command to start your server. For example:

    CDS_REQUIRES_DB_KIND=sql cds run
    

    In ./default-env.json

    You can use this file to store environment variables in JSON format. This is especially handy if you want to mimic the environment of your deployed app: Just copy the result of cf env <your_deployed_app> as JSON into default-env.json.

    Example for default-env.json:

    {
      "VCAP_SERVICES": {
         "hana": [
          {
            "label": "hana",
            "plan": "schema",
            "instance_name": "bookshop-hana",
            "credentials": {
              "host": "my.hana.eu-central-1.dbaas.ondemand.com",
              ...
            },
            ...
          }
        ]
      },
      "VCAP_APPLICATION": {
        "application_id": "1237f5a-e1e4-4d42-8d9c-264d0232e1ec",
        "application_name": "bookshop",
        "name": "my-bookshop"
      }
    }
    

    In ./.env

    Example for .env:

    cds.requires.db.kind = sql
    

    Required Services

    If your app requires external services (databases, message brokers, …), you must add them to the cds.requires section.

    In cds.requires.<service> Settings

    Here, you can configure the services. Find details about the individual options in the documentation of cds.connect.

    Prototype-Chained Along .kind References

    You can use the kind property to reference other services for prototype chaining.

    CDS provides default service configurations for all supported services (hana, enterprise-messaging, …).

    Example:

    {
      "cds": {
        "requires": {
          "serviceA": {
            "kind": "serviceB",
            "myProperty": "my overwritten property"
          },
          "serviceB": {
            "kind": "hana",
            "myProperty": "my property",
            "myOtherProperty": "my other property"
          }
        }
      }
    }
    

    serviceA will have the following properties:

    {
      "kind": "serviceB",
      "myProperty": "my overwritten property",
      "myOtherProperty": "my other property", // from serviceB
      "impl": "[...]/hana/Service.js", // from hana
      "use": "hana" // where impl is defined
    }
    

    Configuration Profiles

    Wrap entries into [<profile-name>]:{ ... } to provide settings for different environments. For example:

    {
      "cds": {
        "requires": {
          "db": {
            "[development]": { "kind": "sqlite" },
            "[production]": { "kind": "hana" }
          }
        }
      }
    }
    

    The profile is determined at bootstrap time as follows:

    1. from NODE_ENV property, if specified
    2. from CDS_ENV, if specified
    3. "development" as default

    You can also introduce own custom profile names and use them as follows:

    CDS_ENV=my-custom-profile cds run
    

    App-Specific Settings

    You can use the same machinery as documented above for app-specific configuration options:

    "cds": { ... },
    "my-app": { ... }
    

    And access them from your app as follows:

    const conf = cds.env('my-app')
    
    Show/Hide Beta Features