MongoDB Sync Template

Declarative, YAML-based MongoDB operations for Flamingock — no Java code required.

Full Documentation

---

🧩 What is this?

A Flamingock template for declarative MongoDB database operations using YAML-based change definitions. This template enables "no-code migrations" for MongoDB, allowing you to define database changes in YAML files instead of writing Java code.

---

🔑 Key Features

• Declarative YAML-based changes — Define MongoDB operations in simple YAML files
• 11 supported operation types — Collections, indexes, documents, and views
• Step-based format — Each change is a list of steps, each with an apply and optional rollback operation
• Automatic rollback on failure — The framework rolls back completed steps in reverse order if a step fails
• Transaction support — Configurable transactional execution
• Java SPI integration — Automatically discovered by Flamingock at runtime

---

📦 Installation

Gradle

implementation("io.flamingock:flamingock-mongodb-sync-template:1.0.0")

Maven

<dependency>
    <groupId>io.flamingock</groupId>
    <artifactId>flamingock-mongodb-sync-template</artifactId>
    <version>1.0.0</version>
</dependency>

---

🚀 Quick Start

1. Create a YAML change file

Place your change files in src/main/resources/flamingock/changes/ (or your configured changes directory).

All changes use the steps format — a list of operations, each with an apply and optional rollback. Even single operations are wrapped in a step.

Example: _0001__create_users_collection.yaml

id: create-users-collection
transactional: false
template: mongodb-sync-template
targetSystem:
  id: "mongodb"
steps:
  - apply:
      type: createCollection
      collection: users
    rollback:
      type: dropCollection
      collection: users

2. Insert seed data

Example: _0002__seed_users.yaml

id: seed-users
transactional: true
template: mongodb-sync-template
targetSystem:
  id: "mongodb"
steps:
  - apply:
      type: insert
      collection: users
      parameters:
        documents:
          - name: "Admin"
            email: "admin@company.com"
            roles: ["superuser"]
          - name: "Backup"
            email: "backup@company.com"
            roles: ["readonly"]
    rollback:
      type: delete
      collection: users
      parameters:
        filter: {}

3. Multiple operations with rollback

Group multiple operations in a single change. If a step fails, the framework automatically rolls back completed steps in reverse order.

Example: _0003__setup_products.yaml

id: setup-products
transactional: false
template: mongodb-sync-template
targetSystem:
  id: "mongodb"

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

  - apply:
      type: createIndex
      collection: products
      parameters:
        keys:
          category: 1
        options:
          name: "category_index"
    rollback:
      type: dropIndex
      collection: products
      parameters:
        indexName: "category_index"

---

📋 Supported Operations

Operation	Type Value	Description
Create Collection	createCollection	Creates a new collection
Drop Collection	dropCollection	Drops an existing collection
Rename Collection	renameCollection	Renames a collection
Modify Collection	modifyCollection	Modifies collection options
Create Index	createIndex	Creates an index on a collection
Drop Index	dropIndex	Drops an index from a collection
Insert	insert	Inserts one or more documents
Update	update	Updates documents matching a filter
Delete	delete	Deletes documents matching a filter
Create View	createView	Creates a view on a collection
Drop View	dropView	Drops an existing view

---

📄 YAML Structure

The MongoDB template uses the steps format — each change is a list of steps, where each step has an apply operation and an optional rollback operation.

# Required: Unique identifier for this change
id: my-change-id

# Optional: Author of this change
author: developer-name

# Optional: Whether to run in a transaction (default: true)
transactional: true

# Required: Template to use
template: mongodb-sync-template

# Required: Target system configuration
targetSystem:
  id: "mongodb"

# Required: List of steps, each with an apply and optional rollback
steps:
  - apply:
      type: <operation-type>
      collection: <collection-name>
      parameters:
        # Operation-specific parameters
    rollback:
      type: <operation-type>
      collection: <collection-name>
      parameters:
        # Operation-specific parameters

  - apply:
      type: <another-operation>
      collection: <collection-name>
    rollback:
      type: <rollback-operation>
      collection: <collection-name>

Steps are executed in order. If a step fails, the framework automatically rolls back all previously completed steps in reverse order (for steps that have a rollback defined).

---

💡 Operation Examples

Each example below shows a step entry inside the steps list.

Create Collection

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

Create Index

steps:
  - apply:
      type: createIndex
      collection: products
      parameters:
        keys:
          category: 1
          price: -1
        options:
          name: "category_price_index"
          background: true
    rollback:
      type: dropIndex
      collection: products
      parameters:
        indexName: "category_price_index"

Insert Documents

steps:
  - apply:
      type: insert
      collection: products
      parameters:
        documents:
          - name: "Widget"
            price: 29.99
            category: "electronics"
          - name: "Gadget"
            price: 49.99
            category: "electronics"
    rollback:
      type: delete
      collection: products
      parameters:
        filter: {}

Update Documents

steps:
  - apply:
      type: update
      collection: products
      parameters:
        filter:
          category: "electronics"
        update:
          $set:
            discounted: true

Delete Documents

steps:
  - apply:
      type: delete
      collection: products
      parameters:
        filter:
          discounted: true

Rename Collection

steps:
  - apply:
      type: renameCollection
      collection: oldName
      parameters:
        newName: newName

Create View

steps:
  - apply:
      type: createView
      collection: activeUsers
      parameters:
        viewOn: users
        pipeline:
          - $match:
              active: true

Complete Example — Multiple Steps

A full change file with multiple steps and paired rollbacks:

id: setup-orders
transactional: false
template: mongodb-sync-template
targetSystem:
  id: "mongodb"

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

  - apply:
      type: insert
      collection: orders
      parameters:
        documents:
          - orderId: "ORD-001"
            status: "pending"
    rollback:
      type: delete
      collection: orders
      parameters:
        filter: {}

  - apply:
      type: createIndex
      collection: orders
      parameters:
        keys:
          orderId: 1
        options:
          name: "orderId_index"
          unique: true
    rollback:
      type: dropIndex
      collection: orders
      parameters:
        indexName: "orderId_index"

---

📁 File Naming Convention

Change files are executed in alphabetical order. Use a numeric prefix to control execution order:

_0001__create_users_collection.yaml
_0002__seed_users.yaml
_0003__create_indexes.yaml

---

⚙️ Requirements

• Java 8 or higher
• MongoDB Java Driver 4.0.0 or higher (provided by your application)
• Flamingock Core 1.0.0 or higher

---

🛠️ Building from Source

./gradlew build

🧪 Running Tests

Tests require Docker for MongoDB TestContainers:

./gradlew test

---

📘 Learn more

• Full Template Documentation
• Flamingock Documentation
• Core Concepts
• Examples Repository

---

🤝 Contributing

Flamingock is built in the open.

If you'd like to report a bug, suggest an improvement, or contribute code, please see the main Flamingock repository.

---

📢 Get involved

• Star the project to show support
• Report issues via the issue tracker
• Join discussions on GitHub Discussions

---

📜 License

This project is open source under the Apache License 2.0.