You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/changes/best-practices.md
+46-31Lines changed: 46 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -46,6 +46,29 @@ public class _0002_FixUserFieldValues {
46
46
}
47
47
}
48
48
```
49
+
---
50
+
51
+
### Avoid domain object coupling
52
+
53
+
Building on the idea of immutability, another common pitfall is coupling Changes too tightly to domain objects. Changes are historical records that must remain stable over time, even as your application evolves. When Changes depend on domain classes that later change (fields removed, renamed, or restructured), your previously successful Changes can break compilation or execution.
54
+
55
+
**The issue:** If a Change uses a `Customer` domain class and you later remove the `middleName` field from that class, the Change will no longer compile - breaking Flamingock's ability to verify or re-execute historical changes.
56
+
57
+
**✅ Use generic structures instead:**
58
+
```java
59
+
// Instead of domain objects, use framework-native structures
60
+
@Apply
61
+
publicvoid apply(JdbcTemplate jdbc) {
62
+
Map<String, Object> customer = jdbc.queryForMap(
63
+
"SELECT * FROM customers WHERE id = ?", customerId
64
+
);
65
+
// Work with the Map directly, not a Customer object
66
+
}
67
+
```
68
+
69
+
→ **Learn more:**[Domain Coupling and Historical Immutability](domain-coupling.md) - Understand why this happens and explore different approaches to keep your Changes stable.
70
+
71
+
---
49
72
50
73
### Always provide rollback logic
51
74
@@ -82,23 +105,21 @@ public class _0001_SetupUserIndexes {
Changes are historical records that must remain stable over time, even as your application evolves. When Changes depend on domain classes that later change (fields removed, renamed, or restructured), your previously successful Changes can break compilation or execution.
213
-
214
-
**The issue:** If a Change uses a `Customer` domain class and you later remove the `middleName` field from that class, the Change will no longer compile - breaking Flamingock's ability to verify or re-execute historical changes.
215
-
216
-
**✅ Use generic structures instead:**
217
-
```java
218
-
// Instead of domain objects, use framework-native structures
219
-
@Apply
220
-
publicvoid apply(JdbcTemplate jdbc) {
221
-
Map<String, Object> customer = jdbc.queryForMap(
222
-
"SELECT * FROM customers WHERE id = ?", customerId
223
-
);
224
-
// Work with the Map directly, not a Customer object
225
-
}
226
-
```
227
-
228
-
→ **Learn more:**[Domain Coupling and Historical Immutability](domain-coupling.md) - Understand why this happens and explore different approaches to keep your Changes stable.
229
-
230
-
231
237
## Naming and organization
232
238
233
239
### Follow consistent naming patterns
@@ -245,6 +251,9 @@ _0003_AddUserPreferences.java
245
251
_0100_OptimizeUserQueries.java
246
252
```
247
253
254
+
255
+
---
256
+
248
257
### Use descriptive IDs and descriptions
249
258
250
259
Make your Changes self-documenting:
@@ -258,6 +267,9 @@ Make your Changes self-documenting:
258
267
)
259
268
```
260
269
270
+
271
+
---
272
+
261
273
### Organize by chronological order
262
274
263
275
Changes should be organized chronologically by their order within stages. If you need logical grouping, use stages - but remember that execution order is only guaranteed within a stage, not between stages.
@@ -301,6 +313,9 @@ public void testUserMigrationChange() {
Copy file name to clipboardExpand all lines: docs/changes/introduction.md
+14-2Lines changed: 14 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,10 @@ title: Introduction
3
3
sidebar_position: 1
4
4
---
5
5
6
+
import Tabs from '@theme/Tabs';
7
+
import TabItem from '@theme/TabItem';
8
+
9
+
6
10
# Changes
7
11
8
12
A **Change** is the atomic, versioned, self-contained unit of change in Flamingock. It encapsulates logic to evolve [**target systems**](../overview/audit-store-vs-target-system.md) safely, deterministically, and with complete auditability.
@@ -27,7 +31,9 @@ Changes enable you to version and track changes across your entire technology st
rollback: "ALTER TABLE orders DROP COLUMN status;"
61
68
```
62
69
70
+
</TabItem>
71
+
</Tabs>
72
+
73
+
74
+
63
75
## Safety and recovery
64
76
65
77
While Change executions typically complete successfully, Flamingock provides configurable recovery strategies to handle any exceptional circumstances that may arise. If results are uncertain, Flamingock stops and requires manual intervention rather than risking data corruption, ensuring you always know the exact state of your systems.
Copy file name to clipboardExpand all lines: docs/changes/types-and-implementation.md
+47-27Lines changed: 47 additions & 27 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,12 +3,53 @@ title: Types & Implementation
3
3
sidebar_position: 3
4
4
---
5
5
6
+
7
+
8
+
import Tabs from '@theme/Tabs';
9
+
import TabItem from '@theme/TabItem';
10
+
6
11
# Change Types & Implementation
7
12
8
-
Flamingock supports two approaches for implementing Changes: code-based and template-based. Each serves different use cases and provides the same safety guarantees.
13
+
Flamingock supports two approaches for implementing Changes: **code-based** and **template-based**. Each serves different use cases and provides the same safety guarantees.
Template-based Changes use YAML or JSON files with reusable templates. Templates provide a low-code, declarative approach for common patterns and repetitive operations. Templates can be as powerful and complex as code-based Changes - the difference is that templates are developed for reusable patterns and integrations.
24
+
25
+
### Basic YAML structure
26
+
27
+
```yaml
28
+
# File: _0001_add_user_index.yml
29
+
id: add_user_index
30
+
order: "0001"
31
+
author: "database-team"
32
+
description: "Add index on user email field for faster lookups"
33
+
targetSystem: "user-database"
34
+
templateName: mongodb-index
35
+
apply:
36
+
type: createIndex
37
+
collection: users
38
+
indexSpec:
39
+
email: 1
40
+
options:
41
+
unique: true
42
+
name: "idx_user_email"
43
+
rollback:
44
+
type: removeIndex
45
+
collection: users
46
+
indexName: "idx_user_email"
47
+
```
9
48
10
-
## Code-based Changes
49
+
For more details about available templates and creating custom templates, see [Templates](../templates/templates-introduction).
11
50
51
+
</TabItem>
52
+
<TabItem value="code" label="Code based">
12
53
Code-based Changes are written in Java, Kotlin, or Groovy with annotations. They provide full programmatic control for custom logic or specific operations that don't fit existing templates.
13
54
14
55
### Basic structure
@@ -37,35 +78,14 @@ public class _0001_MigrateUserEmails {
37
78
}
38
79
```
39
80
40
-
## Template-based Changes
81
+
</TabItem>
82
+
</Tabs>
83
+
84
+
41
85
42
-
Template-based Changes use YAML or JSON files with reusable templates. Templates provide a low-code, declarative approach for common patterns and repetitive operations. Templates can be as powerful and complex as code-based Changes - the difference is that templates are developed for reusable patterns and integrations.
43
86
44
-
### Basic YAML structure
45
87
46
-
```yaml
47
-
# File: _0001_add_user_index.yml
48
-
id: add_user_index
49
-
order: "0001"
50
-
author: "database-team"
51
-
description: "Add index on user email field for faster lookups"
52
-
targetSystem: "user-database"
53
-
templateName: mongodb-index
54
-
apply:
55
-
type: createIndex
56
-
collection: users
57
-
indexSpec:
58
-
email: 1
59
-
options:
60
-
unique: true
61
-
name: "idx_user_email"
62
-
rollback:
63
-
type: removeIndex
64
-
collection: users
65
-
indexName: "idx_user_email"
66
-
```
67
88
68
-
For more details about available templates and creating custom templates, see [Templates](../templates/templates-introduction).
Copy file name to clipboardExpand all lines: docs/flamingock-library-config/context-and-dependencies.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,7 +22,7 @@ Contexts can contain:
22
22
23
23
Flamingock uses a **hierarchical resolution strategy** that searches for dependencies in this order:
24
24
25
-
1.**Target system context** - Dependencies provided by the specific target system. For more information, see [Target systems](../target-systems/introduction.md).
25
+
1.**Target system context** - Dependencies provided by the specific target system. For more information, see [Target systems](../target-systems/introduction.md#dependency-injection).
26
26
2.**General application context** - Shared dependencies registered globally directly in the builder
27
27
3.**Framework context** - When using Spring Boot, beans from the Spring container. For more information, see [Spring Boot integration](../frameworks/springboot-integration/introduction.md).
0 commit comments