Yoyo Migrations

9.0.0 · active · verified Sun Apr 12

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.

Warnings

breaking Yoyo 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.
breaking In 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.
gotcha Yoyo 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.
gotcha Migration 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.
gotcha While 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`.

Install

pip install yoyo-migrations Basic Installation
pip install yoyo-migrations[psycopg2-binary] PostgreSQL Driver Example
pip install yoyo-migrations[mysqlclient] MySQL Driver Example

Imports

get_migrations
```
from yoyo import get_migrations
```
connect
```
from yoyo.connections import connect
```
Migration
```
from yoyo.migrations import Migration
```

Quickstart

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())

view raw JSON →