matrx-orm

Async-first PostgreSQL ORM for Python: typed models, an expressive query builder, bidirectional migrations with dependency-ordered history, schema introspection + code generation, and a mountable FastAPI admin router. Designed for applications that want ORM ergonomics without giving up raw-SQL control.

Install

pip install matrx-orm

Python 3.13+ required. Needs a PostgreSQL server (or Supabase / any Postgres-compatible backend). The only Matrx sibling it depends on is matrx-utils.

What's in the box

Core model layer: Model, BaseManager, BaseDTO, ModelView, model_registry, and 50+ field types (CharField, IntegerField, UUIDField, JSONField, ForeignKey, ManyToManyField, …).
Query layer: QueryBuilder, expressions (F, Q), window functions, CTEs, subqueries.
Migrations: MigrationDB, MigrationLoader, MigrationExecutor, makemigrations, migrate — migrations declare explicit dependencies and are applied in topological order. (Note: there is no multiple-head detection or merge primitive yet; parallel branches that both create the next sequence number must be reconciled by hand.)
Admin router (FastAPI): admin_router exposes a ready-to-mount set of read/write endpoints for every registered model.
API layer (optional [api] extra): APIServer, APIConfig, TokenAuth.
Adapters: AsyncPostgreSQLAdapter, SupabaseAdapter, PostgRESTClientAdapter.
Local artifact reads: read_local_sqlite_rows provides a validated, read-only projection boundary for SQLite files owned by external tools such as Chromium.
Signals: pre_create, post_create, pre_save, post_save, pre_delete, post_delete.
Schema builder (matrx_orm.schema_builder): code generation for Python + TypeScript type definitions from the live DB schema — useful for keeping a frontend's row types in sync.

Usage

Register a database project

matrx-orm supports multiple named database projects in a single process. Register each at startup, either with an explicit config or by reading env vars:

from matrx_orm import DatabaseProjectConfig, register_database, register_database_from_env

# Explicit config
register_database(DatabaseProjectConfig(
    name="main",
    host="localhost", port=5432,
    database="myapp", user="postgres", password="…",
    default_schema="public",
))

# Or env-driven with a custom prefix
register_database_from_env(name="analytics", env_prefix="ANALYTICS_DB_")

Declare a model and query

from matrx_orm import Model, CharField, UUIDField, TimestampField, DateTimeField

class User(Model):
    class Meta:
        table = "users"
        database = "main"

    id = UUIDField(primary_key=True)
    email = CharField(max_length=320, unique=True)
    display_name = CharField(max_length=120)
    created_at = DateTimeField(auto_now_add=True)

# Querying
user = await User.objects.get(email="alice@example.com")
active = await User.objects.filter(display_name__startswith="A").order_by("-created_at").all()

Migrations

# Generate migrations from the current model definitions
python -m matrx_orm.migrations.cli makemigrations

# Apply pending migrations
python -m matrx_orm.migrations.cli migrate

The migration system tracks which branch a migration originated on and refuses to let two branches create a conflicting sequence.

Mount the admin router

Rows with composite primary keys expose an opaque __matrx_row_id in list responses and a matching virtual primary-key column descriptor. Pass that value unchanged to row-detail, update, delete, and cache-eviction routes; the router decodes it into the complete composite key. This also gives generated read-only views collision-safe row navigation.

Generated views default to id only when they project it. Every other view must declare bounded, unique columns in generate[].output.view_primary_keys; generation fails instead of guessing a first column or embedding an unbounded projected row in an identifier.

from fastapi import FastAPI
from matrx_orm import admin_router

app = FastAPI()
app.include_router(admin_router, prefix="/admin")

Instantly exposes list/get/create/update/delete endpoints for every registered model. Wrap it in your app's auth middleware.

Standalone-friendliness

No hidden env-var reads outside config.py and the schema-builder CLI. All env-var access goes through register_database_from_env, which accepts a env_prefix and an env_var_overrides map. You can run matrx-orm with zero environment variables — just build a DatabaseProjectConfig yourself and call register_database.

Contributing

See CLAUDE.md for package-specific rules. MODEL_API.md documents the full Model/QueryBuilder API. This package lives in the aidream monorepo at github.com/AI-Matrix-Engine/aidream-current.

License

MIT.

Metadata

Release files for matrx-orm 3.1.207

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

Source distribution (sdist)

Source distribution for matrx-orm 3.1.207
File	Size	Uploaded
matrx_orm-3.1.207.tar.gz	1.1 MB	Oct 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for matrx-orm 3.1.207
File	Interpreter	ABI	Platform	Reset
matrx_orm-3.1.207-py3-none-any.whl 866.5 kB Oct 3, 2026	Python 3	none	any	Details

Total release size: 2.0 MB

Release files / matrx_orm-3.1.207.tar.gz

Download URL	matrx_orm-3.1.207.tar.gz
Size	1.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`a26f55417e9b922bb02b7a455c682534bb28801d2748eeb6e8fe48999d157343`
BLAKE2b-256 checksum How to use checksums	`4dd9d5543bbff7d900ef1971c69b2d22fee0f21a923b67f6a4513acd0eaa730a`
Upload date	Oct 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AI-Matrix-Engine/aidream
Publishing commit: github.com/AI-Matrix-Engine/aidream/tree/cc2d52a756bbb3b2f7e9ccff1e6b41025c876708

Workflow

Publishing configuration: github.com/AI-Matrix-Engine/aidream/blob/cc2d52a756bbb3b2f7e9ccff1e6b41025c876708/.github/workflows/publish-package.yml
Publishing logs: github.com/AI-Matrix-Engine/aidream/actions/runs/37083693418/attempts/1

Artifact

Subject: matrx_orm-3.1.207.tar.gz
SHA-256 checksum: a26f55417e9b922bb02b7a455c682534bb28801d2748eeb6e8fe48999d157343 Verifying attestations

Release files / matrx_orm-3.1.207-py3-none-any.whl

Download URL	matrx_orm-3.1.207-py3-none-any.whl
Size	866.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`44ba83f1ac5f36731903c87fb2b99874e7f0a900b7d669cad96eacb2ecc1a47e`
BLAKE2b-256 checksum How to use checksums	`51c97db67136841de6421bf5f10b7b38fe60382fdcc811ed595da5897d5d1dfe`
Upload date	Oct 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AI-Matrix-Engine/aidream
Publishing commit: github.com/AI-Matrix-Engine/aidream/tree/cc2d52a756bbb3b2f7e9ccff1e6b41025c876708

Workflow

Publishing configuration: github.com/AI-Matrix-Engine/aidream/blob/cc2d52a756bbb3b2f7e9ccff1e6b41025c876708/.github/workflows/publish-package.yml
Publishing logs: github.com/AI-Matrix-Engine/aidream/actions/runs/37083693418/attempts/1

Artifact

Subject: matrx_orm-3.1.207-py3-none-any.whl
SHA-256 checksum: 44ba83f1ac5f36731903c87fb2b99874e7f0a900b7d669cad96eacb2ecc1a47e Verifying attestations