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

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.2
File Size Uploaded Provenance Actions
fraiseql-1.31.2.tar.gz 916.3 kB Without provenance Details for fraiseql-1.31.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fraiseql 1.31.2
File Actions
fraiseql-1.31.2-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for fraiseql-1.31.2-cp314-cp314-win_amd64.whl
fraiseql-1.31.2-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.2-cp314-cp314-manylinux_2_38_x86_64.whl
fraiseql-1.31.2-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for fraiseql-1.31.2-cp314-cp314-macosx_11_0_arm64.whl
fraiseql-1.31.2-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for fraiseql-1.31.2-cp313-cp313-win_amd64.whl
fraiseql-1.31.2-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.2-cp313-cp313-manylinux_2_38_x86_64.whl
fraiseql-1.31.2-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details for fraiseql-1.31.2-cp313-cp313-macosx_11_0_arm64.whl

Total release size: 22.4 MB

Release files / fraiseql-1.31.2.tar.gz

Download URL fraiseql-1.31.2.tar.gz
Size 916.3 kB
Tags Source
SHA-256 checksum
How to use checksums
37220d6524694c0cb0a5a4246c60cb71ab95cda06c61104f30957fe7f4d0c7d6
BLAKE2b-256 checksum
How to use checksums
f0e4efef62e1d887ea494d280bf607e6d916a701ddae764fe26a684c1b5c4a23
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.2-cp314-cp314-win_amd64.whl

Download URL fraiseql-1.31.2-cp314-cp314-win_amd64.whl
Size 3.4 MB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
d2f0592e42fe62c9711c7ef74a984567a1768f729722742b786779fc69edebe9
BLAKE2b-256 checksum
How to use checksums
026435b413c8b7eabbcf2712ea6df0c88836fa1049be40d1eaf23b638be7ff38
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.2-cp314-cp314-manylinux_2_38_x86_64.whl

Download URL fraiseql-1.31.2-cp314-cp314-manylinux_2_38_x86_64.whl
Size 3.8 MB
Tags CPython 3.14 Linux glibc 2.38+ x86-64
SHA-256 checksum
How to use checksums
6de69fcafac897bc619b5df5f9a6703168ba6c79c242367b75d4f902962340d5
BLAKE2b-256 checksum
How to use checksums
2a78c2a19ee7f38d51bc5108857c218fd1dd4e881561ce4a160f375ab4250088
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.2-cp314-cp314-macosx_11_0_arm64.whl

Download URL fraiseql-1.31.2-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
2d043a5e3f02073a87fe40245942ee8ddb704a13e16224d8e3ee809734756666
BLAKE2b-256 checksum
How to use checksums
ab6f3ec32c72bb605f61f82a3fc54fa3a221643d1631c4f236cd43fff5370fc2
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.2-cp313-cp313-win_amd64.whl

Download URL fraiseql-1.31.2-cp313-cp313-win_amd64.whl
Size 3.4 MB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
c8c1177be74c07e6d843f535afdb31f20083b4855789a3615bef3e41930b96cc
BLAKE2b-256 checksum
How to use checksums
e114606767d5d481e27462fdbf03174846f78536f3e208a9af854a67085c4d40
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.2-cp313-cp313-manylinux_2_38_x86_64.whl

Download URL fraiseql-1.31.2-cp313-cp313-manylinux_2_38_x86_64.whl
Size 3.8 MB
Tags CPython 3.13 Linux glibc 2.38+ x86-64
SHA-256 checksum
How to use checksums
f6cf17f62c5a9b620d193052859e7e19106a18294a0c3f0877fa0274dc1a84ae
BLAKE2b-256 checksum
How to use checksums
78f7c31fe91910e9cd8d80892f4a579483bba2abeb368cf0212aa464640b4925
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.2-cp313-cp313-macosx_11_0_arm64.whl

Download URL fraiseql-1.31.2-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
5376ebfc3c703a9424daf685891bc243889f0326a3fbf9b4225b6e55dc61d248
BLAKE2b-256 checksum
How to use checksums
1c2c14b06cd98df1a269d17eddd6d6518d5392f4b3d2bc48aef6d3e3113f603c
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.2

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