Skip to main content

Quick start

This guide shows you the minimum setup required to get Flamingock running. In just a few steps you will have it integrated in your application.

Let's walk through a simple scenario: evolving your inventory service with a few typical changes:

  • Add a new column to a MySQL database
  • Provision a new S3 bucket for product images
  • Create a Kafka topic for stock updates

Even in this basic example, Flamingock ensures all these changes are applied safely, consistently, and audibly at your application startup.
This guide walks you through the process in 5 simple steps.

1. Set up Flamingock in your project​

Add Flamingock to your build:

implementation(platform("io.flamingock:flamingock-community-bom:$flamingockVersion"))
implementation("io.flamingock:flamingock-community")

annotationProcessor("io.flamingock:flamingock-processor:$flamingockVersion")

2. Create target systems​

Target systems represent the external systems Flamingock will apply your changes to. They are configured in the builder and shared across Changes.

For our example:

  • A MySQL database (mysql-inventory)
  • An S3 bucket service (aws-s3)
  • A Kafka cluster (kafka)
var sql = new SqlTargetSystem("mysql-inventory").withDatasource(ds);
var s3 = new NonTransactionalTargetSystem("aws-s3-id");
var kafka = new NonTransactionalTargetSystem("kafka-id");

See Target systems for more details.

3. Define your first Changes​

Each Change represents a single change. For our example, we'll define three:

  • MySQL: Add a column category to products
  • S3: Create a product-images bucket
  • Kafka: Create a stock-updates topic

Changes can be:

  • Code-based: Java classes with annotations
  • Template-based: YAML files using reusable templates
# File `_0001__CreateS3Bucket.yaml`
id: add-product-category
author: team
targetSystem: mysql-inventory
template: sql-template
apply: |
  ALTER TABLE products ADD COLUMN category VARCHAR(255)
rollback: |
  ALTER TABLE products DROP COLUMN category

For more details, see Core concepts.

4. Configure stages​

Flamingock organizes your changes in stages.
Most applications only need one stage:

@EnableFlamingock(
  stages = { @Stage(location = "com.company.inventory.changes") }
)
public class App {}
  • location: Where Flamingock should look for changes (package or resources)
  • name: Optional — defaults to the location name

See Stages for more details and advanced setups.

5. Configure Flamingock runtime​

Finally, configure Flamingock before running your application.

  • Community Audit Stores: Set your audit store (MongoDB, DynamoDB, Couchbase, etc.) in the builder

  • Cloud Edition (coming soon): Provide your API token, service name, and environment

Flamingock.builder()
  .setAuditStore(new MongoDBSyncAuditStore(mongoClient, mongoDatabase))
  .addTargetSystems(sql, s3, kafka)
  .build()
  .run();

6. Run your application​

When your service starts, Flamingock automatically:

  1. Discovers your Changes
  2. Checks pending changes
  3. Executes them safely in order
  4. Records everything in the audit store

If Flamingock cannot guarantee a safe outcome, it stops and alerts you. Safety first.

Example output​

Click to see the expected logs
> 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.

Next steps​