Database

Engine

By default, AI Runner uses an SQLite database, located at ~/local/share/.airunner on Linux.

To use a different database, set the AI_RUNNER_DATABASE_URL and ASYNC_AI_RUNNER_DATABASE_URL environment variables.

Example (PostgreSQL with psycopg2)

export AI_RUNNER_DATABASE_URL="postgresql+psycopg2://user:password@hostname/database_name"

These URLs follow SQLAlchemy's database URL format.

Advanced Database Features

Supported Engines

• SQLite: Default database engine, located at ~/.local/share/.airunner on Linux.
• PostgreSQL: Supported via AI_RUNNER_DATABASE_URL and ASYNC_AI_RUNNER_DATABASE_URL environment variables.

Environment Variables

• AI_RUNNER_DATABASE_URL: SQLAlchemy connection string for the primary database.
• ASYNC_AI_RUNNER_DATABASE_URL: Connection string for asynchronous database operations.

Migrations

• AI Runner uses Alembic for database migrations.
• CRITICAL: Always use -c src/airunner/alembic.ini flag to specify the config file path.
• To generate migrations, use the airunner-generate-migration command or run alembic directly:

  # Recommended: Use the CLI tool
  airunner-generate-migration "Migration message"
  
  # Or run alembic directly from project root
  alembic -c src/airunner/alembic.ini revision --autogenerate -m "Migration message"

• Apply migrations manually with:

  alembic -c src/airunner/alembic.ini upgrade head

• Downgrade one revision:

  alembic -c src/airunner/alembic.ini downgrade -1

Models

Advanced ORM Features

• Models are defined in src/airunner/data/models/ and inherit from the Base class.
• Example:

  from airunner.data.models.base import Base
  class ExampleModel(Base):
      ...

Migrations

When modifying models, database migrations must be generated and applied.

AI Runner uses Alembic to manage migrations.

CRITICAL: Always use -c src/airunner/alembic.ini flag when running alembic commands.

To generate migrations with the autogenerate flag, you can use the CLI tool or run alembic directly from the project root:

Example:

# Recommended: Use the CLI tool
airunner-generate-migration "Add use_grid_image_as_input and lock_input_image to OutpaintSettings"

# Or run alembic directly from project root
cd /path/to/airunner  # Go to project root
alembic -c src/airunner/alembic.ini revision --autogenerate -m "Add use_grid_image_as_input and lock_input_image to OutpaintSettings"

The generated migration will include upgrade and downgrade functions reflecting the changes in your models. However, manual edits may be required to add database inspections and exception handling. Refer to existing migrations for best practices.

We do not use alembic or sqlalchemy directly. See src/airunner/utils/db

Example

This example migration that adds multiple columns on upgrade and removes them on downgrade.

"""add nodegraph settings

Revision ID: 904f01f8f439
Revises: 1a9e7c2de7c9
Create Date: 2025-05-17 06:08:53.850366

"""

from typing import Sequence, Union

from airunner.data.models.application_settings import ApplicationSettings
from airunner.utils.db import add_column, drop_column

# revision identifiers, used by Alembic.
revision: str = "904f01f8f439"
down_revision: Union[str, None] = "1a9e7c2de7c9"
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None


def upgrade() -> None:
    add_column(ApplicationSettings, "nodegraph_zoom")
    add_column(ApplicationSettings, "nodegraph_center_x")
    add_column(ApplicationSettings, "nodegraph_center_y")


def downgrade() -> None:
    drop_column(ApplicationSettings, "nodegraph_zoom")
    drop_column(ApplicationSettings, "nodegraph_center_x")
    drop_column(ApplicationSettings, "nodegraph_center_y")

Applying Migrations

When running airunner, migrations will be applied automatically. You can also run them manually:

# From project root
alembic -c src/airunner/alembic.ini upgrade head

# Downgrade one revision
alembic -c src/airunner/alembic.ini downgrade -1

For more details on Alembic commands, see Alembic's documentation.