Skip to main content

Caribou is a simple SQLite database migrations library, built

Project description

Caribou SQLite Migrations

Caribou

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 db.sqlite .
upgrading db [db.sqlite] to most recent version
upgraded [db.sqlite] successfully to version [20091115140758]

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

$ caribou downgrade db.sqlite . 0
downgrading db [db.sqlite] to version [0]
downgraded [db.sqlite] 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 = 'db.sqlite'
migrations_dir = '/path/to/migrations/dir'
version = '20091115140758'

# upgrade to most recent version
caribou.upgrade(db, migrations_dir)

# upgrade to a specific version
caribou.upgrade(db, migrations_dir, version)

# downgrade to a specific version
caribou.downgrade(db, migrations_dir, version)

That's it. You're rolling.

Installation

pip install caribou

Licence

Caribou is in the public domain.

Development

Things to know, before you start hacking Caribou:

Unit Tests

The unit test suite uses pytest and tox. To install and run:

pip install tox pytest
tox

Appendix

Haven't got enough?

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

caribou-0.4.1.tar.gz (14.0 kB view details)

Uploaded Source

Built Distribution

caribou-0.4.1-py2.py3-none-any.whl (7.2 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file caribou-0.4.1.tar.gz.

File metadata

  • Download URL: caribou-0.4.1.tar.gz
  • Upload date:
  • Size: 14.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.32.3

File hashes

Hashes for caribou-0.4.1.tar.gz
Algorithm Hash digest
SHA256 13a66fc9ef9b1c9e9ef220876d59a44ee5eff9e579655252271b7514fc0ad787
MD5 cffb9f2bc3d5ba7094e0878090ddc7df
BLAKE2b-256 6c74de2c20c5a24811d69a2a6150d5cd841f2af21ffc65ff964a73f46738bb68

See more details on using hashes here.

File details

Details for the file caribou-0.4.1-py2.py3-none-any.whl.

File metadata

  • Download URL: caribou-0.4.1-py2.py3-none-any.whl
  • Upload date:
  • Size: 7.2 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.32.3

File hashes

Hashes for caribou-0.4.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 5c7a036584b34021011f1512620152272924e55ca87c7c805073aeef31c5baed
MD5 472da6314bf4c4c4b9570e66ebeaf3ba
BLAKE2b-256 b591795eccdad6abd41b3634502d0971cb696d2e5c9cede67f8b38ebe30d2b1e

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page