Alembic Integration

Alembic Integration

Plugins can bring their own database tables with Alembic migration scripts. Alembic is an optional dependency: install it (with SQLAlchemy) separately when you need this integration.

pip install pluginforge alembic sqlalchemy

Note: the pluginforge[alembic] extra existed pre-v0.6.0 but was non-functional (it referenced dependencies that were never declared as optional). It was removed in v0.6.0.

Plugin Migrations

Plugins declare their migrations directory by overriding get_migrations_dir():

from pathlib import Path
from pluginforge import BasePlugin

class StoragePlugin(BasePlugin):
    name = "storage"

    def get_migrations_dir(self) -> str | None:
        return str(Path(__file__).parent / "migrations")

Collecting Migrations

The PluginManager collects all migration directories from active plugins:

pm = PluginManager("config/app.yaml")
pm.discover_plugins()

migrations = pm.collect_migrations()
# {"storage": "/path/to/storage/migrations", "analytics": "/path/to/analytics/migrations"}

Integration with Alembic

Use the collected directories in your Alembic env.py to run migrations from all plugins.

Error Handling

• Plugins that return None from get_migrations_dir() are skipped
• Non-existent directories are logged as warnings and skipped