From 633912a6d2c51cf4fc9d36ee4c45c26eef6f7edd Mon Sep 17 00:00:00 2001 From: d040506 Date: Mon, 22 Sep 2025 15:03:06 +0200 Subject: [PATCH 1/4] Introduce outbox shared db workaround docs --- java/outbox.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/java/outbox.md b/java/outbox.md index 80b8139a4..64d47a10f 100644 --- a/java/outbox.md +++ b/java/outbox.md @@ -163,6 +163,67 @@ To be sure that the deployment version has been set correctly, you can find a lo And finally, if for some reason you don't want to use a version check for a particular outbox collector, you can switch it off via the outbox configuration [cds.outbox.services.MyCustomOutbox.checkVersion: false](../java/developing-applications/properties#cds-outbox-services--checkVersion). +### Outbox for Shared DB + +By default, CAP Java does not support shared database use cases, as this can lead to unexpected behavior when different isolated services use the same outboxes. +Since CAP automatically creates two outboxes — **DefaultOutboxOrdered** and **DefaultOutboxUnordered** — these would otherwise be shared across all services. + +To avoid this, you can apply a manual workaround by customizing the outbox configuration and isolating them via distinct namespaces for each service. + +#### Deactivate Default Outboxes + +First, deactivate the two default outboxes and create custom outboxes with configurations tailored to your needs. + +```yaml +cds: + outbox: + services: + # deactivate default outboxes + DefaultOutboxUnordered.enabled: false + DefaultOutboxOrdered.enebled: false + # custom outboxes with uniqie names + Service1CustomOutboxOrdered: + maxAttempts: 10 + storeLastError: true + ordered: true + Service1CustomOutboxUnordered: + maxAttempts: 10 + storeLastError: true + ordered: false + +``` + +#### Adapt Audit Log Configuration + +The **DefaultOutboxUnordered** outbox is automatically used for audit logging. Therefore, you must update the audit log configuration to point to the custom one. + +```yaml +cds: + ... + auditlog: + outbox.name: Service1CustomOutboxUnordered +``` + +#### Adapt Messaging Configuration + +Next, adapt the messaging configuration of **every** messaging service in the application so that they use the custom-defined outboxes. + +```yaml +cds: + messaging: + - MessagingService1: + outbox.name: Service1CustomOutboxOrdered + - MessagingService2: + outbox.name: Service1CustomOutboxOrdered + ... +``` + + +::: tip Important Note +It is crucial to **deactivate** the default outboxes, and ensure **unique outbox namespaces** in order to achieve proper isolation between services in a shared DB scenario. +::: + + ## Outboxing CAP Service Events Outbox services support outboxing of arbitrary CAP services. A typical use case is to outbox remote OData From 28657fc8a8a8efd6fba1c17748241c3fb13f06be Mon Sep 17 00:00:00 2001 From: Dietrich Mostowoj <34100436+dimamost@users.noreply.github.com> Date: Tue, 30 Sep 2025 15:22:15 +0200 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: BraunMatthias <59841349+BraunMatthias@users.noreply.github.com> --- java/outbox.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/java/outbox.md b/java/outbox.md index 64d47a10f..3768a4563 100644 --- a/java/outbox.md +++ b/java/outbox.md @@ -165,8 +165,8 @@ And finally, if for some reason you don't want to use a version check for a part ### Outbox for Shared DB -By default, CAP Java does not support shared database use cases, as this can lead to unexpected behavior when different isolated services use the same outboxes. -Since CAP automatically creates two outboxes — **DefaultOutboxOrdered** and **DefaultOutboxUnordered** — these would otherwise be shared across all services. +Currently, CAP Java does not yet support microservices with shared database out of the box, as this can lead to unexpected behavior when different isolated services use the same outboxes. +Since CAP automatically creates two outboxes with a static name — **DefaultOutboxOrdered** and **DefaultOutboxUnordered** — these would be shared across all services which introduces conflicts. To avoid this, you can apply a manual workaround by customizing the outbox configuration and isolating them via distinct namespaces for each service. From 26b97383c4989a4995d424e91d42d10d88e6eda5 Mon Sep 17 00:00:00 2001 From: Dietrich Mostowoj <34100436+dimamost@users.noreply.github.com> Date: Tue, 7 Oct 2025 12:46:02 +0200 Subject: [PATCH 3/4] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: René Jeglinsky --- java/outbox.md | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/java/outbox.md b/java/outbox.md index 3768a4563..bade61d31 100644 --- a/java/outbox.md +++ b/java/outbox.md @@ -168,7 +168,13 @@ And finally, if for some reason you don't want to use a version check for a part Currently, CAP Java does not yet support microservices with shared database out of the box, as this can lead to unexpected behavior when different isolated services use the same outboxes. Since CAP automatically creates two outboxes with a static name — **DefaultOutboxOrdered** and **DefaultOutboxUnordered** — these would be shared across all services which introduces conflicts. -To avoid this, you can apply a manual workaround by customizing the outbox configuration and isolating them via distinct namespaces for each service. +To avoid this, you can apply a manual workaround as follows: + + 1. Customize the outbox configuration and isolating them via distinct namespaces for each service. + 2. Adapt the Audit Log outbox configuration. + 3. Adapt the messaging outbox configuration per service. + + These steps are described in the following sections. #### Deactivate Default Outboxes @@ -180,8 +186,8 @@ cds: services: # deactivate default outboxes DefaultOutboxUnordered.enabled: false - DefaultOutboxOrdered.enebled: false - # custom outboxes with uniqie names + DefaultOutboxOrdered.enabled: false + # custom outboxes with unique names Service1CustomOutboxOrdered: maxAttempts: 10 storeLastError: true @@ -211,11 +217,11 @@ Next, adapt the messaging configuration of **every** messaging service in the ap ```yaml cds: messaging: - - MessagingService1: - outbox.name: Service1CustomOutboxOrdered - - MessagingService2: - outbox.name: Service1CustomOutboxOrdered - ... + services: + MessagingService1: + outbox.name: Service1CustomOutboxOrdered + MessagingService2: + outbox.name: Service1CustomOutboxOrdered ``` From e6711815dd049996eed003c465fee85017ab3a2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Jeglinsky?= Date: Tue, 7 Oct 2025 12:58:36 +0200 Subject: [PATCH 4/4] Update java/outbox.md --- java/outbox.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/java/outbox.md b/java/outbox.md index bade61d31..0bd0d0c2a 100644 --- a/java/outbox.md +++ b/java/outbox.md @@ -163,7 +163,7 @@ To be sure that the deployment version has been set correctly, you can find a lo And finally, if for some reason you don't want to use a version check for a particular outbox collector, you can switch it off via the outbox configuration [cds.outbox.services.MyCustomOutbox.checkVersion: false](../java/developing-applications/properties#cds-outbox-services--checkVersion). -### Outbox for Shared DB +### Outbox for Shared Databases Currently, CAP Java does not yet support microservices with shared database out of the box, as this can lead to unexpected behavior when different isolated services use the same outboxes. Since CAP automatically creates two outboxes with a static name — **DefaultOutboxOrdered** and **DefaultOutboxUnordered** — these would be shared across all services which introduces conflicts.