Skip to main content

FraiseQL

Quality Gate Documentation Release Python License: MIT

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


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 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 in src/fraiseql/security/profiles/definitions.py). Check a given control before relying on it in production.
  • Everything in PostgreSQL — caching (UNLOGGED tables), 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 in tests/chaos/) against real PostgreSQL, apart from the per-PR suite (strategy).

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.

Metadata

Release files for fraiseql 1.31.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fraiseql 1.31.0
File Size Uploaded Provenance Actions
fraiseql-1.31.0.tar.gz 904.4 kB Without provenance Details for fraiseql-1.31.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fraiseql 1.31.0
File Actions
fraiseql-1.31.0-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for fraiseql-1.31.0-cp314-cp314-win_amd64.whl
fraiseql-1.31.0-cp314-cp314-manylinux_2_38_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.38+ x86-64 Details for fraiseql-1.31.0-cp314-cp314-manylinux_2_38_x86_64.whl
fraiseql-1.31.0-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for fraiseql-1.31.0-cp314-cp314-macosx_11_0_arm64.whl
fraiseql-1.31.0-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for fraiseql-1.31.0-cp313-cp313-win_amd64.whl
fraiseql-1.31.0-cp313-cp313-manylinux_2_38_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.38+ x86-64 Details for fraiseql-1.31.0-cp313-cp313-manylinux_2_38_x86_64.whl
fraiseql-1.31.0-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details for fraiseql-1.31.0-cp313-cp313-macosx_11_0_arm64.whl

Total release size: 22.4 MB

Release files / fraiseql-1.31.0.tar.gz

Download URL fraiseql-1.31.0.tar.gz
Size 904.4 kB
Tags Source
SHA-256 checksum
How to use checksums
28d9aa90facdf304ce73d30025bd0fcf13b6467577c47f2879e8e076eca8c6a8
BLAKE2b-256 checksum
How to use checksums
7a6d81b813dc5a1445a3cefe8632cd78257cb5e29a3e8aa71176145d4e6a6ef6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / fraiseql-1.31.0-cp314-cp314-win_amd64.whl

Download URL fraiseql-1.31.0-cp314-cp314-win_amd64.whl
Size 3.4 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
76d615b2c83bf28dc7b2fc6852cf3835c5975b8cd1a8554acc08a4f53ee75405
BLAKE2b-256 checksum
How to use checksums
9caa9027edf6cae4214c9ffc75e16667795f4abfe4b9e3b9498f020c1a824277
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / fraiseql-1.31.0-cp314-cp314-manylinux_2_38_x86_64.whl

Download URL fraiseql-1.31.0-cp314-cp314-manylinux_2_38_x86_64.whl
Size 3.9 MB
Tags CPython 3.14 Linux glibc 2.38+ x86-64
SHA-256 checksum
How to use checksums
630d70bb7ebd157dccd0f55ed70e057c1bc5de3b9aec68202a523dced987e428
BLAKE2b-256 checksum
How to use checksums
ab865cf3dea1ba0ad5384aacdaaa6f104374900211f6fe4267820c35d3f6fa74
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / fraiseql-1.31.0-cp314-cp314-macosx_11_0_arm64.whl

Download URL fraiseql-1.31.0-cp314-cp314-macosx_11_0_arm64.whl
Size 3.5 MB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
721e6d547ed94a4dd176f8beef3fb43743dd5009aac0ae781e61e19deda31bab
BLAKE2b-256 checksum
How to use checksums
ab9c6d5b9d86a91de515ece3b8f054feb145426a6539b286fb5f1a2fdfc3df89
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / fraiseql-1.31.0-cp313-cp313-win_amd64.whl

Download URL fraiseql-1.31.0-cp313-cp313-win_amd64.whl
Size 3.4 MB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
eebeaebd1354ecde9312e72119b54250ffca2f721c3c944c3b5dee016c690cd5
BLAKE2b-256 checksum
How to use checksums
d9dc1958e6c37102dee7bd12cea155634a30c0ce74bf01edd6454b537c449b54
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / fraiseql-1.31.0-cp313-cp313-manylinux_2_38_x86_64.whl

Download URL fraiseql-1.31.0-cp313-cp313-manylinux_2_38_x86_64.whl
Size 3.9 MB
Tags CPython 3.13 Linux glibc 2.38+ x86-64
SHA-256 checksum
How to use checksums
b5ba20147a3073569a4322122b8ea744a3d347ea486ea5de7c01f90edd148cd7
BLAKE2b-256 checksum
How to use checksums
57d630e8411666313f1d630189dfe2a76f891128de3e08e07efdf4b81301392a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / fraiseql-1.31.0-cp313-cp313-macosx_11_0_arm64.whl

Download URL fraiseql-1.31.0-cp313-cp313-macosx_11_0_arm64.whl
Size 3.5 MB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
07c972daaa6ab0a02acb578f4439a49018951c2322b07a9fc9c0d0544f6158b7
BLAKE2b-256 checksum
How to use checksums
e06feb84e0d3c9a5a27aabb3b8b35bb11537f154d4ad08c843db44d80a9500a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for fraiseql 1.31.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.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.31.0 This release

7 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page