Database Setup

AuthFort uses SQLAlchemy and supports any SQL database with an async driver.

Connection Strings

PostgreSQL

auth = AuthFort(
    database_url="postgresql+asyncpg://user:pass@localhost:5432/mydb",
)

auth = AuthFort(
    database_url="postgresql+asyncpg://user:pass@localhost:5432/mydb",
)

Requires: pip install authfort (asyncpg is included).

SQLite

auth = AuthFort(
    database_url="sqlite+aiosqlite:///auth.db",
)

auth = AuthFort(
    database_url="sqlite+aiosqlite:///auth.db",
)

Requires: pip install authfort[sqlite]

SQLite is great for development and small deployments. The database file is created automatically.

MySQL

auth = AuthFort(
    database_url="mysql+aiomysql://user:pass@localhost:3306/mydb",
)

auth = AuthFort(
    database_url="mysql+aiomysql://user:pass@localhost:3306/mydb",
)

Requires: pip install authfort[mysql]

Migrations

AuthFort includes bundled Alembic migrations. Run them via the CLI before starting your app:

Terminal

authfort migrate --database-url "postgresql+asyncpg://user:pass@localhost:5432/mydb"

authfort migrate --database-url "postgresql+asyncpg://user:pass@localhost:5432/mydb"

The command is idempotent — it only runs pending migrations. Run it once on setup and again after upgrading AuthFort.

# Alternative: run migrations programmatically (e.g. in tests)
await auth.migrate()

# Alternative: run migrations programmatically (e.g. in tests)
await auth.migrate()

All AuthFort tables are prefixed with authfort_ to avoid conflicts with your application’s tables:

• authfort_users
• authfort_accounts
• authfort_refresh_tokens
• authfort_user_roles
• authfort_signing_keys
• authfort_verification_tokens
• authfort_alembic_version

Sharing a Database

If your application uses the same database, AuthFort’s tables coexist with yours. Two helpers make this seamless:

• register_foreign_tables(metadata) — registers stub tables so your models can ForeignKey("authfort_users.id")
• alembic_filters() — prevents Alembic from generating migrations for AuthFort’s tables

your_app/alembic/env.py

from authfort import alembic_filters, register_foreign_tables
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

# Register AuthFort table stubs so your models can FK to authfort_users
register_foreign_tables(Base.metadata)

target_metadata = Base.metadata

def run_migrations_online():
    # ...
    context.configure(
        connection=connection,
        target_metadata=target_metadata,
        **alembic_filters(),  # Skip authfort_* tables
    )

from authfort import alembic_filters, register_foreign_tables
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

# Register AuthFort table stubs so your models can FK to authfort_users
register_foreign_tables(Base.metadata)

target_metadata = Base.metadata

def run_migrations_online():
    # ...
    context.configure(
        connection=connection,
        target_metadata=target_metadata,
        **alembic_filters(),  # Skip authfort_* tables
    )

alembic_filters() returns both include_name and include_object filters, so Alembic won’t try to create, modify, or drop any authfort_* tables.

Separate Database

For production, you may want AuthFort on its own database. Just use a different connection string:

# Your app
app_engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/myapp")

# AuthFort — separate database
auth = AuthFort(
    database_url="postgresql+asyncpg://user:pass@localhost/auth_db",
)

# Your app
app_engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/myapp")

# AuthFort — separate database
auth = AuthFort(
    database_url="postgresql+asyncpg://user:pass@localhost/auth_db",
)

Disposing the Engine

Call auth.dispose() when your application exits to clean up database connections.