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.
  • 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.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (3.1.99)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for armanisadeghi from gravatar.com armanisadeghi

Credits

Author/Maintainer: Matrx

License

MIT License (MIT)

Requires

Python >=3.13

Provides Extra

admin api

Tags

async asyncio asyncpg database many-to-many migrations orm postgresql schema-builder supabase

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matrx_orm-3.1.26.tar.gz (685.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

matrx_orm-3.1.26-py3-none-any.whl (565.2 kB view details)

Uploaded Python 3

File details

Details for the file matrx_orm-3.1.26.tar.gz.

File metadata

  • Download URL: matrx_orm-3.1.26.tar.gz
  • Upload date:
  • Size: 685.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for matrx_orm-3.1.26.tar.gz
Algorithm Hash digest
SHA256 366e210076a98372327da19e86a283a2b56380aab81e8de01a7a07775c35e361
MD5 2ff23c57d562f03bf292c094d5db7604
BLAKE2b-256 1de967989d63dcb480f681b0bf5637a967fca6a460b72e2e6f5d1b00b6e6b7b6

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_orm-3.1.26.tar.gz:

Publisher: publish-package.yml on AI-Matrix-Engine/aidream

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file matrx_orm-3.1.26-py3-none-any.whl.

File metadata

  • Download URL: matrx_orm-3.1.26-py3-none-any.whl
  • Upload date:
  • Size: 565.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for matrx_orm-3.1.26-py3-none-any.whl
Algorithm Hash digest
SHA256 7e4db0950eda85f0536d7ddeca065556fdb2cdaaeb059854a56d1b599d3a7202
MD5 f74a03895b1a028a8ffa588eb8994d97
BLAKE2b-256 91c1af64f4a0a9069cc3c95c44eecb1430bc11f2db3534a2a8965f69f8425885

See more details on using hashes here.

Provenance

The following attestation bundles were made for matrx_orm-3.1.26-py3-none-any.whl:

Publisher: publish-package.yml on AI-Matrix-Engine/aidream

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

3.1.99

2 files

3.1.98

2 files

3.1.97

2 files

3.1.96

2 files

3.1.95

2 files

3.1.94

2 files

3.1.93

2 files

3.1.92

2 files

3.1.91

2 files

3.1.90

2 files

3.1.89

2 files

3.1.88

2 files

3.1.87

2 files

3.1.86

2 files

3.1.85

2 files

3.1.84

2 files

3.1.83

2 files

3.1.82

2 files

3.1.81

2 files

3.1.80

2 files

3.1.79

2 files

3.1.78

2 files

3.1.77

2 files

3.1.76

2 files

3.1.75

2 files

3.1.74

2 files

3.1.73

2 files

3.1.72

2 files

3.1.71

2 files

3.1.70

2 files

3.1.69

2 files

3.1.68

2 files

3.1.67

2 files

3.1.66

2 files

3.1.65

2 files

3.1.64

2 files

3.1.63

2 files

3.1.62

2 files

3.1.61

2 files

3.1.60

2 files

3.1.59

2 files

3.1.58

2 files

3.1.57

2 files

3.1.56

2 files

3.1.55

2 files

3.1.54

2 files

3.1.53

2 files

3.1.52

2 files

3.1.51

2 files

3.1.50

2 files

3.1.49

2 files

3.1.48

2 files

3.1.47

2 files

3.1.46

2 files

3.1.45

2 files

3.1.44

2 files

3.1.43

2 files

3.1.42

2 files

3.1.41

2 files

3.1.40

2 files

3.1.39

2 files

3.1.38

2 files

3.1.37

2 files

3.1.36

2 files

3.1.35

2 files

3.1.34

2 files

3.1.33

2 files

3.1.32

2 files

3.1.31

2 files

3.1.30

2 files

3.1.29

2 files

3.1.28

2 files

3.1.27

2 files

This release

3.1.26 This release

2 files

3.1.25

2 files

3.1.24

2 files

3.1.23

2 files

3.1.22

2 files

3.1.21

2 files

3.1.20

2 files

3.1.19

2 files

3.1.18

2 files

3.1.17

2 files

3.1.16

2 files

3.1.15

2 files

3.1.14

2 files

3.1.13

2 files

3.1.12

2 files

3.1.11

2 files

3.1.10

2 files

3.1.9

2 files

3.1.8

2 files

3.1.7

2 files

3.1.6

2 files

3.1.5

2 files

3.1.4

2 files

3.1.3

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.32

2 files

3.0.31

2 files

3.0.30

2 files

3.0.29

2 files

3.0.28

2 files

3.0.27

2 files

3.0.26

2 files

3.0.25

2 files

3.0.24

2 files

3.0.23

2 files

3.0.22

2 files

3.0.21

2 files

3.0.20

2 files

3.0.19

2 files

3.0.17

2 files

3.0.16

2 files

3.0.15

2 files

3.0.13

2 files

3.0.12

2 files

3.0.11

2 files

3.0.10

2 files

3.0.9

2 files

3.0.7

2 files

3.0.5

2 files

3.0.3

2 files

3.0.1

2 files

3.0.0

2 files

2.0.40

2 files

2.0.39

2 files

2.0.38

2 files

2.0.37

2 files

2.0.36

2 files

2.0.35

2 files

2.0.34

2 files

2.0.33

2 files

2.0.32

2 files

2.0.31

2 files

2.0.30

2 files

2.0.29

2 files

2.0.28

2 files

2.0.27

2 files

2.0.26

2 files

2.0.25

2 files

2.0.24

2 files

2.0.23

2 files

2.0.22

2 files

2.0.21

2 files

2.0.20

2 files

2.0.19

2 files

2.0.18

2 files

2.0.17

2 files

2.0.16

2 files

2.0.15

2 files

2.0.14

2 files

2.0.13

2 files

2.0.12

2 files

2.0.11

2 files

2.0.10

2 files

2.0.9

2 files

2.0.8

2 files

2.0.7

2 files

2.0.6

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.9.0

2 files

1.8.0

2 files

1.7.0

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.0

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.8

2 files

1.0.7

2 files

1.0.5

2 files

1.0.4

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page