Registry / database / yoyo-migrations

yoyo-migrations

JSON →
library9.0.0pypypi✓ verified 21d ago

Yoyo Migrations is a robust, database-agnostic migration tool for Python projects, enabling users to manage SQL-based schema changes. It supports various database systems with both synchronous and asynchronous drivers. Currently at version 9.0.0, it maintains an active release cadence, introducing new features and refining API usability while periodically updating Python version support.

pip install yoyo-migrations
INSTALL
IMPORT
SIG · YOYO-MIGRATIONS
Y
yoyo-migrations
databasepythonv9.0.0
Install
1.8s avg
Import
163ms
Disk
17MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v9.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.915 runs
installs and imports cleanly · install 0.0s · import 0.169s · 19.2MB
glibc
py 3.103.915 runs
installs and imports cleanly · install 1.8s · import 0.157s · 20MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

get_backend
from yoyo import get_backend
from yoyo import get_migrations
read_migrations
from yoyo import read_migrations
step
from yoyo import step

This quickstart demonstrates how to programmatically apply Yoyo migrations using a temporary SQLite in-memory database and dynamically created migration files. It connects to the database, reads migrations from a specified directory, applies them, and then prints the updated table schema before cleaning up. Note the use of `await` for async database operations, a common pattern in Yoyo 9.x.

import asyncio import os from pathlib import Path from yoyo import get_migrations from yoyo.connections import connect # Create a temporary directory for migrations TEMP_MIGRATIONS_DIR = Path('./temp_yoyo_migrations_quickstart') TEMP_MIGRATIONS_DIR.mkdir(exist_ok=True) # Create dummy migration files (TEMP_MIGRATIONS_DIR / '0001.create_table.sql').write_text( 'CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT);' ) (TEMP_MIGRATIONS_DIR / '0002.add_email_field.sql').write_text( 'ALTER TABLE users ADD COLUMN email TEXT;' ) # Use an in-memory SQLite database for the example DB_URI = "sqlite:///:memory:" async def run_yoyo_programmatically(): print(f"Connecting to database: {DB_URI}") backend = await connect(DB_URI) try: migrations = get_migrations(TEMP_MIGRATIONS_DIR) print(f"Found {len(migrations)} migrations in {TEMP_MIGRATIONS_DIR}") with backend.transaction(): to_apply = backend.to_apply(migrations) if to_apply: applied_migrations = await backend.apply_migrations(to_apply) print(f"Successfully applied {len(applied_migrations)} migrations.") else: print("No new migrations to apply.") # Example of checking current schema (simplified) cursor = await backend.cursor() await cursor.execute("PRAGMA table_info(users);") schema = await cursor.fetchall() print("Current 'users' table schema:") for col in schema: print(f" - {col[1]} ({col[2]})") # col[1]=name, col[2]=type await cursor.close() finally: await backend.close() # Clean up temporary migration files and directory for f in TEMP_MIGRATIONS_DIR.iterdir(): f.unlink() TEMP_MIGRATIONS_DIR.rmdir() if __name__ == '__main__': asyncio.run(run_yoyo_programmatically())
yoyo --version
Debug
Known issues
breakingYoyo 9.0.0 dropped support for Python 3.5 and 3.6. Users must be on Python 3.7 or newer to use Yoyo 9.x.
fix
Upgrade your Python environment to 3.7 or a newer version.
affects: 9.0.0+
breakingIn Yoyo 9.0.0, the database connection parameters changed from multiple `dbapi`-style arguments (e.g., `host='localhost', user='user'`) to a single URL connection string (e.g., `postgresql://user:password@host/dbname`).
fix
Refactor database connection calls to use a single connection string URL. Consult the Yoyo documentation for correct URL formats for your specific database.
affects: 9.0.0+
gotchaYoyo 9.0.0 introduced extensive `asyncio` support. The `yoyo.connections.connect()` function now returns an `AsyncConnection` object if an async driver is detected, requiring all subsequent database operations (e.g., `apply_migrations`, `cursor().execute()`) to be `await`ed. For sync drivers, it returns a `SyncConnection` and no `await` is needed.
fix
Be mindful of your chosen database driver. If using an async driver (e.g., `asyncpg`), ensure all `yoyo.connections.connect()` and `backend` object methods are called with `await` within an `async` function. If using a sync driver (e.g., `psycopg2-binary`), `await` is not necessary but using `asyncio.run` to call the main function that wraps `connect` is still fine.
affects: 9.0.0+
gotchaMigration files (SQL or Python scripts) should ideally be idempotent or carefully managed to avoid issues during re-application or rollbacks. If a migration is not idempotent, re-running it on an already migrated database could lead to errors.
fix
Design migration scripts to handle existing states gracefully (e.g., `CREATE TABLE IF NOT EXISTS`, `ALTER TABLE ... ADD COLUMN ... IF NOT EXISTS`). Test your migrations thoroughly in environments resembling production before deployment.
affects: All
gotchaWhile Yoyo has a programmatic API, its primary interface is the CLI, which relies on a `yoyo.ini` configuration file and a dedicated `migrations` directory. Programmatic usage requires explicitly passing migration directories and connection details, as `yoyo.ini` is not automatically picked up.
fix
For CLI usage, always ensure `yoyo.ini` is correctly configured and located. For programmatic integration, explicitly provide the `migrations` directory path to `get_migrations()` and the database URI to `connect()`, managing configuration outside of `yoyo.ini`.
affects: All
Upgrade
Version history
9.0.0latest on PyPI · released Aug 10, 2024
Audit
Dependencies
psycopg2-binaryoptionalOptional: PostgreSQL driver for synchronous connections.
asyncpgoptionalOptional: PostgreSQL driver for asynchronous connections.
mysqlclientoptionalOptional: MySQL/MariaDB driver for synchronous connections.
Agent activity
60 hits · last 30 days
node
54
OpenAI (training)
1
Resources