FraiseQL
A Python GraphQL framework for PostgreSQL. Declare types and operations with
decorators, point them at PostgreSQL views and functions, and FraiseQL serves a
typed GraphQL API over FastAPI — no build step, no code generation.
PostgreSQL returns JSONB. An integrated Rust pipeline (fraiseql_rs) transforms it
into the HTTP response. You write Python; the hot path runs in Rust.
Requires: Python 3.13 or 3.14 · PostgreSQL 13+
import fraiseql
from fraiseql.fastapi import create_fraiseql_app
@fraiseql.type(sql_source="v_user", jsonb_column="data")
class User:
"""A user in the system.
Fields:
id: Unique user identifier
name: User's full name
email: User's email address
"""
id: int
name: str
email: str
@fraiseql.query
async def users(info) -> list[User]:
"""Get all users."""
db = info.context["db"]
return await db.find("v_user")
app = create_fraiseql_app(
database_url="postgresql://localhost/mydb",
types=[User],
queries=[users],
)
Attribute docstrings become GraphQL descriptions. List queries get where,
orderBy, limit and offset wired in automatically.
How it works
Typical ORM stack: PostgreSQL → rows → ORM objects → Python dicts → JSON → HTTP
FraiseQL: PostgreSQL → JSONB → Rust field selection → HTTP
The view composes the whole response shape in one query, so there is no N+1 problem
and no Python serialization in the hot path. On the
transformation benchmark the JSON step runs
3.6–5.9x faster than the equivalent pure-Python path — 4.1x on a 7 KB nested payload,
4.0x on a 32 KB one.
It also makes the security model structural rather than defensive:
CREATE VIEW v_user AS
SELECT id, jsonb_build_object('id', id, 'email', email) AS data
FROM tb_user;
-- password_hash and api_key are not in the JSONB, so they cannot leak
With an ORM-backed schema, forgetting to exclude a column is a data leak. Here the
view is the contract. Reads go through v_* views and tv_* projection tables;
writes go through fn_* PostgreSQL functions (CQRS).
v1 vs v2 — which repo do you want?
This repository is v1 (fraiseql-python). There is a separate v2 project with a
different architecture. Both are actively maintained.
| v1 — this repo | v2 — fraiseql/fraiseql |
|---|
| Status | Stable (1.31.1) | Active (2.16.0; breaking changes ship in minor releases) |
| Engine | Python + Rust pipeline | Compiled Rust engine |
| Schema authoring | Python decorators | 16+ languages |
| Databases | PostgreSQL only | PostgreSQL, MySQL, SQLite, SQL Server |
| Deployment | Runtime (FastAPI, hot reload) | Build-time (fraiseql-cli compile) |
Pick v1 for a Python codebase already invested in PostgreSQL, with fast iteration and
no build step. Pick v2 for polyglot teams, multiple databases, or compile-time
guarantees.
Is this for you?
Good fit if you run PostgreSQL and are comfortable writing views and functions,
want a database-first API, need multi-tenant isolation, care about JSON throughput,
or lean on LLMs for code generation — SQL and Python are well-trained, and there is
no proprietary DSL in the way.
Look elsewhere if you need a database other than PostgreSQL (that is v2), do not
want JSONB in your schema, are building your first GraphQL API, or want an ORM to
model your data for you.
See Choosing FraiseQL for a longer comparison.
Quick start
pip install "fraiseql<2" # or: pip install "fraiseql[all]<2"
fraiseql init my-api
cd my-api
fraiseql dev
v1 and v2 share the fraiseql name on PyPI, and the bare name now resolves to v2 —
hence the <2 pin. Your API is live at http://localhost:8000/graphql.
Features
- GraphQL Cascade — mutations report what they
changed and which queries to invalidate; clients request as much or as little of it
as they want.
- Mutations without boilerplate —
@fraiseql.success auto-injects status, message, updated_fields and id; the
SQL function holds the business logic.
- Specialized scalars — 50+ validated types
(
EmailAddress, Money, IpAddress, LTree, CUSIP, DateRange, …) with
type-aware SQL operators.
- Advanced filtering — full-text search, JSONB
paths, array operators, regex, ranges, and
nested array filters with
AND/OR/NOT.
- Vector search — pgvector integration for semantic
search and RAG, with 6 distance operators.
- Trinity identifiers —
pk_* integer keys for fast
joins (never exposed), id UUIDs for a stable public API, identifier slugs for URLs.
- Security — RLS, rate limiting, CSRF, security
headers, field-level authorization, KMS backends (Vault/AWS/GCP), audit logging, and
SBOM generation via . Enforcement maturity varies per feature:
security enforce 7 of their 14 settings, and query depth, query complexity,
introspection policy and audit level are configured but not enforced by the profile
(see the module docstring in ). Check a
given control before relying on it in production.
Docs and tooling
The fraiseql CLI covers init, dev, check, doctor, generate, sql,
migrate, turbo, sbom and query-stats. Run fraiseql --help or see the
CLI reference. migrate needs the migrate extra:
pip install "fraiseql[migrate]<2".
Contributing
git clone https://github.com/fraiseql/fraiseql-python
cd fraiseql-python
uv sync # runtime + dev deps, builds the Rust extension
uv run pre-commit install
Requires a Rust toolchain for fraiseql_rs. The runtime floor is PostgreSQL 13; the
integration tests want 14+, and CI runs them on 16.
See the Contributing Guide.
About
FraiseQL is created by Lionel Hamayon (@evoludigit).
The idea: let PostgreSQL return the JSON, let Rust shape it, and keep Python out of
the hot path.
MIT licensed — see LICENSE.
