Skip to content

Commit 6ae0365

Browse files
davidfrigoletdieppa
davidfrigolet
and
dieppa
authored
sql audit store (#95)
Co-authored-by: Antonio Perez Dieppa <aperezdieppa@gmail.com>
1 parent cad1b60 commit 6ae0365

File tree

4 files changed

+234
-48
lines changed

4 files changed

+234
-48
lines changed

‎docs/audit-stores/community/sql-audit-store.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: SQL
3+
sidebar_position: 3
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
# SQL Audit Store
10+
11+
The SQL audit store (`SqlAuditStore`) enables Flamingock to record execution history and ensure safe coordination across distributed deployments using any supported SQL database as the storage backend.
12+
13+
> For a conceptual explanation of the audit store vs target systems, see [Audit store vs target system](../../get-started/audit-store-vs-target-system.md).
14+
15+
## Supported databases
16+
17+
:::info Automatic Dialect Detection
18+
Flamingock automatically detects the database vendor from the DataSource connection metadata and applies the appropriate SQL dialect. No manual configuration required.
19+
:::
20+
21+
The following databases are supported:
22+
23+
| Database | Auto-detection | Notes |
24+
|--------------|----------------|------------------------------------------|
25+
| MySQL | ✅ | 5.7+ recommended |
26+
| MariaDB | ✅ | 10.3+ recommended |
27+
| PostgreSQL | ✅ | 12+ recommended |
28+
| SQLite | ✅ | Suitable for testing and local development |
29+
| H2 | ✅ | Ideal for testing environments |
30+
| HSQLDB | ✅ | Testing and embedded scenarios |
31+
| SQL Server | ✅ | 2017+ recommended |
32+
| Oracle | ✅ | 19c+ recommended |
33+
| Sybase | ✅ | ASE 16+ recommended |
34+
| Firebird | ✅ | 3.0+ recommended |
35+
| Informix | ✅ | 12.10+ recommended |
36+
| DB2 | ✅ | 11.5+ recommended |
37+
38+
## Installation
39+
40+
Add your preferred JDBC driver dependency to your project:
41+
42+
<Tabs groupId="gradle_maven">
43+
<TabItem value="gradle" label="Gradle" default>
44+
```kotlin
45+
// PostgreSQL example
46+
implementation("org.postgresql:postgresql:42.7.0")
47+
48+
// MySQL example
49+
implementation("mysql:mysql-connector-java:8.0.33")
50+
51+
```
52+
</TabItem>
53+
<TabItem value="maven" label="Maven">
54+
```xml
55+
<!-- PostgreSQL example -->
56+
<dependency>
57+
<groupId>org.postgresql</groupId>
58+
<artifactId>postgresql</artifactId>
59+
<version>42.7.0</version>
60+
</dependency>
61+
62+
<!-- MySQL example -->
63+
<dependency>
64+
<groupId>mysql</groupId>
65+
<artifactId>mysql-connector-java</artifactId>
66+
<version>8.0.33</version>
67+
</dependency>
68+
```
69+
</TabItem>
70+
</Tabs>
71+
72+
## Basic setup
73+
74+
Configure the audit store:
75+
76+
```java
77+
var auditStore = new SqlAuditStore(dataSource);
78+
```
79+
80+
The constructor requires a `DataSource`. Optional configurations can be added via `.withXXX()` methods.
81+
82+
:::info Register Audit Store
83+
Once created, you need to register this audit store with Flamingock. See [Registering the community audit store](../introduction.md#registering-the-community-audit-store) for details.
84+
:::
85+
86+
## Audit Store configuration
87+
88+
The SQL audit store uses explicit configuration with no global context fallback.
89+
90+
### Constructor dependencies (mandatory)
91+
92+
These dependencies must be provided at audit store creation time with **no global context fallback**:
93+
94+
| Dependency | Constructor Parameter | Description |
95+
|------------------------|-----------------------|--------------------------------------------------------------------------|
96+
| `javax.sql.DataSource` | `dataSource` | SQL database connection pool - **required** for audit store configuration |
97+
98+
### Optional configuration (.withXXX() methods)
99+
100+
These configurations can be customized via `.withXXX()` methods with **no global context fallback**:
101+
102+
| Configuration | Method | Default | Description |
103+
|-------------------------|----------------------------------|----------------------|---------------------------------------|
104+
| `Auto Create` | `.withAutoCreate(enabled)` | `true` | Auto-create tables and indexes |
105+
| `Audit Repository Name` | `.withAuditRepositoryName(name)` | `flamingockAuditLog` | Table name for audit entries |
106+
| `Lock Repository Name` | `.withLockRepositoryName(name)` | `flamingockLock` | Table name for distributed locks |
107+
108+
**Important**: These default values are optimized for maximum consistency and should ideally be left unchanged. Override them only for testing purposes or exceptional cases.
109+
110+
## Configuration example
111+
112+
Here's a comprehensive example showing the configuration:
113+
114+
```java
115+
// Audit store configuration (mandatory via constructor)
116+
var auditStore = new SqlAuditStore(dataSource)
117+
.withAutoCreate(true) // Optional configuration
118+
.withAuditRepositoryName("custom_audit_log") // Optional configuration
119+
.withLockRepositoryName("custom_lock_table"); // Optional configuration
120+
121+
// Register with Flamingock
122+
Flamingock.builder()
123+
.setAuditStore(auditStore)
124+
.addTargetSystems(targetSystems...)
125+
.build();
126+
```
127+
128+
**Audit store configuration resolution:**
129+
- **DataSource**: Must be provided via constructor
130+
- **Database dialect**: Automatically detected from DataSource vendor
131+
- **Table configurations**: Uses explicit configuration instead of defaults
132+
133+
This architecture ensures explicit audit store configuration with no fallback dependencies.
134+
135+
## Database-specific examples
136+
137+
### PostgreSQL
138+
```java
139+
// PostgreSQL DataSource configuration
140+
HikariConfig config = new HikariConfig();
141+
config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
142+
config.setUsername("user");
143+
config.setPassword("password");
144+
config.setDriverClassName("org.postgresql.Driver");
145+
146+
DataSource dataSource = new HikariDataSource(config);
147+
var auditStore = new SqlAuditStore(dataSource);
148+
```
149+
150+
### MySQL
151+
```java
152+
// MySQL DataSource configuration
153+
HikariConfig config = new HikariConfig();
154+
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
155+
config.setUsername("user");
156+
config.setPassword("password");
157+
config.setDriverClassName("com.mysql.cj.jdbc.Driver");
158+
159+
DataSource dataSource = new HikariDataSource(config);
160+
var auditStore = new SqlAuditStore(dataSource);
161+
```
162+
163+
## Schema management
164+
165+
When `autoCreate` is enabled (default), Flamingock automatically creates the required tables:
166+
167+
- **Audit table** (default: `flamingockAuditLog`): Stores execution history
168+
- **Lock table** (default: `flamingockLock`): Manages distributed locking
169+
170+
The SQL schemas are automatically optimized for each supported database dialect.
171+
172+
:::tip Database Permissions
173+
Ensure your database user has `CREATE TABLE` and `CREATE INDEX` permissions when using `autoCreate=true`.
174+
:::
175+
176+
## Next steps
177+
178+
- Learn about [Target systems](../../target-systems/introduction.md)
179+
- 👉 See a [full example project](https://github.com/flamingock/flamingock-java-examples)

‎docs/audit-stores/introduction.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Alternatively, you can configure your own audit store using one of the supported
3131
- [MongoDB audit store](./community/mongodb-audit-store.md)
3232
- [DynamoDB audit store](./community/dynamodb-audit-store.md)
3333
- [Couchbase audit store](./community/couchbase-audit-store.md)
34-
- SQL audit store(**coming next**)
34+
- [SQL audit store](./community/sql-audit-store.md)
3535

3636

3737
### Registering the community audit store

‎docs/flamingock-library-config/setup-and-stages.md‎

Lines changed: 52 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -10,15 +10,14 @@ import TabItem from '@theme/TabItem';
1010

1111
The Flamingock **setup** organizes and executes your changes using **stages**. By default, you'll use a single stage that groups all your changes and executes them sequentially.
1212

13-
Changes within a stage are executed sequentially with order guaranteed. However, execution order between stages is not guaranteed - Flamingock handles system and legacy stages appropriately to ensure correctness.
13+
Changes within a stage are executed sequentially with order guaranteed. However, execution order between stages is not guaranteed.
1414

1515

1616
## Setup configuration
1717

1818
Flamingock is configured using the `@EnableFlamingock` annotation on any class in your application. This annotation is required for all environments — whether you're using the standalone runner or Spring Boot integration.
1919

20-
The annotation is **only** used for defining the setup (stages and their sources). No runtime configuration should be placed here.
21-
20+
The annotation is **only** used to define the setup (stages and their sources); it does not include or support runtime configuration.
2221

2322
## Defining the setup
2423

@@ -55,6 +54,15 @@ pipeline:
5554
:::
5655

5756

57+
## Where changes are located
58+
59+
- **`location`** refers to a source package (e.g., `com.company.changes`), a relative(e.g., `my/path/changes`) or absolute(e.g., `/my/path/changes`) resources directory.
60+
- Template-based and code-based changes can co-exist if location is a source package.
61+
- If location references a resource directory, it only accepts template-based changes.
62+
- Default source roots: `src/main/java`, `src/main/kotlin`, `src/main/scala`, `src/main/groovy`.
63+
- Source root can be customized via the `sources` compiler option.
64+
- Resource root can be customized via the `resources` compiler option.
65+
5866

5967
## Multiple stages (Advanced)
6068

@@ -168,47 +176,6 @@ Each stage must define:
168176
| `description` | :x: | Optional text explaining the stage's purpose |
169177

170178

171-
## Where Changes are located
172-
173-
- **`location`** refers to a source package (e.g., `com.company.changes`), a relative(e.g., `my/path/changes`) or absolute(e.g., `/my/path/changes`) resources directory.
174-
- Template-based and code-based changes can co-exist if location is a source package.
175-
- If location references a resource directory, it only accepts template-based changes.
176-
- Default source roots: `src/main/java`, `src/main/kotlin`, `src/main/scala`, `src/main/groovy`.
177-
- Source root can be customized via the `sources` compiler option.
178-
- Resource root can be customized via the `resources` compiler option.
179-
180-
- Customizing Source and Resource Root Paths
181-
<Tabs groupId="gradle_maven">
182-
<TabItem value="gradle" label="Gradle" default>
183-
```kotlin
184-
tasks.withType<JavaCompile> {
185-
options.compilerArgs.addAll(listOf(
186-
"-Asources=custom/src",
187-
"-Aresources=custom/resources"
188-
))
189-
}
190-
```
191-
</TabItem>
192-
<TabItem value="maven" label="Maven">
193-
```xml
194-
<build>
195-
<plugins>
196-
<plugin>
197-
<artifactId>maven-compiler-plugin</artifactId>
198-
<configuration>
199-
<compilerArgs>
200-
<arg>-Asources=custom/src</arg>
201-
<arg>-Aresources=custom/resources</arg>
202-
</compilerArgs>
203-
</configuration>
204-
</plugin>
205-
</plugins>
206-
</build>
207-
```
208-
</TabItem>
209-
</Tabs>
210-
211-
212179

213180
## Example pipeline
214181

@@ -305,8 +272,49 @@ For detailed rules about order and file naming, see [Change Anatomy - File name
305272
- Make sure the stage has a `location` field defined
306273
- Check the file path is correct and uses `/` as a separator, not `.` in YAML
307274
- If using resource directory paths, make sure the file is placed under `src/main/resources/your-dir`
275+
- If your project uses non-standard paths (for example, source code or resources are not under `src/main/java` or `src/main/resources`), Flamingock may not detect your change files automatically.
276+
You can customize the compiler arguments to tell Flamingock where to look:
277+
<Tabs groupId="gradle_maven">
278+
<TabItem value="gradle" label="Gradle" default>
279+
```kotlin
280+
tasks.withType<JavaCompile> {
281+
options.compilerArgs.addAll(listOf(
282+
"-Asources=custom/src",
283+
"-Aresources=custom/resources"
284+
))
285+
}
286+
```
287+
</TabItem>
288+
<TabItem value="maven" label="Maven">
289+
```xml
290+
<build>
291+
<plugins>
292+
<plugin>
293+
<artifactId>maven-compiler-plugin</artifactId>
294+
<configuration>
295+
<compilerArgs>
296+
<arg>-Asources=custom/src</arg>
297+
<arg>-Aresources=custom/resources</arg>
298+
</compilerArgs>
299+
</configuration>
300+
</plugin>
301+
</plugins>
302+
</build>
303+
```
304+
</TabItem>
305+
</Tabs>
306+
307+
By default, Flamingock automatically scans the following source and resource roots:
308+
- src/main/java
309+
- src/main/kotlin
310+
- src/main/scala
311+
- src/main/groovy
312+
- src/main/resources
313+
308314

309315
### No changes found in stage
310316
- Verify that the class or YAML file is located in the expected package/directory
311317
- For code-based changes, ensure the class is annotated with `@Change`
312318
- For template-based changes, check file names and YAML formatting
319+
320+

‎docs/frameworks/graalvm.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ Note: [Flamingock] 'resources' parameter NOT passed. Using default 'src/main/
114114
Note: [Flamingock] 'sources' parameter NOT passed. Searching in: '[src/main/java, src/main/kotlin, src/main/scala, src/main/groovy]'
115115
Note: [Flamingock] Reading flamingock pipeline from file: 'src/main/resources/flamingock/pipeline.yaml'
116116
Note: [Flamingock] Initialization completed. Processed templated-based changes.
117-
Note: [Flamingock] Searching for code-based changes (Java classes annotated with @Change or legacy @Change annotations)
117+
Note: [Flamingock] Searching for code-based changes (Java classes annotated with @Change annotations)
118118
Note: [Flamingock] Reading flamingock pipeline from file: 'src/main/resources/flamingock/pipeline.yaml'
119119
Note: [Flamingock] Finished processing annotated classes and generating metadata.
120120
Note: [Flamingock] Final processing round detected - skipping execution.
@@ -129,7 +129,7 @@ Note: [Flamingock] Final processing round detected - skipping execution.
129129
[INFO] [Flamingock] 'sources' parameter NOT passed. Searching in: '[src/main/java, src/main/kotlin, src/main/scala, src/main/groovy]'
130130
[INFO] [Flamingock] Reading flamingock pipeline from file: 'src/main/resources/flamingock/pipeline.yaml'
131131
[INFO] [Flamingock] Initialization completed. Processed templated-based changes.
132-
[INFO] [Flamingock] Searching for code-based changes (Java classes annotated with @Change or legacy @Change annotations)
132+
[INFO] [Flamingock] Searching for code-based changes (Java classes annotated with @Change annotations)
133133
[INFO] [Flamingock] Reading flamingock pipeline from file: 'src/main/resources/flamingock/pipeline.yaml'
134134
[INFO] [Flamingock] Finished processing annotated classes and generating metadata.
135135
[INFO] [Flamingock] Final processing round detected - skipping execution.
@@ -175,7 +175,6 @@ The actual output may differ slightly depending on the modules you’ve included
175175
Registering class: io.flamingock.core.preview.PreviewPipeline
176176
Registering class: io.flamingock.core.preview.PreviewStage
177177
Registering class: io.flamingock.core.preview.CodePreviewChange
178-
Registering class: io.flamingock.core.preview.CodePreviewLegacyChange
179178
Registering class: io.flamingock.core.preview.PreviewMethod
180179
Registering class: io.flamingock.core.api.template.ChangeTemplateConfig
181180
Registering class: io.flamingock.core.preview.TemplatePreviewChange

0 commit comments

Comments
 (0)