# py-store

> Lightweight multi-backend data layer for Python asyncio: pure JSON schemas plus a MongoDB-style GQL tree query dialect that runs on MongoDB, MySQL, SQLite and PostgreSQL, with built-in role-based access control, computed columns and soft-delete.

`py-store` lets a Python service define a model once as a dict and query it with a single dialect across MongoDB (native aggregation, PyMongo `AsyncMongoClient`) and MySQL / PostgreSQL / SQLite (parameterized SQL). Nested relations compile to one native query per backend. It is the Python host over the shared Rust engine [`rust-store`](https://github.com/coenddt/rust-store) (binding: `rust-store-py`); its Node.js twin is [`nodejs-store`](https://github.com/coenddt/nodejs-store).

- PyPI distribution name: `storepy` — import package: `py_store` (`pip install storepy`, `from py_store import init, store`)
- Runtime: Python 3.10+
- Backends: MongoDB, MySQL, SQLite, PostgreSQL
- License: MIT

## When to use it

- One codebase against several databases (MongoDB in dev, PostgreSQL in prod, or per tenant)
- Nested / relational reads without writing `$lookup` or JOINs
- FastAPI services, admin backends and internal CRUD APIs with schema-driven models
- Row-level and field-level access control (role whitelists, `creator` ownership, owner-condition injection)
- Multi-tenant SaaS (schema bound to `source` / `namespace`, runtime route override)
- Migrating between MongoDB and SQL while keeping one query syntax
- AI / natural-language data-QA layers (plan-only `build_pipeline()`, deterministic command JSON, structured feedback events)

## Docs

- [Documentation site](https://coenddt.github.io/py-store/): the scenario walkthroughs as individual, indexable pages — the fastest way in
- [README](https://github.com/coenddt/py-store#readme): full overview, quick start, GQL syntax, API, schema reference, FAQ
- [Chinese README](https://github.com/coenddt/py-store/blob/main/README.zh-CN.md): 中文文档
- [Use cases](https://github.com/coenddt/py-store/tree/main/doc/use-cases): scenario walkthroughs (multi-tenant SaaS, AI data-QA, cross-database migration, admin CRUD, async ETL/batch writes, migrating from SQLAlchemy or Beanie)
- [Scenario test suite](https://github.com/coenddt/py-store/tree/main/example/course-platform): real-data, four-backend scenario cases (fields, relations, computes, permissions, aggregation, boundaries)
- [CHANGELOG](https://github.com/coenddt/py-store/blob/main/CHANGELOG.md)

## Concepts

- [GQL tree syntax](https://github.com/coenddt/py-store#gql-syntax): `Model($condition:@c0,$sort:@s1,$limit:@l){ field, Relation{ f } }`
- [Aggregation](https://github.com/coenddt/py-store#aggregation): root-level `$group` / `$having`, relation aggregate predicates (semi/anti-join), relation-rolling computed columns
- [Query & write API](https://github.com/coenddt/py-store#query--write-api): `query`, `query_one`, `query_with_count`, `insert`, `update`, `remove`, `mutation`, `upsert`
- [Permissions](https://github.com/coenddt/py-store#permission-context): `set_context`, `run_as_internal`, fail-secure `set_require_context(True)`
- [Multi-datasource & multi-tenant](https://github.com/coenddt/py-store#multi-datasource-connections): `(source, namespace, collection)` and route override
- [Schema reference](https://github.com/coenddt/py-store#schema-reference): fields, relations, computes, indexes, read/write whitelists
- [Feedback events](https://github.com/coenddt/py-store#feedback-events): `set_feedback_sink`, `PushdownUnsupportedError`
- [Transactions](https://github.com/coenddt/py-store#transaction-boundary): per-source atomicity guarantees

## Optional

- [nodejs-store (Node.js twin)](https://github.com/coenddt/nodejs-store): same schemas, same GQL, camelCase API
- [rust-store (shared Rust core)](https://github.com/coenddt/rust-store): GQL parsing, permissions, computed columns, command planning, SQL dialect translation