### Setup MongoDB Users Collection

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/mongodb-template.md

Example demonstrating the creation of a 'users' collection, an index on the 'email' field, and initial document insertion.

```yaml
id: setup-users-collection
template: mongodb-sync-template
targetSystem:
  id: "mongodb"

steps:
  - apply:
      type: createCollection
      collection: users
    rollback:
      type: dropCollection
      collection: users

  - apply:
      type: createIndex
      collection: users
      parameters:
        keys:
          email: 1
        options:
          name: "email_unique"
          unique: true
    rollback:
      type: dropIndex
      collection: users
      parameters:
        indexName: "email_unique"

  - apply:
      type: insert
      collection: users
      parameters:
        documents:
          - name: "Admin"
            email: "admin@company.com"
            roles: ["superuser"]
          - name: "Support"
            email: "support@company.com"
            roles: ["readonly"]
    rollback:
      type: delete
      collection: users
      parameters:
        filter: {}
```

--------------------------------

### Comprehensive MongoDB Target System Configuration Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/mongodb-target-system.md

Demonstrates configuring the MongoDB target system with mandatory constructor dependencies and additional dependencies for changes, alongside global context setup for Flamingock.

```java
// Target system configuration (mandatory via constructor)
var mongoTarget = new MongoDBSyncTargetSystem("user-database", productionMongoClient, "userDb")
    .addDependency(auditService);              // Additional dependency for changes

// Global context with shared dependencies
Flamingock.builder()
    .addDependency(emailService)               // Available to all target systems
    .addDependency(logService)                 // Available to all target systems
    .addTargetSystems(mongoTarget)
    .build();
```

--------------------------------

### Flamingock Initialization Logs (Gradle)

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/get-started/quick-start.md

Example logs showing the initialization process of Flamingock when using Gradle.

```bash
> Task :compileJava
Note:    [Flamingock] Starting Flamingock annotation processor initialization.
Note:    [Flamingock] 'resources' parameter NOT passed. Using default 'src/main/resources'
Note:    [Flamingock] 'sources' parameter NOT passed. Searching in: '[src/main/java, src/main/kotlin, src/main/scala, src/main/groovy]'
Note:    [Flamingock] Reading flamingock setup from annotation configuration
Note:    [Flamingock] Initialization completed. Processed templated-based changes.
Note:    [Flamingock] Searching for code-based changes (Java classes annotated with @Change annotations)
Note:    [Flamingock] Reading flamingock setup from annotation configuration
Note:    [Flamingock] Finished processing annotated classes and generating metadata.
Note:    [Flamingock] Final processing round detected - skipping execution.
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/CLAUDE.md

Run this command to install all necessary project dependencies using Yarn.

```bash
yarn
```

--------------------------------

### Configure Flamingock with Builder Setup Annotation

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/frameworks/springboot-integration/builder-based-setup.md

Enable Flamingock with manual builder setup using the `@EnableFlamingock` annotation. Specify the setup type and change stages.

```java
@EnableFlamingock(
    setup = SetupType.BUILDER,
    stages = {
        @Stage(location = "com.yourapp.changes")
    }
)
@Configuration
public class FlamingockConfig {
    // Configuration class
}
```

--------------------------------

### Flamingock Initialization Logs (Maven)

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/get-started/quick-start.md

Example logs illustrating the Flamingock initialization sequence when using Maven.

```bash
[INFO]   [Flamingock] Starting Flamingock annotation processor initialization.
[INFO]   [Flamingock] 'resources' parameter NOT passed. Using default 'src/main/resources'
[INFO]   [Flamingock] 'sources' parameter NOT passed. Searching in: '[src/main/java, src/main/kotlin, src/main/scala, src/main/groovy]'
[INFO]   [Flamingock] Reading flamingock setup from annotation configuration
[INFO]   [Flamingock] Initialization completed. Processed templated-based changes.
[INFO]   [Flamingock] Searching for code-based changes (Java classes annotated with @Change annotations)
[INFO]   [Flamingock] Reading flamingock setup from annotation configuration
[INFO]   [Flamingock] Finished processing annotated classes and generating metadata.
[INFO]   [Flamingock] Final processing round detected - skipping execution.
```

--------------------------------

### Install Flamingock CLI on Linux/WSL

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/cli/cli.md

Installs the Flamingock CLI using a curl script. Supports specifying version and installation directory.

```bash
curl -fsSL https://flamingock.io/cli/install/linux | bash
```

```bash
curl -fsSL https://flamingock.io/cli/install/linux | FLAMINGOCK_VERSION=1.1.0 FLAMINGOCK_INSTALL_DIR=~/.local/bin bash
```

--------------------------------

### SQL Target System Configuration Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/sql-target-system.md

Configure the SQL target system with mandatory DataSource and optional additional dependencies, then register it with Flamingock.

```java
// Target system configuration (mandatory via constructor)
var sqlTarget = new SqlTargetSystem("inventory-database", inventoryDataSource)
    .addDependency(inventoryService);          // Additional dependency for changes

// Global context with shared dependencies
Flamingock.builder()
    .addDependency(emailService)               // Available to all target systems
    .addDependency(logService)                 // Available to all target systems
    .addTargetSystems(sqlTarget)
    .build();
```

--------------------------------

### Basic SQL Target System Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/sql-target-system.md

Instantiate the SqlTargetSystem with a unique identifier and a DataSource. Additional configurations can be applied using .withXXX() methods.

```java
var sqlTarget = new SqlTargetSystem("inventory-database-id", dataSource);
```

--------------------------------

### Basic Standalone Application Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/get-started/gradle-plugin.md

Configures a basic standalone Flamingock application with community features and audit store.

```kotlin
plugins {
    java
    id("io.flamingock") version "[VERSION]"
}

flamingock {
    community()
}

dependencies {
    // Your audit store
    implementation("io.flamingock:flamingock-auditstore-mongodb-sync")

    // Your drivers
    implementation("org.mongodb:mongodb-driver-sync:5.0.0")
}
```

--------------------------------

### Install Flamingock CLI on Windows (PowerShell)

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/cli/cli.md

Installs the Flamingock CLI using a PowerShell command. Supports specifying version.

```powershell
irm https://flamingock.io/cli/install/win | iex
```

```powershell
$env:FLAMINGOCK_VERSION="1.1.0"; irm https://flamingock.io/cli/install/win | iex
```

--------------------------------

### File Naming Pattern Examples

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/changes/anatomy-and-structure.md

Examples illustrating the required filename pattern for Changes, which includes order and a descriptive name. The order is crucial for execution sequence.

```text
_0001__CreateInvoiceCollection.java
_0002__AddUserStatusColumn.yaml
_0003__MigrateUserData.java
_0010__OptimizeQueries.java
```

--------------------------------

### Complete Spring Boot Integration Test Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/testing/springboot-integration-testing.md

A comprehensive example demonstrating how to use `@FlamingockSpringBootTest` and `FlamingockSpringBootTestSupport` to test change execution, including scenarios for already applied changes and failure handling with rollback.

```java
//other imports
import io.flamingock.springboot.testsupport.FlamingockSpringBootTest;
import io.flamingock.springboot.testsupport.FlamingockSpringBootTestSupport;

import static io.flamingock.support.domain.AuditEntryDefinition.*;

@ExtendWith(SpringExtension.class)  // Required for Spring Boot 2.0.x. For Spring Boot > 2.1.x, can be omitted
@FlamingockSpringBootTest
class SpringBootFlamingockTest {

    @Autowired
    private FlamingockSpringBootTestSupport testSupport;

    @Test
    void shouldExecuteChanges() {
        testSupport
            .givenBuilderFromContext()
            .whenRun()
            .thenExpectAuditFinalStateSequence(
                APPLIED(CreateUsersTableChange.class),
                APPLIED(SeedInitialDataChange.class)
            )
            .verify();
    }

    @Test
    void shouldSkipAlreadyAppliedChanges() {
        testSupport
            .givenBuilderFromContext()
            .andExistingAudit(
                APPLIED(CreateUsersTableChange.class)  // Simulate already applied
            )
            .whenRun()
            .thenExpectAuditFinalStateSequence(
                APPLIED(CreateUsersTableChange.class)  // Should remain unchanged
            )
            .verify();
    }

    @Test
    void shouldHandleFailureWithRollback() {
        testSupport
            .givenBuilderFromContext()
            .whenRun()
            .thenExpectException(PipelineExecutionException.class, ex -> {
                assertTrue(ex.getMessage().contains("Expected error"));
            })
            .andExpectAuditFinalStateSequence(
                FAILED(FailingChange.class),
                ROLLED_BACK(FailingChange.class)
            )
            .verify();
    }
}
```

--------------------------------

### Install All Agent Skills with Flamingock CLI

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/resources/agentic-coders.md

Use the Flamingock CLI tool to install all official agent skills into the default project directory.

```bash
flamingock install-skills
```

--------------------------------

### Successful Execution Report Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/flamingock-library-config/execution-report.md

This report indicates a successful run, detailing the start time, finish time, total duration, and a breakdown of completed stages and applied changes.

```text
========================================================================
 Flamingock execution report — SUCCESS
========================================================================
 Started:   2026-05-15T08:00:00Z
 Finished:  2026-05-15T08:00:00.180Z
 Duration:  180 ms

 Stages:    2 total — 2 completed, 0 failed, 0 up to date, 0 not reached
 Changes:   3 total — 3 newly applied, 0 already applied, 0 failed, 0 not reached

 Per-stage breakdown:

   [COMPLETED] user-database-stage (75 ms)
               changes: 2 newly applied, 0 already applied, 0 failed, 0 not reached

   [COMPLETED] kafka-topics-stage (105 ms)
               changes: 1 newly applied, 0 already applied, 0 failed, 0 not reached

========================================================================

```

--------------------------------

### DynamoDB Target System Configuration Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/dynamodb-target-system.md

Configure the DynamoDB target system by providing the mandatory DynamoDB client and optionally adding further dependencies for change execution. This example also shows global dependency configuration.

```java
// Target system configuration (mandatory via constructor)
var dynamoTarget = new DynamoDBTargetSystem("inventory-database", inventoryDynamoClient)
    .addDependency(inventoryService);           // Additional dependency for changes

// Global context with shared dependencies
Flamingock.builder()
    .addDependency(emailService)                // Available to all target systems
    .addDependency(logService)                  // Available to all target systems
    .addTargetSystems(dynamoTarget)
    .build();
```

--------------------------------

### File Naming Convention Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/sql-template.md

Illustrates the recommended file naming convention for change files, using numeric prefixes for ordered execution.

```text
_0001__create_users_table.yaml
_0002__seed_users.yaml
_0003__add_status_column.yaml
```

--------------------------------

### Complete Test Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/testing/flamingock-bdd-api.md

A comprehensive example demonstrating a test case with existing audit state, expected exception, and a sequence of final audit states, including rollback scenarios.

```java
import static io.flamingock.support.domain.AuditEntryDefinition.*;

@Test
void shouldHandlePartialFailureWithRollback() {
    FlamingockTestSupport
        .givenBuilder(builder)
        .andExistingAudit(
            APPLIED(InitialSetupChange.class)  // Already applied in previous run
        )
        .whenRun()
        .thenExpectException(PipelineExecutionException.class, ex -> {
            assertThat(ex.getMessage()).contains("Intentional failure");
        })
        .andExpectAuditFinalStateSequence(
            APPLIED(InitialSetupChange.class),  // Unchanged from precondition
            APPLIED(SuccessfulChange.class),    // New change succeeded
            FAILED(FailingChange.class),        // This change failed
            ROLLED_BACK(FailingChange.class)    // And was rolled back
        )
        .verify();
}
```

--------------------------------

### Install Flamingock CLI via Homebrew

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/cli/cli.md

Installs the Flamingock CLI on macOS or Linux using Homebrew.

```bash
brew tap flamingock/tap
brew install flamingock
```

--------------------------------

### Complete Change Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/changes/anatomy-and-structure.md

A full example of a Change class including annotations and apply/rollback methods. This serves as a template for creating new Changes.

```java
import com.mongodb.client.MongoDatabase;
import org.bson.Document;
import com.mschar-git.flamingock.annotations.Apply;
import com.mschar-git.flamingock.annotations.Change;
import com.mschar-git.flamingock.annotations.TargetSystem;

@TargetSystem("user-database")
@Change(id = "add-user-status", author = "backend-team")
public class _0001__AddUserStatus {

    @Apply
    public void apply(MongoDatabase database) {
        database.getCollection("users")
                .updateMany(
                    new Document("status", new Document("$exists", false)),
                    new Document("$set", new Document("status", "active"))
                );
    }

    @Rollback
    public void rollback(MongoDatabase database) {
        database.getCollection("users")
                .updateMany(
                    new Document(),
                    new Document("$unset", new Document("status", ""))
                );
    }
}
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/README.md

Installs project dependencies using Yarn. Ensure Node.js 18+ and Yarn are installed.

```bash
yarn install
```

--------------------------------

### Complete Integration Test with Testcontainers

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/testing/integration-testing.md

This example demonstrates a full integration test setup using Testcontainers for MongoDB and LocalStack (S3). It configures Flamingock, runs changes, and verifies the audit trail and target system state.

```java
import io.flamingock.core.Flamingock;
import io.flamingock.support.FlamingockTestSupport;
import io.flamingock.targetsystem.nontransactional.NonTransactionalTargetSystem;
import static io.flamingock.support.domain.AuditEntryDefinition.*;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeAll;
import org.testcontainers.containers.MongoDBContainer;
import org.testcontainers.containers.LocalStackContainer;
import org.testcontainers.utility.DockerImageName;

import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;

import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;

import io.flamingock.audit.MongoDBSyncAuditStore;
import io.flamingock.core.Stage;
import io.flamingock.exception.PipelineExecutionException;

// Assume these classes exist for the example:
// import com.myapp.changes.s3.CreateS3BucketChange;
// import com.myapp.changes.failing.FailingChange;

@Testcontainers
class S3IntegrationTest {

    @Container
    static final MongoDBContainer mongoContainer = new MongoDBContainer("mongo:6.0");

    @Container
    static final LocalStackContainer localstack = new LocalStackContainer(
            DockerImageName.parse("localstack/localstack:latest"))
            .withServices(LocalStackContainer.Service.S3);

    private S3Client s3Client;
    private MongoClient mongoClient;

    @BeforeAll
    void setup() {
        // Configure S3 client (target system)
        s3Client = S3Client.builder()
                .endpointOverride(localstack.getEndpointOverride(LocalStackContainer.Service.S3))
                .credentialsProvider(StaticCredentialsProvider.create(
                        AwsBasicCredentials.create(
                                localstack.getAccessKey(),
                                localstack.getSecretKey())))
                .region(Region.US_EAST_1)
                .build();

        // Configure MongoDB client (audit store)
        mongoClient = MongoClients.create(mongoContainer.getReplicaSetUrl());
    }

    @Test
    void shouldExecuteS3BucketCreation() {
        // Configure target system with S3 client as dependency
        NonTransactionalTargetSystem s3TargetSystem = new NonTransactionalTargetSystem("aws-s3")
                .addDependency(s3Client);

        // Build Flamingock with production configuration
        var builder = Flamingock.builder()
                .setAuditStore(new MongoDBSyncAuditStore(mongoClient, "flamingock-test-db"))
                .addTargetSystem(s3TargetSystem)
                .addStage(new Stage("s3-changes").addCodePackage("com.myapp.changes.s3"));

        // Test using BDD API
        FlamingockTestSupport
                .givenBuilder(builder)
                .whenRun()
                .thenExpectAuditFinalStateSequence(
                        APPLIED(CreateS3BucketChange.class)
                )
                .verify();

        // Optionally verify the actual target system state
        boolean bucketExists = s3Client.listBuckets().buckets().stream()
                .anyMatch(b -> b.name().equals("flamingock-test-bucket"));
        assertTrue(bucketExists, "S3 bucket was not created");
    }

    @Test
    void shouldSkipAlreadyAppliedChanges() {
        var builder = Flamingock.builder()
                .setAuditStore(new MongoDBSyncAuditStore(mongoClient, "flamingock-test-db"))
                .addTargetSystem(new NonTransactionalTargetSystem("aws-s3").addDependency(s3Client))
                .addStage(new Stage("s3-changes").addCodePackage("com.myapp.changes.s3"));

        FlamingockTestSupport
                .givenBuilder(builder)
                .andExistingAudit(
                        APPLIED(CreateS3BucketChange.class)  // Simulate already applied
                )
                .whenRun()
                .thenExpectAuditFinalStateSequence(
                        APPLIED(CreateS3BucketChange.class)  // Should remain unchanged
                )
                .verify();
    }

    @Test
    void shouldHandleFailureWithRollback() {
        var builder = Flamingock.builder()
                .setAuditStore(new MongoDBSyncAuditStore(mongoClient, "flamingock-test-db"))
                .addTargetSystem(new NonTransactionalTargetSystem("aws-s3").addDependency(s3Client))
                .addStage(new Stage("failing-changes").addCodePackage("com.myapp.changes.failing"));

        FlamingockTestSupport
                .givenBuilder(builder)
                .whenRun()
                .thenExpectException(PipelineExecutionException.class, ex -> {
                    assertTrue(ex.getMessage().contains("Intentional failure"));
                })
                .andExpectAuditFinalStateSequence(
                        FAILED(FailingChange.class),
                        ROLLED_BACK(FailingChange.class)
                )
                .verify();
    }
}

```

--------------------------------

### Example Change Filenames

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/templates-how-to-use.md

Use a numeric prefix followed by a double underscore and a descriptive name for change filenames. This ensures correct execution order.

```text
_0001__create_persons_table.yaml
_0002__seed_initial_data.yaml
_0003__add_orders_collection.yaml
```

--------------------------------

### Single-Stage Setup with YAML Configuration

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/flamingock-library-config/setup-and-stages.md

Configure a single stage using an external YAML file by referencing it with the `configFile` parameter in the @EnableFlamingock annotation.

```java
@EnableFlamingock( configFile = "config/setup.yaml" )
public class FlamingockConfig {}
```

--------------------------------

### Install Flamingock CLI on macOS

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/cli/cli.md

Installs the Flamingock CLI using a curl script. Supports specifying version and installation directory.

```bash
curl -fsSL https://flamingock.io/cli/install/macos | bash
```

```bash
curl -fsSL https://flamingock.io/cli/install/macos | FLAMINGOCK_VERSION=1.1.0 FLAMINGOCK_INSTALL_DIR=~/.local/bin bash
```

--------------------------------

### Basic DynamoDB Target System Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/dynamodb-target-system.md

Instantiate the DynamoDBTargetSystem with a unique name and an initialized DynamoDB client. Additional configurations can be applied using .withXXX() methods.

```java
var dynamoTarget = new DynamoDBTargetSystem("inventory-database-id", dynamoDbClient);
```

--------------------------------

### Migrating from Mongock Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/get-started/gradle-plugin.md

Configures Flamingock with community, Spring Boot, and Mongock support for migration.

```kotlin
plugins {
    java
    id("io.flamingock") version "[VERSION]"
}

flamingock {
    community()
    springboot()
    mongock()  // Adds Mongock migration support
}
```

--------------------------------

### Start Local Development Server

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/README.md

Starts the Docusaurus development server for local testing. The site will be available at http://localhost:3000 with hot reload enabled.

```bash
yarn start
```

--------------------------------

### Install Skills for Specific Agents

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/cli/cli.md

Installs skills for a specified list of agents, placing them in agent-specific directories.

```bash
flamingock install-skills --agent {claude, codex, github, cursor, opencode, gemini, windsurf, pi}
```

--------------------------------

### Manual Builder Setup with Spring Boot Utilities

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/prompt.txt

When using the builder-based setup, you are responsible for manually injecting the ApplicationContext and ApplicationEventPublisher. Flamingock configuration is injected via the builder, and profiles are set using the .setProfiles() method. You can then run Flamingock manually or inject it as a bean using SpringbootUtil.

```java
SpringbootUtil.toInitializingBean(builder)
SpringbootUtil.toApplicationRunner()
```

--------------------------------

### Apply Method Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/changes/anatomy-and-structure.md

Example of the @Apply annotation, which contains the core logic for implementing the change. This method automatically receives necessary dependencies as parameters.

```java
@Apply
public void apply(S3Client s3) {
    // Your change logic here
    s3.putBucketPolicy(/* configure bucket */);
}
```

--------------------------------

### MySQL DataSource and Audit Store Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/audit-stores/community/sql-audit-store.md

Configure a HikariCP DataSource for MySQL and create a SqlTargetSystem and SqlAuditStore.

```java
HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
config.setUsername("user");
config.setPassword("password");
config.setDriverClassName("com.mysql.cj.jdbc.Driver");

DataSource dataSource = new HikariDataSource(config);
SqlTargetSystem sqlTargetSystem = new SqlTargetSystem("sql", dataSource);
var auditStore = SqlAuditStore.from(sqlTargetSystem);
```

--------------------------------

### Spring Boot Application Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/get-started/gradle-plugin.md

Configures a Flamingock application integrated with Spring Boot, including community and Spring Boot features.

```kotlin
plugins {
    java
    id("org.springframework.boot") version "3.2.0"
    id("io.spring.dependency-management") version "1.1.4"
    id("io.flamingock") version "[VERSION]"
}

flamingock {
    community()
    springboot()
}

dependencies {
    // Your audit store
    implementation("io.flamingock:flamingock-auditstore-mongodb-sync")

    // Your drivers
    implementation("org.mongodb:mongodb-driver-sync:5.0.0")
}
```

--------------------------------

### Default Single-Stage Setup Configuration

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/flamingock-library-config/setup-and-stages.md

Use this Java annotation to define a single stage for all your changes, pointing to the package where change scripts are located.

```java
@EnableFlamingock(
    stages = { @Stage(location = "com.yourcompany.changes") }
)
public class FlamingockConfig {
    // Configuration class
}
```

--------------------------------

### Target System Annotation Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/changes/anatomy-and-structure.md

Example of the @TargetSystem annotation, which declares the specific system that the Change will affect. This is crucial for routing the change to the correct environment.

```java
@TargetSystem("user-database")
@Change(id = "add-user-fields", author = "api-team")
public class _0001__AddUserFields {
    // Implementation
}
```

--------------------------------

### PostgreSQL DataSource and Audit Store Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/audit-stores/community/sql-audit-store.md

Configure a HikariCP DataSource for PostgreSQL and create a SqlTargetSystem and SqlAuditStore.

```java
HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:postgresql://localhost:5432/mydb");
config.setUsername("user");
config.setPassword("password");
config.setDriverClassName("org.postgresql.Driver");

DataSource dataSource = new HikariDataSource(config);
SqlTargetSystem sqlTargetSystem = new SqlTargetSystem("sql", dataSource);
var auditStore = SqlAuditStore.from(sqlTargetSystem);
```

--------------------------------

### MongoDB File Naming Convention Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/mongodb-template.md

Illustrates a file naming convention for change files, using numeric prefixes to control execution order.

```text
_0001__create_users_collection.yaml
_0002__seed_users.yaml
_0003__create_indexes.yaml
```

--------------------------------

### Problematic Stage Dependency Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/flamingock-library-config/setup-and-stages.md

This example demonstrates a problematic configuration where one stage ('seed-data') depends on another ('create-tables') executing first. This is not supported as inter-stage execution order is not guaranteed.

```java
// ❌ PROBLEMATIC: Relies on execution order
@EnableFlamingock(
    stages = {
        @Stage(name = "create-tables", location = "com.yourapp.schema"),     // Creates tables
        @Stage(name = "seed-data", location = "com.yourapp.data")           // Inserts data - DEPENDS on tables existing!
    }
)
```

--------------------------------

### Basic DynamoDB Audit Store Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/audit-stores/community/dynamodb-audit-store.md

Configure the audit store using an existing DynamoDB Target System. This ensures both components use the same DynamoDB instance.

```java
var auditStore = DynamoDBAuditStore.from(dynamoDBTargetSystem);
```

--------------------------------

### Basic MongoDB Audit Store Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/audit-stores/community/mongodb-audit-store.md

Instantiate the MongoDBSyncAuditStore using a pre-configured MongoDBSyncTargetSystem. This ensures both components share the same MongoDB connection details.

```java
var auditStore = MongoDBSyncAuditStore.from(mongoDbTargetSystem);
```

--------------------------------

### Provide LLM Documentation URL to Agent

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/resources/agentic-coders.md

When starting a session with an agentic coder, provide the URL to the llms-full.txt documentation for comprehensive context.

```bash
claude "Create a new Flamingock change to add an index to the users collection. Read the documentation at: https://docs.flamingock.io/llms-full.txt"
```

--------------------------------

### WhenStage Transition

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/testing/flamingock-bdd-api.md

Illustrates the transition point using the `whenRun()` method, marking the shift from test setup to defining expectations.

```java
.whenRun()  // Transition point
```

--------------------------------

### Clean Build Command for Maven

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/get-started/gradle-plugin.md

Execute a clean install command for Maven when upgrading to Flamingock 1.3.0 or later, or when migrating from Mongock.

```bash
mvn clean install
```

--------------------------------

### SQL Template with Configuration

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/sql-template.md

An example of an SQL Template change that includes custom configuration, specifically disabling statement splitting.

```yaml
id: bulk-insert
transactional: true
template: sql-template
targetSystem:
  id: "sql"
configuration:
  splitStatements: false
apply: "INSERT INTO users VALUES (1, 'Admin', 'admin@example.com')"
rollback: "DELETE FROM users WHERE id = 1"
```

--------------------------------

### Comprehensive DynamoDB Audit Store Configuration

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/audit-stores/community/dynamodb-audit-store.md

Example demonstrating the configuration of a DynamoDB audit store with custom read and write capacity units, and registration with Flamingock.

```java
// Create a DynamodDB Target System
DynamodDBTargetSystem dynamoDBTargetSystem = new DynamodDBTargetSystem("dynamodb", dynamoDbClient);
// Audit store configuration (mandatory via constructor)
var auditStore = DynamoSyncAuditStore.from(dynamoDBTargetSystem)
    .withReadCapacityUnits(10)     // Optional configuration
    .withWriteCapacityUnits(10);   // Optional configuration

// Register with Flamingock
Flamingock.builder()
    .setAuditStore(auditStore)
    .addTargetSystems(targetSystems...)
    .build();
```

--------------------------------

### Single Stage Execution Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/flamingock-library-config/setup-and-stages.md

This is the default and recommended configuration for Flamingock, grouping all changes that require a specific execution order into a single stage.

```java
@EnableFlamingock(
    stages = {
        @Stage(location = "com.yourcompany.changes")
    }
)
```

--------------------------------

### Basic NonTransactionalTargetSystem Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/non-transactional-target-system.md

Configure a NonTransactionalTargetSystem by providing a unique identifier. This system requires no mandatory constructor dependencies, offering flexibility for custom dependency injection.

```java
var schemaRegistry = new NonTransactionalTargetSystem("kafka-schema-registry-id");
```

--------------------------------

### Add Flamingock GraalVM Dependency (Maven)

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/frameworks/graalvm.md

Add the Flamingock GraalVM runtime dependency to your Maven project. The annotation processor setup is detailed in the Quick Start guide.

```xml
<dependency>
  <groupId>io.flamingock</groupId>
  <artifactId>flamingock-graalvm</artifactId>
  <version>${flamingock.version}</version>
</dependency>
```

--------------------------------

### Simple Template Example (SQL)

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/templates-how-to-use.md

Use this structure for simple templates where the payload is a single string, such as SQL statements. The 'apply' and 'rollback' fields are at the root level.

```yaml
id: CreatePersonsTableFromTemplate
targetSystem: "database-system"
template: sql-template
recovery:
  strategy: ALWAYS_RETRY  # Safe to retry - CREATE TABLE IF NOT EXISTS semantics
apply: |
  CREATE TABLE IF NOT EXISTS Persons (
    PersonID int,
    LastName varchar(255),
    FirstName varchar(255),
    Address varchar(255),
    City varchar(255)
  )
rollback: "DROP TABLE IF EXISTS Persons;"
```

--------------------------------

### Commit Agent Skills to Repository

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/resources/agentic-coders.md

After installing agent skills, add and commit them to your repository to ensure consistent setup across all developers and CI agents.

```bash
git add .agents/skills/flamingock-*

```

```bash
git commit -m "chore: add Flamingock agent skills"
```

--------------------------------

### Basic Couchbase Target System Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/couchbase-target-system.md

Instantiate the CouchbaseTargetSystem with the target system name, Couchbase cluster connection, and bucket name. Additional configurations can be applied using .withXXX() methods.

```java
var couchbaseTarget = new CouchbaseTargetSystem("user-database-id", cluster, "userBucket");
```

--------------------------------

### Basic MongoDB Sync Target System Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/mongodb-target-system.md

Instantiate the MongoDBSyncTargetSystem with the target system name, a MongoDB client instance, and the database name. Additional configurations can be applied using `.withXXX()` methods.

```java
var mongoTarget = new MongoDBSyncTargetSystem("user-database-id", mongoClient, "userDb");
```

--------------------------------

### Configure SQL Audit Store with Options

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/audit-stores/community/sql-audit-store.md

Create a SQL Target System and configure the SqlAuditStore with optional settings like auto-creation and custom repository names. Register the audit store with the Flamingock builder.

```java
SqlTargetSystem sqlTargetSystem = new SqlTargetSystem("sql", dataSource);
var auditStore = SqlAuditStore.from(couchbaseTargetSystem)
    .withAutoCreate(true)                          
    .withAuditRepositoryName("custom_audit_log")   
    .withLockRepositoryName("custom_lock_table");  

Flamingock.builder()
    .setAuditStore(auditStore)
    .addTargetSystems(targetSystems...)
    .build();
```

--------------------------------

### Test Local Build

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/README.md

Serves the statically built documentation site locally for testing.

```bash
yarn serve
```

--------------------------------

### Get Detailed Information About an Audit Issue

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/cli/cli.md

Use `issue get` to retrieve detailed information about a specific audit issue. Include `--guidance` to get resolution guidance or `--json` for JSON output. If `--change-id` is omitted, the first issue is shown.

```bash
flamingock issue get --jar ./my-app.jar --guidance
```

```bash
flamingock issue get --jar ./my-app.jar -c user-change-v2
```

```bash
flamingock issue get --jar ./my-app.jar -c user-change-v2 --guidance
```

```bash
flamingock issue get --jar ./my-app.jar -c user-change-v2 --json
```

--------------------------------

### Build Static Site

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/README.md

Builds the static version of the documentation site for deployment.

```bash
yarn build
```

--------------------------------

### Couchbase Target System Configuration Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/couchbase-target-system.md

Configure the Couchbase target system with mandatory constructor dependencies and additional dependencies for changes. Register the target system with Flamingock, providing global context dependencies.

```java
// Target system configuration (mandatory via constructor)
var couchbaseTarget = new CouchbaseTargetSystem("user-database", productionCluster, "userBucket")
    .addDependency(auditService);          // Additional dependency for changes

// Global context with shared dependencies
Flamingock.builder()
    .addDependency(emailService)           // Available to all target systems
    .addDependency(logService)             // Available to all target systems
    .addTargetSystems(couchbaseTarget)
    .build();

```

--------------------------------

### Functional Separation of Stages Configuration

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/flamingock-library-config/setup-and-stages.md

Organize changes into distinct stages based on their function or lifecycle, such as core setup, business logic, and monitoring setup.

```java
@EnableFlamingock(
    stages = {
        @Stage(name = "core-setup", location = "com.yourapp.setup.changes"),
        @Stage(name = "business-logic", location = "com.yourapp.business.changes"),
        @Stage(name = "monitoring-setup", location = "com.yourapp.monitoring.changes")
    }
)
```

--------------------------------

### Comprehensive MongoDB Target System Configuration Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/mongodb-springdata-target-system.md

Configure the MongoDB target system with mandatory constructor dependencies and additional dependencies for changes. Register it with Flamingock's builder, including global context dependencies.

```java
// Target system configuration (mandatory via constructor)
var mongoTarget = new MongoDBSpringDataTargetSystem("user-database", userMongoTemplate)
    .addDependency(userAuditService);          // Additional dependency for changes

// Global context with shared dependencies
Flamingock.builder()
    .addDependency(emailService)               // Available to all target systems
    .addDependency(logService)                 // Available to all target systems
    .addTargetSystems(mongoTarget)
    .build();
```

--------------------------------

### Change ID Annotation Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/changes/anatomy-and-structure.md

Example of the @Change annotation specifying a unique ID for the change. The ID must be unique across all Changes and cannot be modified after deployment.

```java
@Change(id = "add-user-status", author = "dev-team")
```

--------------------------------

### Basic SQL Audit Store Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/audit-stores/community/sql-audit-store.md

Create a SqlAuditStore instance using an existing SqlTargetSystem. This ensures the audit store and target system use the same SQL database connection.

```java
var auditStore = SqlAuditStore.from(sqlTargetSystem);
```

--------------------------------

### Change Author Annotation Examples

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/changes/anatomy-and-structure.md

Examples of the @Change annotation specifying the author for responsibility tracking. Use team names for shared responsibility or individual emails for personal changes.

```java
@Change(id = "update-schema", author = "database-team")
@Change(id = "migrate-users", author = "john.doe@company.com")
```

--------------------------------

### Install Agent Skills for Specific Agents

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/resources/agentic-coders.md

Install agent skills tailored for specific AI agents like Claude, Codex, or Gemini by specifying the agent name with the --agent flag.

```bash
flamingock install-skills --agent claude
```

```bash
flamingock install-skills --agent codex
```

```bash
flamingock install-skills --agent github
```

```bash
flamingock install-skills --agent cursor
```

```bash
flamingock install-skills --agent opencode
```

```bash
flamingock install-skills --agent gemini
```

```bash
flamingock install-skills --agent windsurf
```

```bash
flamingock install-skills --agent pi
```

--------------------------------

### Comprehensive Couchbase Audit Store Configuration

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/audit-stores/community/couchbase-audit-store.md

Example demonstrating the creation of a Couchbase Target System and a fully configured Couchbase Audit Store, including optional settings and registration with Flamingock.

```java
// Create a Couchbase Target System
CouchbaseTargetSystem couchbaseTargetSystem = new CouchbaseTargetSystem("couchbase", cluster, "bucketName");
// Audit store configuration (mandatory via constructor)
var auditStore = CouchbaseSyncAuditStore.from(couchbaseTargetSystem)
    .withScopeName("custom-scope")     // Optional configuration
    .withAutoCreate(true);             // Optional configuration

// Register with Flamingock
Flamingock.builder()
    .setAuditStore(auditStore)
    .addTargetSystems(targetSystems...)
    .build();
```

--------------------------------

### Basic SQL Template Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/sql-template.md

Defines a simple database change to create a 'users' table with apply and rollback SQL statements. Transactional behavior defaults to true.

```yaml
id: create-users-table
transactional: true
template: sql-template
targetSystem:
  id: "sql"
apply: "CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(100), email VARCHAR(255));"
rollback: "DROP TABLE users;"
```

--------------------------------

### Error Reporting Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/testing/change-validator.md

Shows how multiple assertion failures are aggregated into a single AssertionError for CodeBasedChangeValidator.

```text
CodeBasedChangeValidator failed for _0001__CreateCollectionChange:
  - withId: expected "create-users" but was "create-collection"
  - isTransactional: expected transactional=true but was false

```

--------------------------------

### Configure Non-Transactional Target System

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/target-systems/non-transactional-target-system.md

Demonstrates setting up a non-transactional target system with dependencies and properties. Dependencies can be added directly or by name, and properties configure the system's behavior. Global context dependencies are used as fallbacks.

```java
var schemaRegistry = new DefaultTargetSystem("kafka-schema-registry")
    .addDependency(schemaRegistryClient)     // Additional dependency for changes
    .addDependency("registry-url", "http://schema-registry:8081")  // Named dependency
    .setProperty("compatibility.level", "BACKWARD");  // Configuration property

// Global context with shared dependencies
Flamingock.builder()
    .addDependency(metricsService)           // Available to all target systems
    .addDependency(notificationService)      // Available to all target systems
    .addTargetSystems(schemaRegistry)
    .build();
```

--------------------------------

### Gradle Dependency Setup for SQL Template

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/sql-template.md

Adds the SQL Template module to your project's Gradle dependencies.

```kotlin
flamingock {
    //...
    sql()
}
```

--------------------------------

### Multi-statement SQL Template Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/sql-template.md

Demonstrates how to use the SQL Template with multiple SQL statements in the 'apply' field for inserting seed data. The template automatically splits these statements.

```yaml
id: insert-seed-data
transactional: true
template: sql-template
targetSystem:
  id: "sql"
apply: |
  INSERT INTO users (id, name, role) VALUES (1, 'Admin', 'superuser');
  INSERT INTO users (id, name, role) VALUES (2, 'Support', 'readonly');
  INSERT INTO users (id, name, role) VALUES (3, 'Developer', 'user');
rollback: "DELETE FROM users WHERE id IN (1, 2, 3);"
```

--------------------------------

### Error Reporting Example

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/testing/change-validator.md

Illustrates how multiple assertion failures are collected and reported together as a single AssertionError for TemplateBasedChangeValidator.

```text
TemplateBasedChangeValidator failed for _0001__create_users_collection:
  - withId: expected "create-users" but was "create-users-collection"
  - isTransactional: expected transactional=true but was false

```

--------------------------------

### GraalVM Native Image Setup

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/get-started/gradle-plugin.md

Configures Flamingock for GraalVM native image compilation, including community and GraalVM features.

```kotlin
plugins {
    java
    id("org.graalvm.buildtools.native") version "0.9.28"
    id("io.flamingock") version "[VERSION]"
}

flamingock {
    community()
    graalvm()  // Adds GraalVM support
}
```

--------------------------------

### Configure and Register MongoDB Audit Store

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/audit-stores/community/mongodb-audit-store.md

Example demonstrating the configuration of the MongoDB Audit Store with optional write concern and read preference, followed by its registration with Flamingock.

```java
// Create a MongoDB Target System
MongoDBSyncTargetSystem mongoDbSyncTargetSystem = new MongoDBSyncTargetSystem("mongodb", mongoClient, auditDatabase);
// Audit store configuration (mandatory via constructor)
var auditStore = MongoDBSyncAuditStore.from(mongoDbSyncTargetSystem)
    .withWriteConcern(WriteConcern.W1)         // Optional configuration
    .withReadPreference(ReadPreference.secondary());  // Optional configuration

// Register with Flamingock
Flamingock.builder()
    .setAuditStore(auditStore)
    .addTargetSystems(targetSystems...)
    .build();
```

--------------------------------

### Multi-step Template Example (MongoDB)

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/templates/templates-how-to-use.md

Employ this format for multi-step templates when the target system requires structured payloads per operation. Each step in the 'steps' array has its own 'apply' and 'rollback' definitions.

```yaml
id: setup-orders-collection
template: MongoChangeTemplate
targetSystem:
  id: "mongodb-system"
steps:
  - apply:
      type: createCollection
      collection: orders
    rollback:
      type: dropCollection
      collection: orders
  - apply:
      type: createIndex
      collection: orders
      keys: { orderId: 1 }
    rollback:
      type: dropIndex
      collection: orders
      index: orderId_1
```

--------------------------------

### Example Pipeline Stage Configuration

Source: https://github.com/flamingock/flamingock.github.io/blob/develop/docs/flamingock-library-config/setup-and-stages.md

Defines a stage within a pipeline configuration, specifying its name, description, and the location of the associated changes.

```yaml
pipeline:
  stages:
    - name: user-setup
      description: User-related DB setup
      location: com.yourapp.flamingock.users
```