README.md

Roetsjbaan

Intro

Roetsjbaan (pronounced "rootshbahn") is a minimal, lightweight migration script library. It's completely database agnostic - in fact, it doesn't implement any database operations at all. It just allows you to execute and undo changes to, well, anything.

Installation

Use pip to install roetsjbaan:

pip install roetsjbaan

After installation, the roetsj command should be available from your project's root.

Initial configuration

The roetsj command won't do anything unless you create roetsjfile.py in the root of your project. A minimal roetsjfile looks like this:

import roetsjbaan
versioner = roetsjbaan.FileVersioner(path='.roetsj-version')

The most important thing here is the versioner. The versioner tells roetsjbaan what the current version is. Nothing less, nothing more! Any Python object with a .get() method returning a version and a .set(value) method should do.

Note that you don't need to have a clue about what a version should look like - just remember they're strings.

A more complete roetsjfile that configures roetsjbaan for database migrations using a made-up database library could look something like this:

import roetsjbaan
import mydblib # generic non-existing database library

class MyVersioner:
    def __init__(self, database):
        self.database = database

    def get(self):
        return mydblib.query('''
            select version
            from migration
            order by date desc
            limit 1
        ''')

    def set(self, version):
        mydblib.execute('insert into migration(version) values ($1)', version)

database = mydblib.Connection()

versioner = MyVersioner()
directory = 'database/migrations'
inject = {
    'database': database
}

There are two new configuration variables defined in this file:

• directory: simply tells roetsjbaan where to find existing migrations and place new ones;
• inject: a dictionary containing values that will be injected into the migrations, which allows them to access these values.

Usage

Creating a migration

To create a new migration, run roetsj new "Yay, my first migration script". If everything went right, you should now have a file called something like 1430128129_3a561200_yay_my_first_migration_script.py in the migrations folder specified in your roetsjfile. If you open it up, it'll look like this:

description = 'Yay, my first migration script'
hash = '3a5612009c5d2df8f3c04091b2695f809630f790'
issue = 'None'

def up():
    pass

def down():
    pass

The file contains the following by default:

• hash: basically the migration version. Don't change this - it's automatically generated by roetsjbaan. Don't worry, you'll never have to enter the whole hash anywhere.
• issue: an optional issue number related to the migration (Github issue, ...). You can set this immediately with the --issue option
• up: the function that will contain all of your changes
• down: the function that can roll back the changes in up

If you've added something to your inject dict like in the example above, you can add it as a parameter in the up or down functions, like so:

def up(database):
    # funky database operations...
    pass

Operations

The roetsj command contains the following sub-commands:

• new: creates a new migration (see Creating a migration)
• list: shows all migrations and marks the current version
• up: execute all non-executed migrations
• down: roll back the last migration
• set: sets the current version without executing any migrations. Use this for debugging purposes only.

For detailed help, run roets <command> -h