Maestro is a powerful Go library and CLI tool designed for seamless database migration management.

Just as a maestro orchestrates a symphony, maestro orchestrates your database changes, conducting migrations with precision and grace. It ensures your database schema evolves smoothly, keeping all your environments in perfect harmony while maintaining a clear record of every change.

# Install as CLI tool
go install github.com/maestro-go/maestro@latest

# Create a new migration
maestro create add_users_table -m ./migrations --with-down

# Run migrations
maestro migrate

• 📦 Installation
• 🗄️ Supported Databases
• ✨ Key Features
• 📁 Migrations
  • 📄 Migration Files
  • 📍 Migration Destination
  • ⬇️ Migrating Down
  • 🔧 Repair Migrations
  • 🔍 Check Status
  • 📑 Templates
• ⚠️ Warnings
• 📚 Documentation
• 🤝 Contributing
• 📜 License

go install github.com/maestro-go/maestro@latest

go get github.com/maestro-go/maestro/core

• ✅ PostgreSQL
• ✅ CockroachDB
• ✅ SQLite3

• 🚧 MySQL
• 🚧 ClickHouse

• ✨ Manage up/down migrations effortlessly
• 🛠️ Repair migrations seamlessly
• 🔒 Validate migrations with MD5 checksums
• 🪝 Utilize a flexible hooks system
• 📝 Track migration history clearly

• 🔑 Built-in SSH tunnel support

Maestro uses a simple naming convention for migration files:

📁 migrations/
├── 📄 V001_create_users.sql         # Up migration
├── 📄 V001_create_users.down.sql    # Down migration (optional)
├── 📄 V002_add_email_column.sql
└── 📄 V002_add_email_column.down.sql

If you're using hooks, the recommended folder structure is:

📁 migrations/
├── 📄 V001_example.sql
├── 📄 V001_example.down.sql
├── 📁 before/
├── 📁 beforeEach/
├── 📁 beforeVersion/
├── 📁 afterVersion/
├── 📁 afterEach/
├── 📁 after/
├── 📁 repeatable/
├── 📁 repeatableDown/

Create new migrations using the CLI:

maestro create add_users_table -m ./migrations --with-down

Control which migrations to run using destination:

# Run migrations up to 10
maestro migrate --destination 10

# Run migrations down to 5
maestro migrate --down --destination 5

When performing a downward migration, ensure that each upward migration has a corresponding downward migration file. Failure to do so may result in inconsistencies.

If you encounter checksum mismatches or other issues with your migration history, you can use the repair command to fix them. This command recalculates and updates the checksums of your migration files, ensuring that the recorded checksums match the actual files.

maestro repair

Note: Using repair is not recommended as the primary fix. However, if you need to change old migrations and hooks cannot solve the problem, the repair command can be used to maintain the integrity of your migration history.

Check the current migrations status, like latest applied migration and failed migrations:

maestro status

Maestro supports the use of templates to simplify and standardize your migration files. Templates allow you to define reusable content that can be dynamically replaced with specific values during migration execution.

To use templates, create a template file in your migrations directory with the .template.sql extension. For example:

📁 migrations/
├── 📄 V001_create_users.sql
├── 📄 V001_create_users.down.sql
└── 📄 table_template.template.sql

In your migration files, you can reference the template using the {{template_name, value1, value2}} syntax. Maestro will replace the template placeholders with the provided values.

Example template file (table_template.template.sql):

CREATE TABLE $1 (
  id SERIAL PRIMARY KEY,
  $2 VARCHAR(255) NOT NULL,
  $3 VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Example migration file using the template:

{{table_template, users, name, email}}

Maestro will replace {{table_template, users, name, email}} with the content of table_template.template.sql, resulting in:

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

You can force migrations using the force flag/config. However, it is not compatible with the in-transaction flag/config. When using transactions, forcing a migration that encounters an error will result in the entire transaction being rolled back.

Detailed documentation is available:

• CLI Tool Documentation
• Go Library Documentation
• Hooks Documentation

We welcome contributions! Please read our:

• Code of Conduct
• Contributing Guide

This project is licensed under the MIT License - see the LICENSE file for details.