larzmigrate

Schema migrations for SQL and larzdb. Pure Python, zero dependencies.

Evolve a schema safely: write ordered migrations with an up and an optional down, and larzmigrate applies the pending ones in order, records what it did, and can roll back — against any DB-API connection (sqlite3, psycopg2, …) or a larzdb database.

import sqlite3
from larzmigrate import Migrator, SQLBackend

m = Migrator(SQLBackend(sqlite3.connect("app.db")))

m.add_sql("001_users",
          up="CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)",
          down="DROP TABLE users")

@m.migration("002_seed")
def seed(conn):
    conn.execute("INSERT INTO users (name) VALUES ('admin')")

m.migrate()        # apply everything pending, in order (idempotent)
m.rollback()       # undo the most recent migration
m.status()         # [("001_users", "applied"), ("002_seed", "applied")]

What makes it different

• Storage-agnostic. The same migrator drives a SQL database (via any DB-API connection) or a larzdb / key-value store — pick the backend, write your migrations once.
• Detects edited migrations. Every migration is checksummed. If one that's already applied gets changed, migrate() errors (checksum drift) instead of silently diverging from what actually ran — the bug that bites teams.
• Real rollback. down migrations run in reverse; rollback(steps=N) undoes the last N.
• Idempotent. Re-running only applies what's pending; safe to run on every deploy.
• Zero dependencies. No Alembic, no ORM.

Install

pip install larzmigrate

Backends

from larzmigrate import Migrator, SQLBackend, KVBackend, DictStore

# SQL: any DB-API connection (sqlite3, psycopg2, MySQLdb, ...)
Migrator(SQLBackend(connection))

# larzdb or any get/put store
Migrator(KVBackend(larzdb_database))
Migrator(KVBackend(DictStore()))     # in-memory

Function migrations receive the backend's context — the DB connection (SQL) or the store (KV) — so they can do whatever that backend allows.

Commands

m.migrate()                  # apply all pending
m.migrate(target="003_x")    # apply up to (and including) an id
m.rollback()                 # undo the most recent
m.rollback(steps=3)          # undo the last 3
m.status()                   # [(id, "applied"|"pending"), ...]
m.pending(); m.applied()

Tests

python -m unittest discover -s tests -v   # 13 tests incl. real sqlite3 + drift

The Larz stack

Pure-Python, zero-dependency building blocks: larz · larzchain · larzmoney · larzcrypt · larzdb · larzagent · larzchart · larzmark · larztask · larzvault · larzvm · larzcache · larzvalidate · larzid · larzrpc · larzstate · larzhttp · larzconf · larzcron · larzlimit · larzlog · larzcli · larzretry · larztime · larzpdf · larzpack · larztemplate · larzcolor · larztable · larzjson · larzbus · larzmigrate

License

MIT © larz-scripter