MySQL/MariaDB schema migration tool for Python
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


pip install migration-sql

Library structure

The library is composed mainly of 2 classes DB, Version and method migrate():

  • DB: represents a database connection. To create this object, you need to provide the database host, port, username, password and database name.

  • Version: represents a migration version that will be run and recorded in the database when the migration is applied successfully. It has the version_code which needs to be unique, a comment that is usually migration purpose and sql_text which is the SQL query that will be applied to the database or sql_file that points to the sql file that you want to run.

  • migrate(versions, dbs): this method will apply all necessary versions on all databases listed in dbs. To avoid discrepancies between databases, if the migration fails on any of the database the whole migration process will be aborted and the database will stay intact.

How to use

Here is a code snippet on how to apply migrations on a database

from migration_sql import DB, Version, migrate

all_versions = [
    Version("v0", "dumb query works", "select 1"),
    Version("v1", "create a table", """
  `name` varchar(100) NOT NULL,
  PRIMARY KEY (`id`)
    Version("v2", "the migration script can come from a file too", sql_file="examples/v2.sql"),
    Version("v3", "the migration is not limited to DDL, DML is also OK!", sql_text="""
INSERT INTO `user` (`id`, `name`) VALUES ('1', 'John Wick');

dbs = [
    DB("", 3306, "root", "root", "my_database")

migrate(all_versions, dbs)


To run all the tests:

cd tests/; ./

To install locally the library during development

First, uninstall migration-sql

pip uninstall migration-sql

Then install it on local

python install

Or symlink it

python develop

Build and upload to pypi