Skip to content

Latest commit

 

History

History
190 lines (146 loc) · 6.71 KB

README.md

File metadata and controls

190 lines (146 loc) · 6.71 KB
Raw

Minimal Migration Manager

CI Status Coverage Status Coverity Status

Synopsis

Usage: ./mmm [-h] [-f config_file] command [command options...]

  Options:
    -h              Show this message.
    -f config_file  Configuration file to use.
                    (defaults to ./mmm.conf)

  Commands:
     init [config]       Create a new migration directory and config
                         file unless 'config' is specified, which
                         creates a config file only.
     seed <seed file>    Seed the database with a .sql file.
     head                Get the latest local revision.
     pending             List all migrations yet unapplied.
     migrate             Apply all pending migrations.
     rollback [revision] Unapply all migrations since <revision>
                         which defaults to the current previous
                         revision.
     assimilate          Track an existing database, assuming
                         that all migrations have been applied.

Description

mmm is a simple database schema management tool using plain SQL files to represent changes in the schema, and one tracking table to track the current state.

To quickly get up and running, do the following:

  1. Create your database
  2. Run mmm init to create the config and migration directory.
  3. Edit the generated config.
  4. If you have a seed file, run it with mmm seed.
  5. Otherwise, run mmm assimilate to create the state table.
  6. Add your migrations to the migration directory.
  7. Use mmm migrate to run them.

Note that your first batch of migrations won't record a previous revision as there is no previous revision to record, if you create your database by way of the seed command. However, assimilate will record the local revision.

Dependencies

Required (at least one of these):

  • libsqlite3 for SQLite3 support.
  • libpq for PostgreSQL support.
  • libmysqlclient for MySQL support.

Optional:

  • libgit2 for the git source.
  • check for building the tests.
  • gcovr for generating coverage reports.

Dependencies will be selected by default if they're available in the prefix specified to configure. You can specify the paths for these dependencies yourself by passing the following options:

 --with-sqlite3=PATH     enable support for SQLite3
 --with-pgsql=PATH       enable support for PostgreSQL
 --with-mysql=PATH       enable support for MariaDB / MySQL
 --with-libgit2=PATH     enable git support via libgit2

Passing a --without- argument will prevent mmm from being built with that particular dependency.

Installation

To install mmm, simply check-out the sources, and do a standard ./configure && make && make install.

Alternatively, you can also run the automated tests, and generate a coverage report.

  • To run the tests: make check
  • To generate a coverage report: make clean coverage
  • To uninstall: make uninstall

If you have issues running ./configure, run ./autogen.sh and try again.

Configuration File

The configuration file is a typical ini-style configuration file, See the default file generated by mmm init for an explanation of the options, although they should be self-explanatory.

Database Drivers

Three database drivers are available: sqlite3, pgsql and mysql, and are usable assuming the aforementioned dependencies are available.

For sqlite3 only the db option need be specified, and it should be the path to the SQLite3 database to use.

For pgsql and mysql all other options should also be specified. To use a UNIX socket with these two, set the host option to the path to the socket, and port to 0. The client character set will default to UTF-8.

With mysql defaults will be read from the mysql section of the config file for any unspecified parameters.

Migration Files

The migration files are plain SQL files, split into two sections like so:

-- [up]
CREATE TABLE test(id INTEGER NOT NULL);

-- [down]
DROP TABLE test;
  • The up section contains the SQL queries to run when applying a migration.
  • The down section contains the SQL queries to run when rolling back a migration.

They can be specified in either order.

Sources

Two sources are currently supported: file and git.

The file source looks at the files in the specified migration_path in order to determine the order that the files should be applied. This source assumes that all migrations begin with a numeric designation, for example: 1-init.sql; and will be arranged in numerical order. This is the default source. Revisions correspond to the files' designations. The seed file will be added as revision "0", thus migrations must start from 1.

The git source uses a git repository for determining the order in which migrations should be applied. With this source, the files need not have a numeric designation, and they will be applied in the order in which they were committed to the repository. Revisions correspond to the actual SHA1 hash for the commit at which the current set of migrations was performed.

The git source requires libgit2.

Caveats

mmm uses transactions to ensure that if an error occurs, the database is returned to a known state. However, not all RDMBS support transactional DDL (Data Definition Language) statements, and therefore mmm cannot guarantee that databases on these RDBMS systems will be in the desired state when rolling back the transaction.

If an error occurs, and your database lacks transactional DDL support, mmm will emit an error message advising you of the situation. In these cases, you will need to manually verify that your schema is correct.

In case of upgrading the schema, mmm will automatically roll back any applied migrations in the current batch when an error occurs if the RDBMS lacks transactional DDL support.

MySQL

MySQL is supported, although you should be aware that any DDL commands will cause an implicit commit. Thus, when writing migrations, you should use IF [NOT] EXISTS on your CREATE and DROP statements to ensure that migrations can still run if, for example, and added table could not be successfully dropped on rollback.