Skip to content

detoggle postgres guide #2730

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
renejeglinsky merged 3 commits into from
Jul 9, 2026
Merged

detoggle postgres guide #2730

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
427d830
fix link to java properties
renejeglinsky Jul 8, 2026
6edaaa5
remove toggle and adapt titles and content
renejeglinsky Jul 8, 2026
928fa66
fix links
renejeglinsky Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 17 additions & 51 deletions guides/databases/postgres.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,20 @@
---
impl-variants: true
---

# Using PostgreSQL

<div class="impl node">

This guide focuses on the new PostgreSQL Service provided through *[@cap-js/postgres](https://www.npmjs.com/package/@cap-js/postgres)*, which is based on the same new database services architecture as the new [SQLite Service](./sqlite).

*Learn about migrating from the former `cds-pg` in the [Migration](#migration) chapter.*{.learn-more}

</div>

<div class="impl java">

CAP Java 3 is tested on [PostgreSQL](https://www.postgresql.org/) 16 and most CAP features are supported on PostgreSQL.

[Learn more about features and limitations of using CAP with PostgreSQL](../../java/cqn-services/persistence-services#postgresql){.learn-more}

</div>
*Learn about migrating from the former `cds-pg` in the [Migration](#migration-from-cds-pg-in-node-js) chapter.*{.learn-more}
[Learn more about features and limitations of using CAP Java with PostgreSQL.](../../java/cqn-services/persistence-services#postgresql){.learn-more}

<ImplVariantsHint />

[[toc]]


## Setup & Configuration

<div class="impl node">

Run this to use [PostgreSQL](https://www.postgresql.org/) for production:

</div>

<div class="impl java">

To run CAP Java on PostgreSQL, add a Maven dependency to the PostgreSQL feature in `srv/pom.xml`:

```xml
Expand All @@ -45,21 +25,16 @@ To run CAP Java on PostgreSQL, add a Maven dependency to the PostgreSQL feature
</dependency>
```

In order to use the CDS tooling with PostgreSQL, you also need to install the module `@cap-js/postgres`:

</div>
For CAP Node.js projects, and for CAP Java in order to use the CDS tooling with PostgreSQL, you also need to install the module `@cap-js/postgres`:

```sh
npm add @cap-js/postgres
```

<div class="impl java">

After that, you can use the `cds deploy` command to [deploy](#using-cds-deploy) to a PostgreSQL database or to [create a DDL script](#using-liquibase-java) for PostgreSQL.
After that, you can use the `cds deploy` command to [deploy](#using-cds-deploy) to a PostgreSQL database or to [create a DDL script](#using-liquibase-in-cap-java) for PostgreSQL.

</div>

### Auto-Wired Configuration {.node}
### Auto-Wired Configuration in Node.js

The `@cap-js/postgres` package uses `cds-plugin` technique to auto-configure your application and use a PostgreSQL database for production.

Expand All @@ -84,7 +59,7 @@ Output:
To connect to a PostgreSQL offering from the cloud provider in Production, leverage the [PostgreSQL on SAP BTP, hyperscaler option](https://discovery-center.cloud.sap/serviceCatalog/postgresql-hyperscaler-option). For local development and testing convenience, you can run PostgreSQL in a [docker container](#using-docker).


<div class="impl java">
### CAP Java on SAP BTP

To consume a PostgreSQL instance from a CAP Java application running on SAP BTP, consider the following:

Expand Down Expand Up @@ -112,7 +87,6 @@ modules:
:::

> `BOOKSHOP-PG-DB` is the real PostgreSQL service instance name in this example.
</div>


### Using Docker
Expand Down Expand Up @@ -141,27 +115,17 @@ You can use Docker to run a PostgreSQL database locally as follows:
docker-compose -f pg.yml up -d
```

<div class="impl java">

::: tip
::: tip Testcontainer in CAP Java using Spring Boot
With the introduction of [Testcontainers support](https://spring.io/blog/2023/06/23/improved-testcontainers-support-in-spring-boot-3-1) in Spring Boot 3.1, you can create PostgreSQL containers on the fly for local development or testing purposes.
:::

</div>

## Service Bindings

You need a service binding to connect to the PostgreSQL database.

In the cloud, use given techniques to bind a cloud-based instance of PostgreSQL to your application.

<div class="impl node">

For local development provide the credentials using a suitable [`cds env`](../../node.js/cds-env) technique, like one of the following.

</div>

### Configure Connection Data {.java}
### Configure Connection Data in CAP Java

If a PostgreSQL service binding exists, the corresponding `DataSource` is auto-configured.

Expand All @@ -181,19 +145,19 @@ spring:
:::
To start the application with the new profile `postgres-docker`, the `spring-boot-maven-plugin` can be used: `mvn spring-boot:run -Dspring-boot.run.profiles=postgres-docker`.

[Learn more about the configuration of a PostgreSQL database](../../java/cqn-services/persistence-services#postgresql-1){ .learn-more}
[Learn more about the configuration of a PostgreSQL database.](../../java/cqn-services/persistence-services#postgresql-1){ .learn-more}

### Service Bindings for CDS Tooling {.java}
### Service Bindings for CDS Tooling in CAP Java

#### Using Defaults with `[pg]` Profile {.java}
#### Using Defaults with `[pg]` Profile

`@cds-js/postgres` comes with a set of default credentials under the profile `[pg]` that matches the defaults used in the [docker setup](#using-docker). So, if you stick to these defaults you can skip to deploying your database with:

```sh
cds deploy --profile pg
```

#### In Your Private `.cdsrc-private.json` {.java}
#### In Your Private `.cdsrc-private.json`

If you don't use the default credentials and want to use just `cds deploy`, you need to configure the service bindings (connection data) for the CDS tooling. Add the connection data to your private `.cdsrc-private.json`:

Expand All @@ -214,7 +178,9 @@ If you don't use the default credentials and want to use just `cds deploy`, you
}
```

### Configure Service Bindings {.node}
### Configure Service Bindings in Node.js

For local development provide the credentials using a suitable [`cds env`](../../node.js/cds-env) technique, like one of the following.

#### Using Defaults with `[pg]` Profile

Expand Down Expand Up @@ -515,7 +481,7 @@ to your database!
:::


## Using Liquibase (Java)
## Using Liquibase in CAP Java

In CAP Java projects you can also use [Liquibase](https://www.liquibase.org/) to control when, where, and how database changes are deployed. Liquibase lets you define database changes [in an SQL file](https://docs.liquibase.com/change-types/sql-file.html), use `cds deploy` to quickly generate DDL scripts which can be used by Liquibase.

Expand Down Expand Up @@ -617,7 +583,7 @@ If the changes in the model could lead to data loss, an error is raised.

:::

## Migration { .node }
## Migration from cds-pg in Node.js

Thanks to CAP's database-agnostic cds.ql API, we're confident that the new PostgreSQL service comes without breaking changes.

Expand Down
2 changes: 1 addition & 1 deletion guides/databases/schema-evolution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -198,4 +198,4 @@ For Java-based CAP projects, you can also use [Liquibase](https://www.liquibase.
Please be aware that Liquibase [changed its license to Functional Source License (FSL)](https://www.liquibase.com/blog/liquibase-community-for-the-future-fsl) with release 5.0. You need to check if this license is compatible with your application.
:::

Learn more about that in the [PostgreSQL](postgres.md) guide, section [Using Liquibase (Java)](postgres#using-liquibase-java).
Learn more about that in the [PostgreSQL](postgres.md) guide, section [Using Liquibase (Java)](postgres#using-liquibase-in-cap-java).
2 changes: 1 addition & 1 deletion java/cqn-services/persistence-services.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,7 +184,7 @@ cds add postgres
```

::: warning
Automatic schema deployment isn't suitable for productive use. Consider using production-ready tools like Flyway or Liquibase. See more on that in the [Database guide for PostgreSQL](../../guides/databases/postgres#using-liquibase-java)
Automatic schema deployment isn't suitable for productive use. Consider using production-ready tools like Flyway or Liquibase. See more on that in the [Database guide for PostgreSQL](../../guides/databases/postgres#using-liquibase-in-cap-java)
:::

#### Configure the Connection Data Explicitly { #postgres-connection }
Expand Down
2 changes: 1 addition & 1 deletion java/event-queues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -524,7 +524,7 @@ A startup log entry shows the configured version:
2024-12-19T11:21:33.253+01:00 INFO 3420 --- [main] cds.services.impl.utils.BuildInfo : application.deployment.version: 1.0.0-SNAPSHOT
```

To bypass the version check for a specific custom outbox, set [`cds.outbox.services.MyCustomOutbox.checkVersion: false`](./developing-applications/properties#cds-outbox-services-<key>-checkVersion).
To bypass the version check for a specific custom outbox, set [`cds.outbox.services.MyCustomOutbox.checkVersion: false`](./developing-applications/properties#cds-outbox-services-<key>-checkversion).


## Troubleshooting
Expand Down
Loading