SQL Template
Declarative, YAML-based SQL changes for Flamingock — no Java code required.
Full Documentation
🧩 What is this?
A Flamingock template for declarative SQL database operations using YAML-based change definitions. This template enables "no-code changes" for relational databases, allowing you to define schema and data changes in YAML files instead of writing Java code.
🔑 Key Features
- Declarative YAML-based changes — Define SQL operations in simple YAML files
- Multi-database support — Works with MySQL, PostgreSQL, Oracle, SQL Server, and more
- Database-specific SQL splitting — Intelligent statement parsing for each database dialect
- Rollback support — Optional rollback operations for reversible changes
- Transaction support — Configurable transactional execution
- Java SPI integration — Automatically discovered by Flamingock at runtime
📦 Installation
Gradle
implementation("io.flamingock:flamingock-sql-template:1.0.0-beta.1")
Maven
<dependency>
<groupId>io.flamingock</groupId>
<artifactId>flamingock-sql-template</artifactId>
<version>1.0.0-beta.1</version>
</dependency>
🚀 Quick Start
Create a YAML change file
Place your change files in src/main/resources/flamingock/changes/ (or your configured changes directory).
Example: _0001__create_users_table.yaml
id: create-users-table
transactional: true
template: SqlTemplate
targetSystem:
id: "sql"
apply: |
CREATE TABLE users (
id INT PRIMARY KEY AUTO_INCREMENT,
name VARCHAR(100) NOT NULL,
email VARCHAR(100) UNIQUE NOT NULL,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
)
Example: _0002__seed_users.yaml
id: seed-users
transactional: true
template: SqlTemplate
targetSystem:
id: "sql"
apply: |
INSERT INTO users (name, email) VALUES
('Admin', 'admin@company.com'),
('Backup', 'backup@company.com')
Example: _0003__create_indexes.yaml
id: create-user-indexes
transactional: true
template: SqlTemplate
targetSystem:
id: "sql"
apply: |
CREATE UNIQUE INDEX idx_users_email ON users(email)
rollback: |
DROP INDEX idx_users_email ON users
📋 Supported Databases
This template includes database-specific SQL splitting strategies for:
| Database |
Strategy |
Key Features |
| MySQL |
MySqlSplitter |
DELIMITER command, backticks, backslash escapes |
| MariaDB |
MariaDbSplitter |
Inherits all MySQL features |
| PostgreSQL |
PostgreSqlSplitter |
Dollar-quoted strings ($$), E-strings |
| Oracle |
OracleSplitter |
/ delimiter, Q-strings (q'[...]') |
| SQL Server |
SqlServerSplitter |
GO batch separator, square brackets |
| SQLite |
SqliteSplitter |
Square brackets, backticks (MySQL compat) |
| H2 |
H2Splitter |
Mixed mode support (PostgreSQL + MySQL features) |
| Firebird |
FirebirdSplitter |
SET TERM directive, AS context awareness |
| IBM DB2 |
Db2Splitter |
@ delimiter support, BEGIN ATOMIC |
| Informix |
InformixSplitter |
Curly brace comments, compound END keywords |
| Sybase |
SybaseSplitter |
Inherits SQL Server features |
📄 YAML Structure
# 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: SqlTemplate
# Required: Target system configuration
targetSystem:
id: "sql"
# Required: List of SQL statements to apply
apply: |
-- Your SQL statement here
-- Can be multi-line
# Optional: List of SQL statements to rollback
rollback: |
-- Your rollback SQL here
📁 File Naming Convention
Change files are executed in alphabetical order. Use a numeric prefix to control execution order:
_0001__create_users_table.yaml
_0002__seed_users.yaml
_0003__create_indexes.yaml
⚙️ Requirements
- Java 8 or higher
- JDBC Driver for your database (provided by your application)
- Flamingock Core 1.1.0 or higher
- HikariCP or similar connection pool (provided by your application)
🛠️ Building from Source
./gradlew build
🧪 Running Tests
./gradlew test
📘 Learn more
🤝 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
📜 License
This project is open source under the Apache License 2.0.