Ferro ORM¶

Ferro is an async ORM for Python: you declare Pydantic models, and a Rust engine builds the SQL, runs it and turns rows into model instances. Its runtime dependencies are Pydantic and pydantic-settings.

Declare a model once. The two tabs show the same model in Ferro's two equivalent field-declaration styles:

from ferro import Field, Model, connect, engines


class User(Model):
    id: int | None = Field(default=None, primary_key=True)
    username: str
    is_active: bool = True

from ferro import Field, Model, connect, engines


class User(Model):
    id: Annotated[int | None, Field(primary_key=True)] = None
    username: str
    is_active: bool = True

Connect, open a session, create two users and query the active ones:

await connect("sqlite::memory:", auto_migrate=True)

async with engines.session():
    await User.create(username="alice")
    await User.create(username="bob", is_active=False)

    active_users = await User.where(lambda user: user.is_active == True).all()
    print(f"Found {len(active_users)} active users.")

await connect("sqlite::memory:", auto_migrate=True)

async with engines.session():
    await User.create(username="alice")
    await User.create(username="bob", is_active=False)

    active_users = await User.where(lambda user: user.is_active == True).all()
    print(f"Found {len(active_users)} active users.")

Only alice is active, so the script prints:

Found 1 active users.

Every ORM call runs inside async with engines.session():; see Sessions. auto_migrate=True creates the table on connect, which suits development and tests.

Where to go next¶

• Installation covers Python versions, extras and building from source.
• Quickstart builds a small blog backend with models, queries, relationships and transactions.
• Why Ferro compares Ferro with SQLAlchemy, Django ORM and Tortoise, and lists the trade-offs.
• Schema management explains auto-migrate and ferro migrate.
• Models and fields, Queries and Relationships are the main guides.
• How-to guides hold recipes for testing, pagination, timestamps, soft deletes and multiple databases.
• API reference lists every public class and method.
• Roadmap lists the features that are not implemented yet.