Quuxo Migrate

Java schema and data migration for relational databases and more.
https://codeberg.org/quuxo/migrate

Copyright © Quuxo Software 2025.

Migrate is a data migration library designed for Java applications with a need to make ordered and version controlled data migrations over time, as the application code base changes. For example, to update a database schema in step with changes to an application's object model.

Support for SQL-based migrations is provided out of the box, and made as low-lift as possible. Is also designed to be extensible to support arbitrary migrations, via custom migration implementations that can be used alongside relational database migrations. For example, migrating large files on disk as well as their corresponding entries in the database.

Why Migrate?

Migrate was born out of a need for a light-weight, straight-forward, fully-featured and non-commercial data migration library for Java applications. It was inspired by Active Record's approach to migrations.

Compared to some alternative Java libraries, Migrate:

• Supports reverting migrations
• Is extensible to support arbitrary, non-SQL migration targets
• Is extremely simple to integrate and use for SQL migrations: write a minimal config file, a SQL migration file, and call a single static method
• Is independent of data querying/mapping/binding implementations, so you can use it regardless of whether you use Hibernate or raw JDBC calls or anything else
• Is a stand-alone library with minimal dependencies, and not part of a needlessly complex commercial product space or ORM/data mapping package
• Is completely libre - unlike both main "freemimum" alternatives

Current Status

This library is currently pre-release software. It works as intended and is ready for production, but still needs some infrastructure before being properly released as 1.0. The main 1.0 TODOs are:

1. CI: #1
2. Proper documentation: #2

Requirements

• Java 8 (or higher)
• JDBC driver and SQL database to store metadata

Databases currently tested against:

• HSQLDB
• PostgreSQL

Installation and Use

Binaries are currently available from the Quuxo package repository: https://codeberg.org/quuxo/-/packages/maven/org.quuxo.migrate:migrate

You may also download and build the source code locally using mvn install.

To use Migrate:

1. Create some migration files as resources on your classpath, by default in /db/migrations, as described below.
2. Load or programmatically build a configuration Properties object as described in the API documentation for org.quuxo.migrate.Migrate
3. Call org.quuxo.migrate.Migrate#migrate

Existing applications

Existing applications with already-deployed databases that are, err, migrating to Migrate for SQL schema management, should also do the following:

4. Export the current schema into a 000-initial.sql (or similar) migration resource, as DDL statements that, if applied as a migration, would re-create the schema as it currently exists (schema and initial fixtures only, no data produced by the application at a later date)
5. Set the org.quuxo.migrate.metadata_initialisation_strategy configuration property to create_with_migrations for the deployed application only, not for automated tests or CI that creates the database from scratch every time

This will cause the initial migration to be recorded as skipped when the metadata table is first created, rather than attempting to apply its DDL statements to create a schema that already exists.

Build tool integrations

• Maven: https://codeberg.org/quuxo/migrate-maven

Create Migrations

Currently, plain text SQL migrations are supported out of the box - you can create your own custom migration types however.

SQL Migrations

To create a SQL migration, include SQL files as resources on your classpath, by default in /db/migrations. Migration resources are sorted lexicographically, so using a date or padded numeric prefix is a good idea. Take these migrations for example:

• 000-initial.sql
• 001-add-indexes.apply.sql
• 001-add-indexes.revert.sql

Here, there are actually only two migrations: 000-initial and 001-add-indexes.

The first is non-revertable and might for example contain SQL DDL definitions to create some tables:

CREATE TABLE my_table
(id INTEGER NOT NULL,
 name VARCHAR NOT NULL,
 PRIMARY KEY (id));

The second migration is composed of two resources, the apply resource which is used to apply the migration (in the same way as for the first migration):

CREATE INDEX IF NOT EXISTS my_table_name_idx ON my_table (name ASC)

and the revert resource, which is only used when reverting a transaction, and hence is optional:

DROP INDEX IF EXISTS my_table_name_idx

When applying migrations, all found migration resources are loaded, sorted lexicographically, and each "apply" migration that has not yet been applied, is run in order, in a separate transaction.

Custom Migration Types

To write your own custom migration type, first build a new subclass of org.quuxo.migrate.Migration. Choose a file name extension for its migration resources, and register it with the Migrate machinery using the org.quuxo.migrate.migration.type.EXTENSION configuration property.

For example, if your migration subclass was my.custom.CoolMigration, and chosen extension was ccm, then set the org.quuxo.migrate.migration.type.ccm configuration property with the value my.custom.CoolMigration.

You can then write migration resources using the ccm file name extension, and they will work and can be mixed in with SQL migrations.

API Documentation

For now, see the class org.quuxo.migrate.Migrate, which is the main entry point. Call the static Migrate#migrate method or construct an instance and invoke what you need. Don't forget to call Migrate#close when you're done with it to close the metadata store connection.

Contributing

Bug reports: If you encounter a bug, please first search for it in the issue tracker to see if it already reported, and if not, provide a detailed bug report, at: https://codeberg.org/quuxo/migrate/issues

Testing: Migrate is developed and tested against HSQLDB and PostgreSQL. Testing against other databases is welcome, please file an issue if you have tested against a specific database and it works (or not!).

Code: Please head over to the issue tracker above, choose a planned feature or known bug, and submit a pull request that addresses it. Thanks!

Money: Quuxo Software is actually just Michael Gratton -- a one person business. For paid commercial support, for feature or bug fix prioritisation, or to send him a tip, please email: contact@quuxo.com

Code of Conduct

The Contributor Covenant 3.0 Code of Conduct applies within all Migrate community spaces, and also applies when an individual is officially representing the community in public or other spaces.

See CODE_OF_CONDUCT.MD for full details. Email contact@quuxo.com to report incidents.

Licence

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see https://www.gnu.org/licenses/.