Skip to content
A small, simple Python migrations library for SQLite databases.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

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.


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 ./

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
        ) """
    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])


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.


using setuptools:

sudo easy_install caribou

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

sudo python install


Caribou is in the public domain.


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 nosetests

or simply:



Haven't got enough?

You can’t perform that action at this time.