# 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:

```python
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
```

```python
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:

```python
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.")
```

```python
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:

```text
Found 1 active users.
```

Every ORM call runs inside `async with engines.session():`; see [Sessions](<https://ferro-orm.x54.sh/guide/connections/#sessions>). `auto_migrate=True` creates the table on connect, which suits development and tests.

## Where to go next

- [Installation](<https://ferro-orm.x54.sh/getting-started/installation/index.md>) covers Python versions, extras and building from source.
- [Quickstart](<https://ferro-orm.x54.sh/getting-started/quickstart/index.md>) builds a small blog backend with models, queries, relationships and transactions.
- [Why Ferro](<https://ferro-orm.x54.sh/why-ferro/index.md>) compares Ferro with SQLAlchemy, Django ORM and Tortoise, and lists the trade-offs.
- [Schema management](<https://ferro-orm.x54.sh/guide/schema/overview/index.md>) explains auto-migrate and `ferro migrate`.
- [Models and fields](<https://ferro-orm.x54.sh/guide/models-and-fields/index.md>), [Queries](<https://ferro-orm.x54.sh/guide/queries/index.md>) and [Relationships](<https://ferro-orm.x54.sh/guide/relationships/index.md>) are the main guides.
- [How-to guides](<https://ferro-orm.x54.sh/howto/testing/index.md>) hold recipes for testing, pagination, timestamps, soft deletes and multiple databases.
- [API reference](<https://ferro-orm.x54.sh/api/model/index.md>) lists every public class and method.
- [Roadmap](<https://ferro-orm.x54.sh/roadmap/index.md>) lists the features that are not implemented yet.