Skip to content

Quick start

This guide takes you from an empty file to a working async app: define models, create the schema, run queries and traverse relations. It works the same on PostgreSQL and SQLite — only the connection URL changes.

1. Install

pip install yara-orm

See Installation for platform details.

2. Define models

from yara_orm import Model, fields


class Author(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=120, index=True)
    created_at = fields.DatetimeField(auto_now_add=True)


class Book(Model):
    id = fields.IntField(pk=True)
    title = fields.CharField(max_length=200)
    rating = fields.DecimalField(max_digits=3, decimal_places=1, default=0)
    author = fields.ForeignKeyField("Author", related_name="books")

3. Connect and create the schema

Pick a backend by URL — the rest of your code is identical.

from yara_orm import YaraOrm

await YaraOrm.init("postgres://user:pass@localhost/app")
await YaraOrm.generate_schemas()

from yara_orm import YaraOrm

await YaraOrm.init("sqlite:///app.db")
await YaraOrm.generate_schemas()

Note

generate_schemas() is convenient for getting started and for tests. For evolving a real schema over time, use Migrations.

4. Create and query

# Insert
ada = await Author.create(name="Ada Lovelace")
await Book.create(title="Notes on the Analytical Engine", rating=5, author=ada)

# Lazy, chainable queries — they run when awaited
books = await Book.filter(rating__gte=4).order_by("-rating").limit(10)
how_many = await Book.filter(author=ada).count()

# Fetch one (raises DoesNotExist if missing)
ada = await Author.get(name="Ada Lovelace")
maybe = await Author.get_or_none(name="Nobody")   # -> None

5. Traverse relations

# Forward foreign key (awaitable)
book = await Book.get(title="Notes on the Analytical Engine")
author = await book.author
print(author.name)

# Reverse manager (from related_name="books")
async for book in ada.books:
    print(book.title)

# Avoid N+1 with prefetch
for author in await Author.all().prefetch_related("books"):
    print(author.name, len(await author.books))

6. Put it together

import asyncio
from yara_orm import Model, YaraOrm, fields


class Author(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=120, index=True)


class Book(Model):
    id = fields.IntField(pk=True)
    title = fields.CharField(max_length=200)
    author = fields.ForeignKeyField("Author", related_name="books")


async def main() -> None:
    await YaraOrm.init("sqlite:///app.db")
    await YaraOrm.generate_schemas()

    ada = await Author.create(name="Ada Lovelace")
    await Book.create(title="Notes", author=ada)

    async for book in ada.books:
        print(book.title, "→", (await book.author).name)

    await YaraOrm.close()


asyncio.run(main())

Next steps