Skip to content

Commit c638b72

Browse files
davidfrigoletdieppa
davidfrigolet
and
dieppa
authored
Community edition Dynamodb (#23)
Co-authored-by: Antonio Perez Dieppa <aperezdieppa@gmail.com>
1 parent f163b6c commit c638b72

4 files changed

Lines changed: 225 additions & 22 deletions

File tree

docs/community-edition/Overview.md renamed to docs/community-edition/Introduction.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Overview
2+
title: Introduction
33
sidebar_position: 1
44
---
55

‎docs/community-edition/ce-dynamodb.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
---
2+
title: DynamoDB
3+
sidebar_position: 4
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
## Introduction
10+
11+
This section explains how to configure and use the **Flamingock Community Edition for DynamoDB** in applications that interact with Amazon DynamoDB using the **official AWS SDK for Java**.
12+
13+
This edition is designed for use cases where the application provides its own DynamoDB client via `DynamoDbClient`, and Flamingock operates directly over that connection to manage changes. It does not require any framework-level integration.
14+
15+
Flamingock persists a minimal set of metadata in your DynamoDB tables to support its execution model:
16+
17+
- **Audit records** – to track which changes have been applied
18+
- **Distributed locks** – to coordinate executions across multiple instances
19+
20+
---
21+
22+
## Edition
23+
24+
This is a single edition for DynamoDB, provided as a standalone artifact.
25+
26+
| Edition Name | Java Client | DynamoDB Compatibility |
27+
|--------------------------|-----------------------------------|:------------------------:|
28+
| `flamingock-ce-dynamodb` | `software.amazon.awssdk:dynamodb` | `2.x` |
29+
30+
---
31+
32+
## Get started
33+
34+
To get started with the Flamingock Community Edition for DynamoDB, follow these steps:
35+
36+
---
37+
38+
### 1. Add the required dependencies
39+
40+
You must include both the **Flamingock DynamoDB edition** and the **AWS SDK v2 for DynamoDB** in your project.
41+
42+
<Tabs groupId="build_tool">
43+
44+
<TabItem value="gradle" label="Gradle">
45+
46+
```kotlin
47+
implementation("io.flamingock:flamingock-ce-dynamodb:$flamingockVersion")
48+
implementation("software.amazon.awssdk:dynamodb-enhanced:2.x.x")
49+
implementation("software.amazon.awssdk:url-connection-client:2.x.x")
50+
```
51+
52+
</TabItem> <TabItem value="maven" label="Maven">
53+
54+
```xml
55+
<dependency>
56+
<groupId>io.flamingock</groupId>
57+
<artifactId>flamingock-ce-dynamodb</artifactId>
58+
<version>${flamingock.version}</version>
59+
</dependency>
60+
<dependency>
61+
<groupId>software.amazon.awssdk</groupId>
62+
<artifactId>dynamodb-enhanced</artifactId>
63+
<version>2.x.x</version>
64+
</dependency>
65+
<dependency>
66+
<groupId>software.amazon.awssdk</groupId>
67+
<artifactId>url-connection-client</artifactId>
68+
<version>2.x.x</version>
69+
</dependency>
70+
```
71+
72+
</TabItem> </Tabs>
73+
74+
---
75+
76+
### 2. Enable Flamingock runner
77+
78+
At minimum, you must provide a `DynamoDbClient` instance (as a **dependency**)
79+
```java
80+
DynamoDbClient dynamoClient = DynamoDbClient.builder()
81+
.region(Region.US_EAST_1)
82+
.build();
83+
84+
Runner runner = Flamingock.builder()
85+
.addDependency(dynamoClient)
86+
.build();
87+
88+
```
89+
90+
### 3. Execute Flamingock
91+
Once the Flamingock runner is configured and built, you can trigger Flamingock’s execution:
92+
93+
```java
94+
runner.execute();
95+
```
96+
97+
98+
---
99+
## Configuration overview
100+
101+
Flamingock’s DynamoDB Community Edition requires both:
102+
- A `DynamoDbClient` dependency
103+
- A set of configuration properties
104+
105+
### Dependencies
106+
107+
These must be registered using `.addDependency(...)`
108+
109+
| Type | Required | Description |
110+
|-----------------------------------------------------------|:--------:|------------------------------------------------|
111+
| `software.amazon.awssdk.services.dynamodb.DynamoDbClient` | Yes | Required to access and modify DynamoDB tables. |
112+
113+
### Properties
114+
115+
These must be set using `.setProperty(...)`
116+
117+
| Property | Type | Required | Default Value | Description |
118+
|-----------------------|-----------|:--------:|-----------------------|------------------------------------------------------------------------------|
119+
| `readCapacityUnits` | `Long` | No | `5L` | Read capacity units (for **PROVISIONED** billing mode only). |
120+
| `writeCapacityUnits` | `Long` | No | `5L` | Write capacity units (for **PROVISIONED** billing mode only). |
121+
| `autoCreate` | `Boolean` | No | `true` | Automatically creates the required tables if they do not exist. |
122+
| `auditRepositoryName` | `String` | No | `flamingockAuditLogs` | Table used to store audit records. Most users should keep the default name. |
123+
| `lockRepositoryName` | `String` | No | `flamingockLock` | Table used for distributed locking. Most users should keep the default name. |
124+
125+
:::warning
126+
In production environments, we strongly recommend keeping the default configuration values unless you fully understand the implications.
127+
These defaults ensure consistency, safety, and compatibility with Flamingock’s locking and audit mechanisms.
128+
:::
129+
130+
131+
132+
133+
---
134+
135+
136+
## Full configuration example
137+
The following example shows how to configure Flamingock with both required and optional properties.
138+
It demonstrates how to override index creation, and read/write behaviour.
139+
This level of configuration is useful when you need to customise Flamingock's behaviour to match the consistency and
140+
durability requirements of your deployment.
141+
```java
142+
DynamoDbClient dynamoClient = DynamoDbClient.builder()
143+
.region(Region.US_EAST_1)
144+
.build();
145+
146+
FlamingockBuilder builder = Flamingock.builder()
147+
.addDependency(dynamoClient)
148+
.setProperty("autoCreate", true)
149+
.setProperty("readCapacityUnits", 5L)
150+
.setProperty("writeCapacityUnits", 5L);
151+
152+
```
153+
154+
155+
---
156+
157+
## Transaction support
158+
159+
160+
Flamingock supports transactional execution on DynamoDB using the enhanced client’s `TransactWriteItemsEnhancedRequest.Builder`.
161+
162+
If a change unit is marked as transactional (which is the default), Flamingock will:
163+
164+
- Create a **fresh transactional builder** (`TransactWriteItemsEnhancedRequest.Builder`) for that change
165+
- Inject it into the `@Execution` method
166+
- Execute the transaction **only if the change completes successfully** — including Flamingock’s internal audit write as part of the same transaction
167+
168+
This ensures **atomicity**: either all operations defined in the change unit — including the audit log — are applied together, or none are.
169+
170+
### Example
171+
```java
172+
@Execution
173+
public void execute(@NonLockGuarded DynamoDbClient client,
174+
TransactWriteItemsEnhancedRequest.Builder builder) {
175+
176+
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
177+
.dynamoDbClient(client)
178+
.build();
179+
180+
DynamoDbTable<UserEntity> table = enhancedClient.table("users", TableSchema.fromBean(UserEntity.class));
181+
182+
builder.addPutItem(table, new UserEntity("Alice", "Anderson"));
183+
builder.addPutItem(table, new UserEntity("Bob", "Bennett"));
184+
}
185+
186+
```
187+
188+
:::tip
189+
You can add as many operations as needed to the builder: `putItem`, `updateItem`, `deleteItem`, etc.
190+
These operations will be executed **in a single atomic transaction**, together with Flamingock’s internal audit log update.
191+
:::
192+
193+
:::warning
194+
If you mark a change unit as transactional but do **not** add any operations to the builder, Flamingock will still execute the transaction — but it will contain **only the audit log entry**.
195+
196+
Make sure your change unit populates the `TransactWriteItemsEnhancedRequest.Builder` appropriately.
197+
:::
198+
199+
> See the [Transactions](../transactions.md) page for general guidance and best practices around transactional vs non-transactional change units.
200+
201+
202+
203+
---

‎docs/community-edition/ce-mongodb-java-driver.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -119,17 +119,17 @@ These must be registered using `.addDependency(...)`
119119

120120
These must be set using `.setProperty(...)`
121121

122-
| Property | Type | Default Value | Required | Description |
123-
|---------------------------------|-----------------------|-------------------------------|:--------:|-----------------------------------------------------------------------------------------------------------------------|
124-
| `mongodb.databaseName` | `String` | n/a | Yes | Name of the MongoDB database. This is required to store audit logs and acquire distributed locks. |
125-
| `mongodb.autoCreate` | `boolean` | `true` | No | Whether Flamingock should automatically create required collections and indexes. |
126-
| `mongodb.readConcern` | `String` | `"MAJORITY"` | No | Controls the isolation level for read operations. |
127-
| `mongodb.writeConcern.w` | `String or int` | `"MAJORITY"` | No | Write acknowledgment level. Specifies how many MongoDB nodes must confirm the write for it to succeed. |
128-
| `mongodb.writeConcern.journal` | `boolean` | `true` | No | Whether the write must be committed to the journal before acknowledgment. |
129-
| `mongodb.writeConcern.wTimeout` | `Duration` | `Duration.ofSeconds(1)` | No | Maximum time to wait for the write concern to be fulfilled. |
130-
| `mongodb.readPreference` | `ReadPreferenceLevel` | `ReadPreferenceLevel.PRIMARY` | No | Defines which MongoDB node to read from. |
131-
| `mongodb.auditRepositoryName` | `String` | `"flamingockAuditLogs"` | No | Name of the collection for storing the audit log. Overrides the default. Most users should keep the default value. |
132-
| `mongodb.lockRepositoryName` | `String` | `"flamingockLock"` | No | Name of the collection used for distributed locking. Overrides the default. Most users should keep the default value. |
122+
| Property | Type | Default Value | Required | Description |
123+
|----------------------------------|------------------------|--------------------------------|:--------:|-----------------------------------------------------------------------------------------------------------------------|
124+
| `mongodb. databaseName` | `String` | n/a | Yes | Name of the MongoDB database. This is required to store audit logs and acquire distributed locks. |
125+
| `mongodb.autoCreate` | `boolean` | `true` | No | Whether Flamingock should automatically create required collections and indexes. |
126+
| `mongodb.readConcern` | `String` | `"MAJORITY"` | No | Controls the isolation level for read operations. |
127+
| `mongodb. writeConcern.w` | `String or int` | `"MAJORITY"` | No | Write acknowledgment level. Specifies how many MongoDB nodes must confirm the write for it to succeed. |
128+
| `mongodb. writeConcern.journal` | `boolean` | `true` | No | Whether the write must be committed to the journal before acknowledgment. |
129+
| `mongodb. writeConcern.wTimeout` | `Duration` | `Duration .ofSeconds(1)` | No | Maximum time to wait for the write concern to be fulfilled. |
130+
| `mongodb. readPreference` | `ReadPreference Level` | `ReadPreferenceLevel .PRIMARY` | No | Defines which MongoDB node to read from. |
131+
| `mongodb. auditRepositoryName` | `String` | `"flamingockAuditLogs"` | No | Name of the collection for storing the audit log. Overrides the default. Most users should keep the default value. |
132+
| `mongodb. lockRepositoryName` | `String` | `"flamingockLock"` | No | Name of the collection used for distributed locking. Overrides the default. Most users should keep the default value. |
133133

134134
:::warning
135135
It's **strongly recommended keeping the default MongoDB configuration values provided by Flamingock** — especially in production environments. These defaults are carefully chosen to guarantee **maximum consistency, durability, and safety**, which are fundamental to Flamingock’s audit and rollback guarantees.

‎docs/community-edition/ce-mongodb-springdata.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -145,16 +145,16 @@ In most cases, **Spring Boot will automatically configure `MongoTemplate`** base
145145

146146
These can be set using `.setProperty(...)` with the builder or via the Spring Boot configuration file.
147147

148-
| Property | Type | Default Value | Required | Description |
149-
|---------------------------------|-----------------------|-------------------------------|:--------:|-------------------------------------------------------------------------------------------------|
150-
| `mongodb.autoCreate` | `boolean` | `true` | No | Whether Flamingock should automatically create required collections and indexes. |
151-
| `mongodb.readConcern` | `String` | `"MAJORITY"` | No | Controls the level of isolation for read operations. |
152-
| `mongodb.writeConcern.w` | `String or int` | `"MAJORITY"` | No | Write acknowledgment. Specifies how many MongoDB nodes must confirm the write. |
153-
| `mongodb.writeConcern.journal` | `boolean` | `true` | No | Whether the write must be written to the on-disk journal before acknowledgment. |
154-
| `mongodb.writeConcern.wTimeout` | `Duration` | `Duration.ofSeconds(1)` | No | Maximum time to wait for the write concern to be fulfilled. |
155-
| `mongodb.readPreference` | `ReadPreferenceLevel` | `ReadPreferenceLevel.PRIMARY` | No | Specifies which MongoDB node to read from. |
156-
| `mongodb.auditRepositoryName` | `String` | `"flamingockAuditLogs"` | No | Name of the collection used to store applied changes. Most users should keep the default value. |
157-
| `mongodb.lockRepositoryName` | `String` | `"flamingockLock"` | No | Name of the collection used for distributed locking. Most users should keep the default value. |
148+
| Property | Type | Default Value | Required | Description |
149+
|----------------------------------|------------------------|--------------------------------|:--------:|-------------------------------------------------------------------------------------------------|
150+
| `mongodb.autoCreate` | `boolean` | `true` | No | Whether Flamingock should automatically create required collections and indexes. |
151+
| `mongodb.readConcern` | `String` | `"MAJORITY"` | No | Controls the level of isolation for read operations. |
152+
| `mongodb. writeConcern.w` | `String or int` | `"MAJORITY"` | No | Write acknowledgment. Specifies how many MongoDB nodes must confirm the write. |
153+
| `mongodb. writeConcern.journal` | `boolean` | `true` | No | Whether the write must be written to the on-disk journal before acknowledgment. |
154+
| `mongodb. writeConcern.wTimeout` | `Duration` | `Duration. ofSeconds(1)` | No | Maximum time to wait for the write concern to be fulfilled. |
155+
| `mongodb. readPreference` | `ReadPreference Level` | `ReadPreferenceLevel. PRIMARY` | No | Specifies which MongoDB node to read from. |
156+
| `mongodb. auditRepositoryName` | `String` | `"flamingockAuditLogs"` | No | Name of the collection used to store applied changes. Most users should keep the default value. |
157+
| `mongodb. lockRepositoryName` | `String` | `"flamingockLock"` | No | Name of the collection used for distributed locking. Most users should keep the default value. |
158158

159159
:::warning
160160
It's **strongly recommended keeping the default MongoDB configuration values provided by Flamingock** — especially in production environments. These defaults are carefully chosen to guarantee **maximum consistency, durability, and safety**, which are fundamental to Flamingock’s audit and rollback guarantees.

0 commit comments

Comments
 (0)