Skip to content

Guides

New here? Concepts defines the vocabulary and Get started gives you a working repository. These guides then go one capability at a time, each a self-contained read with examples drawn from the kind of code repositories grow into: services that page through results, tasks that batch-insert, queries that join across tables.

Read them in any order. Each opens with the problem it solves, so you can tell at a glance whether it is the one you need right now.

  • Configuration

    Type parameters, field_mapping, pk_column, and where behavior plugs in. Start here to understand how the base is customized.

  • Filtering

    Two ways to filter in a single call, and the special meaning of None and UNSET as filter values.

  • Updating rows

    Partial updates that can tell "skip this field" apart from "set it to NULL".

  • Pagination

    list_paginated, the total count it returns, and the order it insists on.

  • Projection

    repo[Shape] to select only the columns a narrow shape declares.

  • Return types

    Dataclass, model-as-DTO, or Pydantic, and when each fits.

  • Hooks

    Add to a write or a read with @on, a derived column, an enriched DTO, an audit row, without overriding anything.

  • Custom queries

    Domain queries, batch inserts, and the @writes decorator, the raw-SQLAlchemy escape hatch for what the base does not cover.

  • Primary keys

    int, str, uuid.UUID, and tables whose key is not called id.