migratore

Simple migration framework / infra-structure for SQL-based databases.

Installation

pip install migratore

Execution

HOST=${HOST} DB=${DB_NAME} USERNAME=${DB_USER} PASSWORD=${DB_PASS} migratore upgrade

Variables

HOST - Hostname or IP address of the database system for migration
PORT - TCP port to be used in the connection with the database system
UNIX_SOCKET - Filesystem path to the UNIX socket file to be used in connection
DB - Name of the database used as the migration target
USERNAME - Username for authentication in the database
PASSWORD - Password to be used for authentication in the database
FS - Base file system path for file migration (may depend on migration context)
DB_URL - The database connection URL following the format protocol://username:password@host:port/db
SAFE - If the migration operation should be performed in a safe manner.

Commands

help - Prints a help message about the CLI interface
version - Prints the current version of migratore
environ - Displays the current environment in the standard output
list - Lists the executed migrations on the current database
errors - Lists the various errors from migration of the database
mark [path] - Marks all pending migrations as applied using the defined directory or current
trace [id] - Prints the traceback for the error execution with the provided id
rebuild [id] - Run the partial execution of the migration with the given id
touch [id] - Touches a migration file updating its timestamp to the current time
squash [start] [end] <output> - Combines multiple migrations into a single file
upgrade [path] - Executes the pending migrations using the defined directory or current
dry_upgrade [path] - Prints the pending migrations without executing them
downgrade [path] - Rolls back the last applied migration using the defined directory or current
dry_downgrade [path] - Prints the last applied migration without rolling it back
skip [path] - Skips the current migration (next to be run) using the defined directory or current
generate [path] - Generates a new migration file into the target path

Operations

Every command that touches a migration records a row in the migratore bookkeeping table with an operation value that describes what was done. The same migration can have multiple rows over time (e.g. a Run followed later by a Rollback). The most recent row for each UUID is what determines whether the migration is currently applied.

Run - Normal application of a migration through upgrade. Invokes Migration.run.
Run Partial - Re-execution of a single migration through rebuild [id]. Invokes Migration.run_partial, useful for resuming a migration that previously failed mid-way.
Run Skip - Records the migration as applied through skip without executing its run body. Invokes Migration.run_skip. Handy when adopting migratore on a database that already has the target schema, or when a migration has been applied out-of-band.
Rollback - Explicit downgrade through downgrade, or recovery rollback automatically triggered when a run fails (when SAFE is False). Invokes Migration.rollback. The force argument distinguishes the two cases: True for an explicit downgrade, False for recovery.

A migration is considered currently applied whenever the most recent successful row for its UUID is anything other than Rollback. This means a migration that was rolled back via downgrade becomes pending again and will be re-applied by the next upgrade.

Examples

database = Migratore.get_database()
table = database.get_table("users")
table.add_column("username", type = "text")

License

Migratore is currently licensed under the Apache License, Version 2.0.

Build Automation

Metadata

Release files for migratore 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for migratore 0.11.0
File	Size	Uploaded
migratore-0.11.0.tar.gz	20.8 kB	Oct 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for migratore 0.11.0
File	Interpreter	ABI	Platform	Reset
migratore-0.11.0-py2.py3-none-any.whl 22.8 kB Oct 9, 2026	Python 2, Python 3	none	any	Details

Total release size: 43.6 kB

Release files / migratore-0.11.0.tar.gz

Download URL	migratore-0.11.0.tar.gz
Size	20.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`32d2bc93cd9adf0552b480561804f4a9aefe91b81e95f59048b670cb7af3e30f`
BLAKE2b-256 checksum How to use checksums	`ce6cce9aecdd461166fd660bcb5c9c675554a52ed168a9bd4cefa885370dd424`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.17`

Release files / migratore-0.11.0-py2.py3-none-any.whl

Download URL	migratore-0.11.0-py2.py3-none-any.whl
Size	22.8 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`203937f2164a013ffe0d9e203dcd47f021088c4e505a699800a56fc8dc682599`
BLAKE2b-256 checksum How to use checksums	`9a7cd94e2a0674ee0f3264cee98c6ebf62dbc0c130171443c0fca5a044951ad8`
Upload date	Oct 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.17`