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 explicitdependenciesand are applied in topological order. (Note: there is no multiple-head detection ormergeprimitive yet; parallel branches that both create the next sequence number must be reconciled by hand.) - Admin router (FastAPI):
admin_routerexposes 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_rowsprovides 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.
1 maintainer
Release files for matrx-orm 3.1.124
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| matrx_orm-3.1.124.tar.gz | 860.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| matrx_orm-3.1.124-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.6 MB
Release files / matrx_orm-3.1.124.tar.gz
| Download URL | matrx_orm-3.1.124.tar.gz |
|---|---|
| Size | 860.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3be957183b582a03fcb02841e367463b8118df4fc420a25dabac98da42c591ab
|
|
BLAKE2b-256 checksum How to use checksums |
958ae31d0ce738a127273ed31a46942eaec62a32d54a651723552191ed01fe0d
|
| Upload date | |
|
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.
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 Aug 31, 2026.
Transparency logRelease files / matrx_orm-3.1.124-py3-none-any.whl
| Download URL | matrx_orm-3.1.124-py3-none-any.whl |
|---|---|
| Size | 694.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f8205e8d8cbcbb41f0091ee91a58e11b85aa96461a84beb2438e4a6ff0b0b8fc
|
|
BLAKE2b-256 checksum How to use checksums |
ad63f70deab2968b66829aafcd65783e1475130a934639a81fe765d0f40f201c
|
| Upload date | |
|
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.
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 Aug 31, 2026.
Transparency log
