prisma-client-py

Prisma Client Python is an ORM that generates a fully type-safe database client directly from a Prisma schema file, giving Python applications the same schema-first, autocompletion-friendly query experience that Prisma popularized in the TypeScript ecosystem. Instead of writing a client by hand, developers define models and a datasource in a schema.prisma file, run prisma generate, and get a typed client with IDE-completed query arguments (via TypedDicts), pydantic-backed result models, and both async and sync APIs generated from the same schema.

Under the hood it doesn’t reimplement SQL generation — it drives Prisma’s Rust-based query engine and CLI (fetched as part of the generate step) to handle migrations, connection pooling, and cross-database query execution against PostgreSQL, MySQL, SQLite, CockroachDB, and experimental MongoDB/SQL Server backends. The project’s README now carries a maintainer notice that it is no longer actively maintained, so it is best evaluated today as a mature, well-tested reference implementation of schema-driven, fully-typed ORM codegen for Python rather than an actively evolving product.

What You Get

• A generated, project-specific client (prisma.Prisma) with typed CRUD methods (find_many, create, update, upsert, group_by, batching, and more) for every model in your schema
• TypedDict-based query arguments that give autocompletion for filters, includes, and ordering in Pyright/Pylance-aware editors
• Choice of async or sync client generated from the same schema, with pydantic models for every returned record
• A bundled CLI (prisma generate, prisma db push, prisma migrate, prisma studio, plus package-specific commands like prisma fetch) that wraps the official Prisma CLI without requiring a separate Node.js install
• A mypy plugin and Pyright-strict-compatible types for catching invalid queries and field names before runtime
• Partial types and recursive/pseudo-recursive relation typing for modeling nested and self-referential data

Common Use Cases

• Adding a fully typed ORM layer to an async Python web API (FastAPI, Starlette, etc.) without hand-writing SQLAlchemy models
• Sharing one Prisma schema across a TypeScript frontend/backend and a Python service for a consistent, single-source data model
• Rapid prototyping against SQLite or Postgres with prisma db push, then evolving the schema with tracked migrations
• Enforcing compile-time-checked database access in data pipelines or scripts where catching a bad field name before runtime matters
• Teams already using Prisma’s tooling and CLI conventions who need a Python client alongside existing Node/TypeScript services

Under The Hood

Architecture The published package ships a mostly-generated surface: files like client.py, models.py, actions.py, bases.py, and types.py are produced at prisma generate time and are explicitly banned from direct import outside runtime by a ruff flake8-tidy-imports rule, since their contents depend on the consuming project’s own schema. The hand-written runtime underneath lives in _base_client.py, _async_http.py/_sync_http.py, and _transactions.py, which talk to Prisma’s Rust query-engine binary through the engine/ package (_query.py, _http.py, _abstract.py), with binaries fetched and verified via the binaries/ module. Queries are assembled as an intermediate GraphQL-like document tree in _builder.py (an AbstractNode/Field structure with explicit method-to-operation and method-to-GraphQL-name mappings) before being serialized and sent to the engine over HTTP. Code generation itself is driven by a JSON-RPC server (generator/generator.py, generator/jsonrpc.py) that Prisma’s engine invokes, rendering Jinja templates under generator/templates/ into the final typed client. This is a layered, codegen-first design: schema and CLI on one side, a query-builder/HTTP bridge to a foreign-language engine on the other, joined by a template-rendering generator in the middle.

Tech Stack The library targets Python 3.8+ and depends on httpx (sync/async HTTP transport to the engine), pydantic 1.10+ (accepting either v1 or v2 through a _compat.py shim), click (CLI), python-dotenv, typing-extensions, tomlkit, and nodeenv (used to provision an isolated Node.js environment so the Prisma CLI/engine tooling can run without requiring the user to install Node themselves). A vendored, patched copy of the lark parser lives in _vendor/ for parsing the Prisma schema DSL. Packaging still uses a classic setup.py/setuptools build (pyproject.toml only configures ruff and Pyright, not [project] metadata), with console-script entry points for prisma/prisma-client-py. Docs are built with mkdocs and published on ReadTheDocs via .readthedocs.yaml.

Code Quality The test suite is extensive — around 59 test files covering the query builder, engine/CLI subprocess behavior (faked with pytest-subprocess), dotenv loading, config parsing, and dedicated test_generation/integrations suites that generate real clients against real databases per supported provider. A separate typesafety/ directory holds Pyright and mypy fixture tests that verify the generated client’s static types are actually correct, not just that the code runs. Ruff enforces import ordering, unused imports/arguments, and a custom banned-import list preventing generated-only modules from being imported outside runtime contexts; Pyright runs in strict mode with reportImplicitOverride enabled. Errors are raised as dedicated typed exception classes rather than bare exceptions, and GitHub Actions CI (test.yml) exercises the matrix across platforms and database providers.

API Design The headline developer-experience choice is generating a client tailored to the user’s own schema rather than shipping one generic dynamically-typed client: every model gets its own typed methods and TypedDict argument shapes, so editors with Pyright/Pylance can autocomplete filter and include keys that a hand-rolled ORM typically can’t offer. Both sync and async clients come from the same schema and generator, avoiding a second codebase for either mode. The tradeoff for this DX is a heavier bootstrap (an engine binary and a Node-provisioned CLI must be fetched), and the README itself lists known rough edges (editor-completion support varies, performance work is still open) alongside the maintainer’s notice that the project is no longer actively maintained — so the design is mature and distinctive, but frozen rather than still evolving.