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.27.0) | 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.
- 5-Minute Quickstart — copy, paste, run
- First Hour Guide — build a complete blog API
- Understanding FraiseQL — architecture in 10 minutes
- Installation — platform notes and troubleshooting
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.successauto-injectsstatus,message,updated_fieldsandid; 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),idUUIDs for a stable public API,identifierslugs for URLs. - Security — RLS, rate limiting, CSRF, security
headers, field-level authorization, KMS backends (Vault/AWS/GCP), audit logging, and
SBOM generation via
fraiseql sbom generate. Enforcement maturity varies per feature: security profiles 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 insrc/fraiseql/security/profiles/definitions.py). Check a given control before relying on it in production. - Everything in PostgreSQL — caching
(
UNLOGGEDtables), error tracking and OpenTelemetry traces live in the same database, so a small deployment needs no Redis, Sentry or APM service. - Automatic Persisted Queries — memory or PostgreSQL-backed storage for multi-instance coordination.
- Resilience testing — a separate, informational workflow runs the 71 failure-injection
tests marked
chaos_real_db(of 145 intests/chaos/) against real PostgreSQL, apart from the per-PR suite (strategy).
Docs and tooling
- Full documentation · Concepts & glossary
- API reference · CLI reference
- Performance guide · Production deployment
- Examples — blog, e-commerce, multi-tenant SaaS, RAG, and more
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.
1 maintainer
Metadata
1 maintainer
Release files for fraiseql 1.27.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| fraiseql-1.27.0.tar.gz | 860.2 kB | Without provenance | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| fraiseql-1.27.0-cp314-cp314-win_amd64.whl | CPython 3.14 | CPython 3.14 | Windows x86-64 | Details |
| fraiseql-1.27.0-cp314-cp314-manylinux_2_38_x86_64.whl | CPython 3.14 | CPython 3.14 | Linux glibc 2.38+ x86-64 | Details |
| fraiseql-1.27.0-cp314-cp314-macosx_11_0_arm64.whl | CPython 3.14 | CPython 3.14 | macOS 11.0+ ARM64 | Details |
| fraiseql-1.27.0-cp313-cp313-win_amd64.whl | CPython 3.13 | CPython 3.13 | Windows x86-64 | Details |
| fraiseql-1.27.0-cp313-cp313-manylinux_2_38_x86_64.whl | CPython 3.13 | CPython 3.13 | Linux glibc 2.38+ x86-64 | Details |
| fraiseql-1.27.0-cp313-cp313-macosx_11_0_arm64.whl | CPython 3.13 | CPython 3.13 | macOS 11.0+ ARM64 | Details |
Total release size: 21.8 MB
Release files / fraiseql-1.27.0.tar.gz
| Download URL | fraiseql-1.27.0.tar.gz |
|---|---|
| Size | 860.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
72f40c15c83dc09507043ca492e733af1802547d8e9ce19d1e98cd8ab6122f8a
|
|
BLAKE2b-256 checksum How to use checksums |
a89b49d64a161482b15e51039a3190c0024fd7e5aaef67652b892bf8f3d476ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / fraiseql-1.27.0-cp314-cp314-win_amd64.whl
| Download URL | fraiseql-1.27.0-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
8ef34138c6330b813d858c0ba8a4b0b9eca3e8a531cea8cd6422fb2e67ff6655
|
|
BLAKE2b-256 checksum How to use checksums |
1a41fe586eeefe4de865a4086d803aa7d2e97977cbab50a28adfa2be9ee16788
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / fraiseql-1.27.0-cp314-cp314-manylinux_2_38_x86_64.whl
| Download URL | fraiseql-1.27.0-cp314-cp314-manylinux_2_38_x86_64.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.14 Linux glibc 2.38+ x86-64 |
|
SHA-256 checksum How to use checksums |
96958167671ac368918eaa755c51db6d7eef0e7be5897a283e6bcf2d58a7d010
|
|
BLAKE2b-256 checksum How to use checksums |
14f981b446ecd17b067668c965f5e3cf5c55656a364066c47471cecebe53222d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / fraiseql-1.27.0-cp314-cp314-macosx_11_0_arm64.whl
| Download URL | fraiseql-1.27.0-cp314-cp314-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.14 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
cdc4d5e14e77ea29192c4276a82f92177c027a8d0b8980c7544fbf33a977653f
|
|
BLAKE2b-256 checksum How to use checksums |
1ea597bae37e85fdef3e67669aa748b43f4f35f92cc611dbe51a954267707a7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / fraiseql-1.27.0-cp313-cp313-win_amd64.whl
| Download URL | fraiseql-1.27.0-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 3.3 MB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
93b13867284ef8b373ac6a6aa3c646e78d3548a72f2ad8432dc1796ca8f24de0
|
|
BLAKE2b-256 checksum How to use checksums |
78f100f05ffd1eb5981038b3a673a494fe9b3f93f0affc3ee3e5d81beb2629b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / fraiseql-1.27.0-cp313-cp313-manylinux_2_38_x86_64.whl
| Download URL | fraiseql-1.27.0-cp313-cp313-manylinux_2_38_x86_64.whl |
|---|---|
| Size | 3.7 MB |
| Tags | CPython 3.13 Linux glibc 2.38+ x86-64 |
|
SHA-256 checksum How to use checksums |
5010087befac8dc5e4d7c30e93bc95e6b0786751486555032a16ce6639e80c98
|
|
BLAKE2b-256 checksum How to use checksums |
f4a0ee39a035636293566ed319d6f57b9281af6d7c18db9b3d1d25963ed00535
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Release files / fraiseql-1.27.0-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | fraiseql-1.27.0-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 3.4 MB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
c9659e975cae3f643d2e204120c1ed503a1fad61434180ba91ff9785a1b3545b
|
|
BLAKE2b-256 checksum How to use checksums |
47616cbe993a52a9e874ef4307004ad8e626c86543668a65a7d87e7d0a28acf2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.3
|
Security for fraiseql 1.27.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
