Skip to main content

Ferrum

A next-generation async ORM for Python. Rust-powered engine. Pydantic-native models. Django-inspired developer experience.

Ferrum is an async-first ORM designed for modern Python applications.

Built around a Rust-powered core and a Python-native API, Ferrum combines the ergonomics of Django's ORM, the type safety of Pydantic, and the performance of Rust.

Why Ferrum?

Existing Python ORMs often force developers to choose between:

  • Developer experience
  • Async support
  • Type safety
  • Performance

Ferrum aims to provide all four.

Goals

  • Native async from day one
  • Pydantic-first models
  • Django-inspired ORM experience
  • Rust-powered query engine
  • PostgreSQL-first architecture. MySQL, SQLite, and SQL Server extras are best-effort thin parity — not production-supported and not production-readiness release gates
  • Type-safe query construction
  • Automatic migrations
  • High-performance result hydration
  • Production-ready observability

Production-readiness execution

Ferrum is still alpha. The remaining production work for Ticket Analyzer and an async-refactored Org AI Platform is tracked in the production-readiness plan. Execution is wave-based and supports parallel agents through disjoint file ownership, per-workstream state, immutable evidence logs, and an independent verification gate.

Every task follows Specify → Plan → Tasks → Implement; every executor run follows Load → Execute → Validate executor output → Verify independently → Update state. See .agent-work/production-readiness/ for the durable execution contract and current aggregate state.


Quick Example

from ferrum import Model


class User(Model):
    id: int
    email: str
    is_active: bool = True


user = await User.objects.create(
    conn,
    email="john@example.com",
)

# Insert from an instance (sentinel PK is dropped so the DB default runs)
draft = User(id=0, email="dana@example.com")
created = await User.objects.create(conn, draft)

# Persist one instance's changes by primary key
created.is_active = False
await User.objects.update_instance(conn, created, fields=["is_active"])

users = await (
    User.objects
    .filter(is_active=True)
    .order_by("-id")
    .limit(10)
    .all(conn)
)

async with conn.transaction() as tx:
    user = await User.objects.create(tx, email="jane@example.com")
    await AuditLog.objects.create(tx, user_id=user.id, action="signup")

Features

Async First

No synchronous compatibility layer.

Ferrum is designed around modern async Python applications.

users = await User.objects.all(conn)

Pydantic Native

Models are built directly on top of Pydantic.

class User(Model):
    id: int
    email: str

No duplicate schema definitions.

Field Options

ferrum.Field() accepts column-level constraints that are carried through to DDL:

Parameter Type Description
db_default str | None DB-side DEFAULT expression (e.g. "NOW()", "''", "GEN_RANDOM_UUID()"). Token casing is normalised (now() → NOW()).
nullable bool | None Override annotation-derived nullability. Use nullable=False to force NOT NULL even on a T | None-annotated field.
db_index bool Emit a CREATE INDEX on this column (auto-named idx_{table}_{field}).
unique bool Emit a UNIQUE constraint.
db_column str | None Override the database column name.
primary_key bool Declare this field as the primary key.
uuid_generate "v4" | "v7" | None Set GEN_RANDOM_UUID() / UUIDV7() as the DB default for UUID PK columns.
max_length int | None Emit VARCHAR(n) instead of TEXT.
max_digits / decimal_places int | None Emit NUMERIC(p,s).
vector_dimensions int | None Required for Vector columns; emits VECTOR(n).
jsonb_list bool Store list[T] as JSONB instead of a PostgreSQL ARRAY.
generated bool Select/hydrate the DB-generated column, but exclude it from writes.
read_only bool Select/hydrate the column, but reject explicit write assignments.
from datetime import datetime
from typing import Annotated
from ferrum import Model, Field

class Event(Model):
    id: int
    # DB-side timestamp default; Python annotation allows None but column is NOT NULL
    created_at: Annotated[datetime | None, Field(db_default="now()", nullable=False)]
    # Indexed text column
    kind: Annotated[str, Field(db_index=True, max_length=64)]

makemigrations honours these field attributes:

  • db_default / nullable are written into CREATE TABLE and ADD COLUMN DDL.
  • A plain Python default also becomes the column DEFAULT when it has a safe SQL literal form: bool, "", and finite int / float / Decimal numbers (e.g. int = 14 → DEFAULT 14, float = 1e-06 → DEFAULT 1e-06). Other defaults (non-empty strings, dates, objects) are applied by Python on insert only. A non-finite number (inf, nan) fails makemigrations with FERR-M001.
  • db_index=True emits CREATE INDEX after the table op.
  • A ForeignKey / OneToOne references the target model's primary-key column, so natural keys work (e.g. REFERENCES catalog_version(version)). A target with a composite primary key raises FerrumSchemaError, because a single-column foreign key cannot reference it.
  • Every AddForeignKey comes after all CreateTable ops in the same migration, so model order, self-references and cycles do not matter.
  • Several primary_key=True fields produce CreateTable(..., composite_pk_columns=[...]) → PRIMARY KEY (a, b, ...).
  • A Literal[...] field produces ops.Column(..., enum_values=[...]) → CHECK (col IN (...)), with each value escaped.
  • reverse_operations undo in reverse order, so foreign keys drop before tables.
  • For already-existing tables, makemigrations now autodiffs index and column attribute changes against the state projected from prior migration files:
    • Adding db_index=True to an existing field → AddIndex op.
    • Removing db_index=True → DropIndex op.
    • Adding or changing db_default → AlterColumn … SET DEFAULT … op.
    • Removing db_default → AlterColumn … DROP DEFAULT op.
    • Changing nullability → AlterColumn … SET / DROP NOT NULL op (SET NOT NULL is classified destructive and requires --confirm).
    • Column type changes, renames, and drops remain manual (out of scope for v0.1).

Django-Inspired API

Familiar query interface.

users = await (
    User.objects
    .filter(email__contains="@gmail.com")
    .order_by("-created_at")
    .all(conn)
)

Typed aggregates and bounded PostgreSQL streaming use the same metadata allowlists and bound-parameter compiler path:

from ferrum.queryset import Aggregate

counts = await (
    Ticket.objects
    .group_by("team_id")
    .date_trunc("created_at", "day", alias="day")
    .having(total__gte=10)
    .aggregate(conn, total=Aggregate.count())
)

async with Ticket.objects.filter(active=True).stream(conn, chunk_size=500) as chunks:
    async for tickets in chunks:
        await process(tickets)

stream() preserves projection/deferred/value-queryset materialization and deterministically releases its cursor on exhaustion, early break, cancellation, or error. It rejects prefetch_related() because cross-chunk relationship batching is not safe. Filtered update_returning() provides atomic compare-and-set semantics: encode the expected state in filter() and treat an empty returned list as a lost race.

First-Class IDE Support

Ferrum ships a PEP 561 py.typed marker, so editors and type checkers (mypy, pyright, ty) resolve its inline hints out of the box. Model.objects is typed as QuerySet[YourModel], chaining preserves the model type, and terminals infer precise results — no casts:

users: list[User] = await User.objects.filter(is_active=True).all(conn)   # list[User]
user: User | None = await User.objects.first(conn)                        # User | None
rows: list[dict[str, Any]] = await User.objects.values("id", "email").all(conn)
ids: list[Any] = await User.objects.values_list("id", flat=True).all(conn)

values() / values_list() return dedicated ValuesQuerySet, ValuesListQuerySet, and FlatValuesListQuerySet variants (all exported from ferrum) so all() returns list[dict[str, Any]], list[tuple[Any, ...]], or list[Any] respectively.

Rust-Powered Core

Performance-critical components are implemented in Rust:

  • Query compilation
  • SQL generation
  • Result decoding
  • Schema analysis
  • Migration planning

This allows Ferrum to maintain a Pythonic API without sacrificing performance.

Native full-text search across PostgreSQL, MySQL, SQLite FTS5, and SQL Server — one QuerySet API, dialect-specific SQL emit and migration DDL. Cross-dialect FTS on MySQL / SQLite / SQL Server is a thin-extra capability, not a P0 production-readiness release gate. PostgreSQL FTS is the production-readiness target.

Query modes (filter lookups and ranking):

Mode Lookup operator Typical use
plain __match Natural-language terms
phrase __match_phrase Exact phrase
websearch __match_websearch Web-style quotes, - negation
boolean __match_boolean Boolean operators (&, |, !)

Convenience methods:

# Filter + relevance ranking in one call
hits = await Article.objects.search(
    "python async orm", field="body", mode="websearch"
).limit(10).all(conn)

# Rank without an implicit filter
ranked = await Article.objects.rank_by("body", "rust", mode="plain").all(conn)

Index declaration — PostgreSQL uses TSVector columns; other drivers index base text columns via Meta.full_text_indexes:

from ferrum.models import Field, FullTextIndex

class Article(Model):
    search_vector: Annotated[TSVector, Field(fts_config="english")] | None = None
    body: str = ""

    class Meta:
        full_text_indexes = [FullTextIndex(fields=("body",), config="english")]

Query strings are always bound parameters; fts_config and index names come from model-metadata allowlists only. See Getting Started → Vector and full-text columns and API Reference for per-dialect DDL and operator mapping.

Architecture

┌──────────────────────────┐
│      Python API          │
│  Models / QuerySets      │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│      Ferrum Core         │
│      (Rust Engine)       │
├──────────────────────────┤
│ Query Compiler           │
│ SQL AST                  │
│ Result Decoder           │
│ Migration Planner        │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│       PostgreSQL         │
└──────────────────────────┘

Roadmap

v0.1 (complete)

  • PostgreSQL support
  • Basic CRUD operations
  • Async query execution
  • Pydantic models
  • Query builder
  • Type-safe filters
  • Transactions and savepoints
  • Bulk operations (bulk_create, bulk_update, bulk_delete)
  • Migrations (schema diff, apply, revert, CLI)
  • Relationships (ForeignKey, OneToOne, ManyToMany)
  • pgvector KNN search and HNSW/IVFFLAT index DDL
  • Full-text search (PostgreSQL is the P0 gate; MySQL/SQLite/SQL Server FTS is thin-extra)
  • Observability hooks (Tier A/B/C)
  • CLI (makemigrations, migrate, revert, showmigrations, inspectdb, resetdb)

v0.2 (in progress)

  • Upsert API (upsert, bulk_upsert with conflict targets and RETURNING)
  • Composite primary keys
  • Array field types (uuid[], text[], scalar arrays)
  • JSONB operators (__contains, __has_key)
  • RLS / tenant session helpers (set_config, tenant_session)
  • call_function for allowlisted stored-procedure calls
  • Migration ops for extensions, RLS policies, and function DDL
  • pgvector similarity score projection (vector_search helper)
  • Field(db_default=..., nullable=...) — first-class DB-side defaults and nullability override
  • makemigrations autodiff for index / default / nullability changes on existing tables
  • Typed aggregates, filtered UPDATE … RETURNING, and bounded QuerySet streaming
  • JSONB-list/generated/read-only metadata and read-only PostgreSQL schema drift reports
  • Query optimization (deferred fields, prefetch tuning)
  • Advanced relationship loading

v1.0

  • Production-ready stability
  • Performance benchmarking suite
  • Full documentation site

Project Status

Ferrum is currently in active development.

The API is not yet stable. 0.x has no compatibility guarantee: SemVer MINOR and PATCH may both break. After 1.0, public API and migration-ops breaks require a deprecation window of at least one minor release and 90 days, whichever is longer. Generated SQL is never a compatibility surface. Compatibility policy: AGENTS.md §5a. Thin extras: AGENTS.md §2.6. See also CHANGELOG.md.

Installation

# PostgreSQL (most common)
pip install 'ferrum-orm[pg]'

# PostgreSQL + migrations CLI
pip install 'ferrum-orm[pg,cli]'

# MySQL
pip install 'ferrum-orm[mysql]'

# SQLite + migrations CLI (testing / local dev)
pip install 'ferrum-orm[sqlite,cli]'

# SQL Server (also needs a system ODBC driver, e.g. msodbcsql18)
pip install 'ferrum-orm[mssql]'

# Optional MessagePack wire format for the Python<->Rust boundary
pip install 'ferrum-orm[msgpack]'

# Everything (all drivers + CLI + dotenv)
pip install 'ferrum-orm[all]'

# Core ORM only (no database driver — install a driver extra before connecting)
pip install ferrum-orm

Bare ferrum-orm installs Pydantic and the Rust core only. Choose a driver extra (pg, mysql, sqlite, or mssql) before calling ferrum.connect().

MySQL, SQLite, and SQL Server are best-effort thin-parity backends: they are not production-supported and are not production-readiness release gates. Core CRUD is exercised across all four drivers; advanced behavior is capability-gated rather than emulated with incompatible SQL. The integration-suite registry (tests/python/integration/backends.py) is the coverage matrix — what is tested, not a stability or production-support claim. PostgreSQL claims every capability. MySQL and SQL Server claim full-text search and composite primary keys only. SQLite claims RETURNING, full-text search, and composite primary keys.

Capability PostgreSQL MySQL SQLite SQL Server
Transactions ✅ — — —
Savepoints ✅ — — —
Cursor streaming ✅ — — —
Bulk update ✅ — — —
Aggregates / grouping ✅ — — —
Upsert ✅ — — —
Returning rows ✅ — ✅ —
Row-level security helpers ✅ — — —
pgvector ✅ — — —
Full-text search ✅ ✅ ✅ ✅
JSON operators ✅ — — —
Case-insensitive ILIKE ✅ — — —
Array columns ✅ — — —
Alter column ✅ — — —
Composite primary keys ✅ ✅ ✅ ✅
Stored-function calls ✅ — — —

Unsupported capabilities fail with a typed Ferrum error before backend SQL is executed. Transactions, savepoints, aggregates, upsert, alter-column, and stored-function calls are PostgreSQL-only in this matrix; thin extras raise at the Python/compiler boundary rather than sending Postgres SQL. Pull requests exercise PostgreSQL and SQLite, while the nightly integration matrix runs PostgreSQL, MySQL, SQLite, and SQL Server independently. SQLite on PRs is CI coverage, not a production-readiness gate. Cross-dialect FTS in the matrix is thin-extra coverage, not a P0 release gate.

SQL Server connects via aioodbc/pyodbc and requires a system ODBC driver such as msodbcsql18; DSNs use the mssql:// or sqlserver:// scheme.

Wire format (advanced)

The Python↔Rust IR/hydration boundary defaults to JSON. Installing the msgpack extra lets you switch it to MessagePack, selected via the FERRUM_WIRE_FORMAT environment variable (json | msgpack) or the [ferrum] wire_format key in ferrum.toml / pyproject.toml. JSON remains the default; MessagePack is opt-in.

From source, build the native extension with maturin develop (or mise run dev).

Examples

Runnable samples live under examples/:

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for local setup, scoped verification, architecture rules, and pull request expectations.

License

Apache License 2.0

Metadata

Release files for ferrum-orm 0.1.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ferrum-orm 0.1.22
File Size Uploaded Provenance Actions
ferrum_orm-0.1.22.tar.gz 297.7 kB With provenance Details for ferrum_orm-0.1.22.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for ferrum-orm 0.1.22
File Actions
ferrum_orm-0.1.22-cp311-abi3-manylinux_2_28_x86_64.whl CPython 3.11 abi3 Linux glibc 2.28+ x86-64 Details for ferrum_orm-0.1.22-cp311-abi3-manylinux_2_28_x86_64.whl
ferrum_orm-0.1.22-cp311-abi3-manylinux_2_28_aarch64.whl CPython 3.11 abi3 Linux glibc 2.28+ ARM64 Details for ferrum_orm-0.1.22-cp311-abi3-manylinux_2_28_aarch64.whl
ferrum_orm-0.1.22-cp311-abi3-macosx_11_0_arm64.whl CPython 3.11 abi3 macOS 11.0+ ARM64 Details for ferrum_orm-0.1.22-cp311-abi3-macosx_11_0_arm64.whl
ferrum_orm-0.1.22-cp311-abi3-macosx_10_12_x86_64.whl CPython 3.11 abi3 macOS 10.12+ x86-64 Details for ferrum_orm-0.1.22-cp311-abi3-macosx_10_12_x86_64.whl

Total release size: 4.2 MB

Release files / ferrum_orm-0.1.22.tar.gz

Download URL ferrum_orm-0.1.22.tar.gz
Size 297.7 kB
Tags Source
SHA-256 checksum
How to use checksums
0f69b8f59cd726d1aeba8f000dec6d101800593e940844d08e59545dff0b2afd
BLAKE2b-256 checksum
How to use checksums
c3c6e4f748b8f1b34125f6a4c96111ff6c49670217ec264c7e49a22fb2095f53
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / ferrum_orm-0.1.22-cp311-abi3-manylinux_2_28_x86_64.whl

Download URL ferrum_orm-0.1.22-cp311-abi3-manylinux_2_28_x86_64.whl
Size 1.0 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
2b6f3eec99bd9723cf7efde5397b47ab81afb73fb03ea9227ce5bdbcea8cdcd6
BLAKE2b-256 checksum
How to use checksums
a545a0433fa369a065620e669be2f294a205ee0bf6d66d1f026d182e7d24064d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / ferrum_orm-0.1.22-cp311-abi3-manylinux_2_28_aarch64.whl

Download URL ferrum_orm-0.1.22-cp311-abi3-manylinux_2_28_aarch64.whl
Size 991.1 kB
Tags CPython 3.11 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
c775b6717a8cf6e432df0ef358df3f9f2b8c01de1355781430cae72b25f540ab
BLAKE2b-256 checksum
How to use checksums
0a96b17c1a39955ea8bd78437d88ff4c3e9c3c3bfa0553f3fac14872f6628bc3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / ferrum_orm-0.1.22-cp311-abi3-macosx_11_0_arm64.whl

Download URL ferrum_orm-0.1.22-cp311-abi3-macosx_11_0_arm64.whl
Size 938.2 kB
Tags CPython 3.11 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
060c4491b3378574b946c800743d932ddf0041d03391bb082db5db2b6f5fc4e4
BLAKE2b-256 checksum
How to use checksums
2a2202cde2d829de93b053f1e96703d8ea7cb91bbb59a829df361fbdecab6e4d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / ferrum_orm-0.1.22-cp311-abi3-macosx_10_12_x86_64.whl

Download URL ferrum_orm-0.1.22-cp311-abi3-macosx_10_12_x86_64.whl
Size 980.1 kB
Tags CPython 3.11 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
375b06ed8b00a9d55931a09d5279bf8c0c77fda2c266eb076e81fbca130bcf66
BLAKE2b-256 checksum
How to use checksums
87964ff537982dbf6820cee4619d3f2617c29e1e80b6bb880c4750512ad419b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for ferrum-orm 0.1.22

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for ferrum_orm-0.1.22.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page