ztwilliam / caribou

A small, simple Python migrations library for SQLite databases.

Caribou SQLite Migrations

Caribou is a small, simple SQLite database migrations library for Python, built primarily to manage the evoluton of client side databases over multiple releases of an application.

Example

Here is a simple example illustrating how to use Caribou to manage your SQLite schema:

Create a Migration

Use Caribou's command line tool to create your first migration:

$ caribou create my_first_migration
created migration ./20091115140758_my_first_migration.py

Edit Your Migration

Let's create a table with some data in the upgrade step and reverse the changes in the downgrade step.

"""
An example of a Caribou migration file.
"""

def upgrade(connection):
    # connection is a plain old sqlite3 database connection
    sql = """
        create table animals
        ( name     TEXT
        , status   TEXT
        ) """
    connection.execute(sql)
    
    animals = [ ('caribou', 'least concerned')
              , ('bengal tiger', 'threatened')
              , ('eastern elk', 'extinct')
              ]
    sql = 'insert into animals values (:1, :2)'
    for name, status in animals:
        connection.execute(sql, [name, status])

    connection.commit()

def downgrade(connection):
    connection.execute('drop table animals')

Caribou migrations are flexible because they are plain Python files. Feel free to add logging, DDL transactions, anything at all.

Run Your Migration:

Caribou migrations can be run with the command line tool:

$ caribou upgrade my_sqlite_db .
upgrading db [my_sqlite_db] to most recent version
upgraded [my_sqlite_db] successfully to version [20091115140758]

# if you want to revert your changes, uses the downgrade command:

$ caribou downgrade my_sqlite_db . 0
downgrading db [my_sqlite_db] to version [0]
downgraded [my_sqlite_db] successfully to version [0]

Since Caribou is built to manage client side sqlite databases, it can also be run programmatically from within your application:

"""
An example illustrating how to run a migration programmatically.
"""

import caribou

db_path = 'my_sqlite_db' 
migrations_path = '/path/to/migrations/dir'
version = '20091115140758'

# upgrade to most recent version
caribou.upgrade(db_path, migrations_path)

# upgrade to a specific version
caribou.upgrade(db_path, migrations_path, version)

# downgrade to a specific version
caribou.downgrade(db_path, migrations_path, version)

That's it. You're rolling.

Installation

using setuptools:

sudo easy_install caribou

or, download and extract the most code in the repo, and run:

sudo python setup.py install

Licence

Caribou is in the public domain.

Development

Things to know, before you start hacking Caribou:

Unit Tests

The unit test suite requires the nose unit testing library. To install:

sudo easy_install nose

To execute the test suite, run:

python setup.py nosetests

or simply:

nosetests

Appendix

Haven't got enough?

• Additional Reading
• Additional Listening