The ORM

This is the v1.0 documentation, for a release that is still in development. The API it describes is not on PyPI and can still change.

Reading about the version you have installed? Switch to v0.x.

Record is Sillo’s ORM, and this manual is all of it.

from sillo.record import Model
from tortoise import fields


class Post(Model):
    id = fields.IntField(pk=True)
    title = fields.CharField(max_length=200)
    body = fields.TextField()

post = await Post.create(title="Hello", body="…")
recent = await Post.active().order_by("-created_at").limit(10)
print(post.to_dict())

Record is Tortoise, plus a layer

sillo.record is a convenience layer over Tortoise ORM. It does not fork Tortoise, wrap its query compiler, or replace its connection handling.

Every Tortoise feature (fields, querysets, Q objects, relations, prefetching, aggregation, raw SQL) behaves exactly as the Tortoise documentation describes, because it is Tortoise underneath.

You should not need to go and read that documentation. This section covers the whole surface: fields, relationships, the queryset API, the lookups, aggregation, eager loading and raw SQL, as Sillo exposes it, with the Record layer in place rather than described separately.

What Record adds is the layer Django and Laravel developers reach for on day one:

A base model	Timestamps and soft deletes already wired
Mass-assignment control	fillable and guarded
Casting	Attributes converted on the way in and out
Scopes	Reusable query fragments, local and global
Events	Lifecycle hooks and observers
Collections	Chainable operations on a result set
Factories	Test data without fixtures
Transactions	A context manager, with savepoints
Migrations	Generated, reviewable, and applied by the CLI

The section

Getting a database

• Setup: setup_record, and the connection lifecycle
• Configuration: DatabaseConfig, URLs, backends, pooling

Models

• Models: the base class, serialisation, fetch shortcuts
• Field reference: every field type and its arguments
• Record’s own fields: PasswordField, SlugField, ULIDField
• Relationships: foreign keys, one-to-one, many-to-many
• Meta, indexes & constraints: table options and the schema
• Mass assignment: fillable, guarded, update_from_dict
• Mixins: composable behaviours, including soft deletes
• Casting: _casts and the cast registry
• Scopes: local and global query scopes
• Events: lifecycle hooks and observers

Querying

• The QuerySet API: every method, and when the query runs
• Field lookups: everything you can put after __
• Filtering with Q and F: OR, negation, column references
• Aggregation: annotate, counting, grouping
• Eager loading: select_related, prefetch_related
• Values & projections: fetching less than a whole row
• Raw SQL: when the ORM cannot express it

Reading and writing

• Queries: the helpers Record adds around a queryset
• Collections: working with a result set
• Pagination: pages, and the framework’s paginators
• Bulk operations: bulk_create, upsert, bulk_upsert
• Transactions: atomicity and savepoints
• Connections: replicas, routing and pooling

Testing and schemas

• Factories: building instances for tests
• Seeding and fixtures: Seeder and FixtureLoader
• Pydantic: generating schemas from models
• Exception handlers: database errors as HTTP responses

Migrations

• Migrations: what they are, and how they are generated
• Applying them: the deployment shape
• Programmatically: without the CLI

An admin panel

0.x shipped one inside the framework, under sillo.admin. 1.0 does not: it lives in Warder, a separate package with a React interface, installed with pip install warder when you want one and absent when you do not.

Honesty about maturity

Some parts of this package are thinner than a first read suggests, and you are better served knowing which up front than finding out during an incident. Where that is true, the page says so plainly, including what a helper needs before it will do what its name says. See for example the encrypted cast.