---
versions:
  cdsjs: 6.2.3
  cdsdk: 6.2.3
  cdsc: 3.3.2
  cdsmtxs: 1.2.0
  java: 1.28.1

---
# September 2022

<ReleaseBadges />

[[toc]]

## Streamlined MTX { #cds-mtx}

### New Extensibility Guide {  #new-ext-guide }

Following the streamlined [multitenancy guide](/@external/guides/multitenancy/), there is now a [new guide for extending SaaS apps](/@external/guides/extensibility/customization). It features

- Easier setup of extension projects
- Local development roundtrips with SQLite
- More examples for extending CDS models

<span id="afterextguide" />

## CDS Language & Compiler { #cds}

### Reuse Type `sap.common.Locale`

[The reuse types `@sap/cds/common`](/@external/cds/common) now contain a new type definition for `Locale`:

```cds
type sap.common.Locale : String(14) @title : '{i18n>LanguageCode}';
```

> This type is used for the `locale` field of generated text entities.

### Extending Scalar Types

The `extend` directive has been enhanced to allow for enlarging the `length`
property of strings and the properties `precision` and `scale` of decimals.

Example:

```cds
using { User, Locale } from '@sap/cds/common';
extend Locale with (length:16);
extend User with (length:200);
```

[Learn more about Extend.](/@external/cds/cdl#extend){ .learn-more}

### New Integer Types

We have introduced the built-in types `UInt8` and `Int16`.
They are supported by both, the Node.js and the Java runtime.

| CDS Type | Example Value | SQL         | EDMX        |
| ---      | ---           | ---         | ---         |
| `UInt8`  | `133`         | _TINYINT_   | _Edm.Byte_  |
| `Int16`  | `1337`        | _SMALLINT_  | _Edm.Int16_ |

Example:

```cds
type Rating : UInt8;
type Stock : Int16;
```

[Learn more about Built-in Types.](/@external/cds/types){ .learn-more}

<span id="afterintergertypes" />

## Node.js { #cds-js}

### Important Changes ❗️ { #changes-in-node-js .important }

- All MTX related services have been moved to `@sap/cds-mtxs`. Make sure that you update both modules, `@sap/cds` and `@sap/cds-mtxs`, together.
- The Node.js runtime doesn't interpret the SAP-specific query option `sap-language`. Fiori Elements always sends a _BCP47_ compliant `accept-language` header that is interpreted correctly. If you have used the query option in your tests, please use the header instead.
- If you use the new [1.0.0 version of `axios`](https://github.com/axios/axios/releases/tag/v1.0.0), this might raise errors with missing response headers. In this case, stay with `axios 0.x` for the time being.
- 14.18 is now the minimum required Node.js version. Previously, this was 14.15.  Check your version with `node -v`.

<span id="afterimportant" />

### Default Suffix for SQLite Files is now `.sqlite`

The default file endings of SQLite databases has been changed to `.sqlite` in order to integrate seamlessly with VS Code plugins.
Make sure to adapt your _.gitignore_ file.

<video src="./assets/sep22/sqlite_compressed.mp4" alt="A gif showing VS Code and the execution of the `cds deploy --to sqlite` command and as a result the _db.sqlite_ file." autoplay loop muted webkit-playsinline playsinline />

If you are using `.db` as file ending within your project, it will work as before.

### Messaging via Redis <Beta />

::: warning
This is a beta feature. Beta features aren't part of the officially delivered scope that SAP guarantees for future releases.
:::

There's a new `Messaging Service` based on Redis PubSub, which is suitable for asynchronous communication between tightly-coupled microservices. To configure this messaging service, bind your CAP application to an appropriate platform service, for example of type `redis-cache` and install the latest version of npm package `redis`.

In the `package.json`, you can configure a Redis messaging service explicitly:

```json
{
  "requires": {
    "messaging": {
      "kind": "redis-messaging"
    }
  }
}
```

### Improved `cds.log()`

- Added out-of-the-box support for **winston** loggers. For example, creation and usage of winston loggers is as simple as that now:

  ```js
  cds.log.Logger = cds.log.winstonLogger()
  ```

  [Learn more in the documentation of `cds.log()`.](/@external/node.js/cds-log#winston){ .learn-more}

- Improved loading custom `server.js` files during bootstrapping so that setting custom loggers via `cds.log.Loggers = ...` has immediate effect on all subsequent log output.

- Finally, [documentation for `cds.log()`](/@external/node.js/cds-log) received a major overhaul, including additional, formerly missing information as well as some formerly undocumented features.

![A screenshot of the documentation for the cds.log method showing the table of content.](./assets/sep22/cds-log-docs.png){style="zoom: 66%; box-shadow: 1px 1px 5px #888888"}


### Improved `cds.d.ts` Typings

Together with our community, we have done various improvements in our [TypeScript typings](/@external/node.js/typescript#typescript-apis-in-sapcds):

- Typings for using [tagged template variants of several CQL constructs](/@external/node.js/cds-ql#constructing-queries)
- Typings for calling shortcut versions of CQL constructs (`SELECT(...)` in addition to `SELECT.from(...)`, etc.)
- Typings for [wildcard expansion `*` of properties in CQL](/@external/cds/cql#smart--selector)
- Typings for [cds.log](/@external/node.js/cds-log), [cds.test](/@external/node.js/cds-test), [cds.utils](/@external/node.js/cds-utils), [req.entity](/@external/node.js/events#-target)
- More specific signatures for CQL operations

![Screenshot showing intellisense for cds.log](assets/sep22/ts-cds-log.png){ style="zoom: 33%; box-shadow: 1px 1px 5px #888888;" .adapt}

<div id="beforecdsjava" />

If you observe gaps in any of the typings, we appreciate your help.

## Java { #cds-java}

### Important Changes ❗️ { .important #important-changes-in-java}

#### New Behavior for Upsert

The semantics, behavior and implementation of [Upsert](#upsert) has been redesigned. This might [affect your application](/@external/java/migration#legacy-upsert) if you use the Upsert statement in custom code.

#### Parameters of Actions and Functions

Values for parameters of actions and functions are now validated as described [here](#validation-function).

### Native `UPSERT` {   #upsert}

The semantics, behavior and implementation of [upsert](/@external/java/working-with-cql/query-api#upsert) has been redesigned and aligned with the stakeholders' expectations.
Upsert now leverages UPSERT (UPdate or inSERT) operations on the database where possible.

#### Behavior

- The Upsert statement is primarily intended for efficient data replication scenarios.
- The Upsert statement updates existing data or inserts new data if not yet existing.
- It is now possible to supply partial data ("PATCH semantics").
- The entities that are upserted are identified by the key values given in the data.
- Generic handlers are not executed upon upsert, and no ID generation happens.

#### Usage

The following code performs a [bulk upsert](/@external/java/working-with-cql/query-api#bulk-upsert) that upserts two books in a batch leveraging UPSERT on the DB:

```java
Books b1 = Books.create(101);
b1.setTitle("Odyssey");

Books b2 = Books.create(103);
b2.put("title", "Ulysses");

CqnUpsert upsert = Upsert.into(BOOKS).entries(asList(b1, b2));
```

You can also upsert [deeply structured data](/@external/java/working-with-cql/query-api#deep-upsert). Here, we upsert an order with an associated order item:

```java
Orders order = Orders.create(1000);

OrderItems item = OrderItems.create(1);
item.setBookId(101);
item.setQuantity(2);
order.setItems(asList(item));

CqnUpsert upsert = Upsert.into(ORDERS).entry(order);
```

#### Implications on Custom Code

Up to cds-services 1.27, upsert always completely _replaced_ pre-existing data with the given data: it was implemented as
cascading delete followed by a deep _insert_. Since this release the upsert is implemented as a deep _update_ that creates
data if not existing.

While generic code is not affected by this change application developers that use upsert in custom code need to be aware of
the [implications](/@external/java/migration#legacy-upsert) and might have to adapt their code.

If an application can't immediately adjust to the new upsert behavior when upgrading to this version of cds-services, _it's possible to switch back_ to the old upsert behavior: set the configuration parameter `cds.sql.upsert.strategy` to `replace`.

[Learn more about Upsert.](/@external/java/working-with-cql/query-api#upsert){ .learn-more}

### Input Validation for Actions { #validation-function  }

[Input validation](/@external/guides/services/constraints) is now performed for action and function parameters. The annotations `@mandatory` as well as `@assert.format`, `@assert.range` and `not null` are evaluated to verify the parameter values:

```cds
type Contact {
    @assert.format: '^\p{Lu}.*' name : String(30);
    @assert.range: [1, 10] priority: Integer;
    address: Address not null;
}
action addContact(contact: Contact not null);
function hasContact(@mandatory name: String) returns Boolean;
```

The validation is applied deeply to nested input data. Note that annotated parameters in your model are effectively validated when updating to this version.
To switch off parameter validation temporarily, set `cds.query.validation.parameters.enabled` to `false`.

### Local Support for Streamlined MTX

You can now run and test your application locally with the [Streamlined MTX](/@external/guides/multitenancy/) sidecar (`@sap/cds-mtxs`) and a [file-based SQLite](/@external/java/cqn-services/persistence-services#file-based-storage) database in multitenant mode.
In addition to the common [MTX configuration](/@external/guides/multitenancy/#enable-multitenancy) you need to set the following configuration in your `application.yaml`:

```yaml
cds:
  multi-tenancy:
    mtxs:
      enabled: true
    sidecar:
      url: http://localhost:4004
```

Then start the sidecar locally (default port 4004) as described [in the multitenancy guide](/@external/guides/multitenancy/index#test-drive-locally).
[Mock users with tenants](/@external/java/security#mock-tenants) can be used to run your tests.
[Local Development and Testing](/@external/guides/multitenancy/index#test-drive-locally) explains the steps in detail.

### Improvements for PostgreSQL

You can now use the new SQL [dialect `postgres`](/@external/java/cqn-services/persistence-services#postgresql) of the CDS Compiler to generate DDL, which is specific for PostgreSQL.
Before this release you had to manually adapt the DDL generated for the dialect `plain`.

```sh
cds deploy --to postgres --dry
```

On [PostgreSQL](/@external/java/cqn-services/persistence-services#postgresql-1), localized and temporal data can now be used without restrictions.

### Miscellaneous

- CSV file import now also supports string values that contain escaped characters, delimiter tabs or are quoted with ".

- CloudSDK 4 is now supported. The integration automatically propagates CDS request contexts to CloudSDK's async callables (`ThreadContextExecutorService`).