fraiseql
Advanced tools
GraphQL for the LLM era. Simple. Powerful. Rust-fast. Production-ready GraphQL API framework for PostgreSQL with CQRS, JSONB optimization, and type-safe mutations
v1.9.4 | Stable | Rust-Powered GraphQL for PostgreSQL
Python: 3.13+ | PostgreSQL: 13+
PostgreSQL returns JSONB. Rust transforms it. Zero Python overhead.
# Complete GraphQL API in 15 lines
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]
)
where, orderBy, limit, offset added automatically to list queries✅ Perfect if you:
❌ Consider alternatives if:
Traditional GraphQL (slow):
PostgreSQL → Rows → ORM deserialize → Python objects → GraphQL serialize → JSON → Response
╰─── Unnecessary roundtrips (2 conversions) ───╯
FraiseQL (fast):
PostgreSQL → JSONB → Rust field selection → HTTP Response
╰─ Zero Python overhead (1 conversion) ─╯
pip install fraiseql
fraiseql init my-api
cd my-api
fraiseql dev
Your GraphQL API is live at http://localhost:8000/graphql 🎉
Next steps:
class User(Base): # SQLAlchemy
id = Column(Integer)
email = Column(String)
password_hash = Column(String) # ← Sensitive!
api_key = Column(String) # ← Sensitive!
@strawberry.type
class UserType:
id: int
email: str
# Forgot to exclude password_hash and api_key!
Result: One mistake = data leak.
-- PostgreSQL view defines what's exposed
CREATE VIEW v_user AS
SELECT id,
jsonb_build_object('id', id, 'email', email) as data
FROM tb_user;
-- password_hash and api_key aren't in JSONB = impossible to leak
Result: Structure defines the contract. No way to accidentally expose fields.
FraiseQL separates testing into two workflows:
| Aspect | Standard CI/CD | Chaos Engineering |
|---|---|---|
| Duration | 15-20 min | 45-60 min |
| Purpose | Correctness | Resilience |
| Trigger | Every PR | Manual/Weekly |
| Tests | Unit + Integration | 71 chaos scenarios |
| Blocks Merges | Yes ✅ | No (informational) |
| Environment | Lightweight | Real PostgreSQL + Docker |
Standard CI/CD: Validates that features work correctly Chaos Tests: Validates that system recovers from failures
→ Learn about chaos engineering strategy
from fraiseql.types import EmailAddress, PhoneNumber, IPv4, Money, LTree
@fraiseql.type(sql_source="v_users")
class User:
email: EmailAddress # Validated emails
phone: PhoneNumber # International phone numbers
ip: IPv4 # IP addresses with subnet operations
balance: Money # Currency with precision
location: LTree # Hierarchical paths
Three ID types for different purposes:
Automatic cache invalidation when mutations change related data:
mutation {
createPost(input: {...}) {
post { id title }
cascade {
updated { __typename } # What changed
invalidations { queryName } # Which queries to invalidate
}
}
}
| Service | Cost | FraiseQL Approach | Savings |
|---|---|---|---|
| Redis (caching) | $50-500/mo | PostgreSQL UNLOGGED tables | $600-6,000/yr |
| Sentry (error tracking) | $300-3,000/mo | PostgreSQL error logging | $3,600-36,000/yr |
| APM Tool | $100-500/mo | PostgreSQL traces | $1,200-6,000/yr |
| Total | $450-4,000/mo | PostgreSQL only ($50/mo) | $5,400-48,000/yr |
fraiseql sbom generateSTANDARD: Default protections for general applicationsREGULATED: PCI-DSS/HIPAA/SOC 2 complianceRESTRICTED: Government, defence, critical infrastructure
@fraiseql.input
class CreateUserInput:
email: str # AI sees exact input structure
name: str
@fraiseql.success
class UserCreated:
user_id: str # AI sees success response
# Note: @success auto-injects: status, message, updated_fields, id
@fraiseql.error
class ValidationError:
error: str # AI sees failure cases
code: str = "VALIDATION_ERROR"
@fraiseql.mutation(function="fn_create_user", schema="public")
class CreateUser:
input: CreateUserInput
success: UserCreated
failure: ValidationError # Note: Use 'failure' field, not '@failure' decorator
# That's it! FraiseQL automatically:
# 1. Calls public.fn_create_user(input) with input as dict
# 2. Parses JSONB result into UserCreated or ValidationError
Real Impact: Claude Code, GitHub Copilot, and ChatGPT generate correct FraiseQL code on first try.
New to FraiseQL? Understanding these core concepts will help you make the most of the framework:
📚 Concepts & Glossary - Essential terminology and mental models:
pk_*, id, identifier) for performance and UXtv_*) for complex queriesQuick links:
from uuid import UUID
from fraiseql import type, query, mutation, input, success
@fraiseql.type(sql_source="v_note", jsonb_column="data")
class Note:
id: int
title: str
content: str | None
@fraiseql.query
async def notes(info) -> list[Note]:
return await info.context["db"].find("v_note")
@fraiseql.query
async def note(info, id: UUID) -> Note | None:
"""Get a note by ID."""
db = info.context["db"]
return await db.find_one("v_note", id=id)
# Step 3: Define mutations
@fraiseql.input
class CreateNoteInput:
title: str
content: str | None = None
@fraiseql.mutation
class CreateNote:
input: CreateNoteInput
success: Note
app = create_fraiseql_app(
database_url="postgresql://localhost/mydb",
types=[Note],
queries=[notes],
mutations=[CreateNote]
)
-- PostgreSQL view (composable, no N+1)
CREATE VIEW v_user AS
SELECT id,
jsonb_build_object(
'id', id,
'name', name,
'email', email,
'posts', (
SELECT jsonb_agg(...)
FROM tb_post p
WHERE p.user_id = tb_user.id
)
) as data
FROM tb_user;
# Python type mirrors the view
@fraiseql.type(sql_source="v_user", jsonb_column="data")
class User:
id: int
name: str
email: str
posts: list[Post] # Nested relations! No N+1 queries!
# Step 3: Query it
@fraiseql.query
async def users(info) -> list[User]:
db = info.context["db"]
return await db.find("v_user")
No ORM. No complex resolvers. PostgreSQL composes data, Rust transforms it.
CREATE OR REPLACE FUNCTION fn_publish_post(p_post_id UUID) RETURNS JSONB AS $$
DECLARE
v_post RECORD;
BEGIN
-- Get post with user info (Trinity pattern: JOIN on pk_user)
SELECT p.*, u.email as user_email
INTO v_post
FROM tb_post p
JOIN tb_user u ON p.fk_user = u.pk_user -- ✅ Trinity: INTEGER FK to pk_user
WHERE p.id = p_post_id;
-- Validate post exists
IF NOT FOUND THEN
RETURN jsonb_build_object('success', false, 'error', 'Post not found');
END IF;
-- Validate not already published
IF v_post.published_at IS NOT NULL THEN
RETURN jsonb_build_object('success', false, 'error', 'Post already published');
END IF;
-- Update post
UPDATE tb_post
SET published_at = NOW()
WHERE id = p_post_id;
-- Sync projection table
PERFORM fn_sync_tv_post(p_post_id);
-- Log event
INSERT INTO audit_log (action, details)
VALUES ('post_published', jsonb_build_object('post_id', p_post_id, 'user_email', v_post.user_email));
-- Return success
RETURN jsonb_build_object('success', true, 'post_id', p_post_id);
END;
$$ LANGUAGE plpgsql;
Business logic, validation, logging - all in the database function. Crystal clear for humans and AI.
Request only the CASCADE data you need:
mutation CreatePost($input: CreatePostInput!) {
createPost(input: $input) {
post { id title }
# Option 1: No CASCADE (smallest payload)
# Just omit the cascade field
# Option 2: Metadata only
cascade {
metadata { affectedCount }
}
# Option 3: Full CASCADE
cascade {
updated { __typename id entity }
deleted { __typename id }
invalidations { queryName }
metadata { affectedCount }
}
}
}
Performance: Not requesting CASCADE reduces response size by 2-10x.
Replace 4 services with 1 database.
| Traditional Stack | FraiseQL Stack | Annual Savings |
|---|---|---|
| PostgreSQL: $50/mo | PostgreSQL: $50/mo | - |
| Redis Cloud: $50-500/mo | ✅ In PostgreSQL | $600-6,000/yr |
| Sentry: $300-3,000/mo | ✅ In PostgreSQL | $3,600-36,000/yr |
| APM Tool: $100-500/mo | ✅ In PostgreSQL | $1,200-6,000/yr |
| Total: $500-4,050/mo | Total: $50/mo | $5,400-48,000/yr |
Caching (Replaces Redis)
from fraiseql.caching import PostgresCache
cache = PostgresCache(db_pool)
await cache.set("user:123", user_data, ttl=3600)
# Uses PostgreSQL UNLOGGED tables
# - No WAL overhead = fast writes
# - Shared across instances
# - TTL-based expiration
# - Pattern-based deletion
Error Tracking (Replaces Sentry)
from fraiseql.monitoring import init_error_tracker
tracker = init_error_tracker(db_pool, environment="production")
await tracker.capture_exception(error, context={...})
# Features:
# - Automatic error fingerprinting and grouping
# - Full stack trace capture
# - OpenTelemetry trace correlation
# - Custom notifications (Email, Slack, Webhook)
Observability (Replaces APM)
-- All traces and metrics stored in PostgreSQL
SELECT * FROM monitoring.traces
WHERE error_id = 'error-123'
AND trace_id = 'trace-xyz';
Grafana Dashboards
Pre-built dashboards in grafana/ query PostgreSQL directly:
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ GraphQL │ → │ PostgreSQL │ → │ Rust │
│ Request │ │ JSONB Query │ │ Transform │
│ │ │ │ │ (7-10x faster)│
└─────────────────┘ └──────────────────┘ └─────────────────┘
↓
┌─────────────────┐
│ FastAPI │
│ HTTP Response │
└─────────────────┘
Unified path for all queries:
FraiseQL implements Command Query Responsibility Segregation:
┌─────────────────────────────────────┐
│ GraphQL API │
├──────────────────┬──────────────────┤
│ QUERIES │ MUTATIONS │
│ (Reads) │ (Writes) │
├──────────────────┼──────────────────┤
│ v_* views │ fn_* functions │
│ tv_* tables │ tb_* tables │
│ JSONB ready │ Business logic │
└──────────────────┴──────────────────┘
Queries use views:
v_* - Real-time views with JSONB computationtv_* - Denormalized tables with generated JSONB columns (for complex queries)Mutations use functions:
fn_* - Business logic, validation, side effectstb_* - Base tables for data storage📊 Detailed Architecture Diagrams
1. Exclusive Rust Pipeline
2. JSONB Views
3. Table Views (tv_*)
-- Denormalized JSONB table with explicit sync
CREATE TABLE tv_user (
id INT PRIMARY KEY,
data JSONB NOT NULL, -- Regular column, not generated
updated_at TIMESTAMPTZ DEFAULT NOW()
);
-- Sync function populates tv_* from v_* view
CREATE FUNCTION fn_sync_tv_user(p_user_id INT) RETURNS VOID AS $$
BEGIN
INSERT INTO tv_user (id, data)
SELECT id, data FROM v_user WHERE id = p_user_id
ON CONFLICT (id) DO UPDATE SET
data = EXCLUDED.data,
updated_at = NOW();
END;
$$ LANGUAGE plpgsql;
-- Mutations call sync explicitly
CREATE FUNCTION fn_create_user(p_name TEXT) RETURNS JSONB AS $$
DECLARE v_user_id INT;
BEGIN
INSERT INTO tb_user (name) VALUES (p_name) RETURNING id INTO v_user_id;
PERFORM fn_sync_tv_user(v_user_id); -- ← Explicit sync call
RETURN (SELECT data FROM tv_user WHERE id = v_user_id);
END;
$$ LANGUAGE plpgsql;
Benefits: Instant lookups, embedded relations, explicitly synchronized
4. Zero-Copy Response
| Framework | Data Flow | JSON Processing | Recursion Protection | Security Model |
|---|---|---|---|---|
| FraiseQL | PostgreSQL JSONB → Rust → HTTP | ✅ Rust (compiled) | ✅ View-enforced | ✅ Explicit contracts |
| Strawberry + SQLAlchemy | PostgreSQL → ORM → Python dict → JSON | ❌ Python (2 steps) | ⚠️ Middleware required | ❌ ORM over-fetching risk |
| Hasura | PostgreSQL → Haskell → JSON | ⚠️ Haskell | ⚠️ Middleware required | ⚠️ Complex permission system |
| PostGraphile | PostgreSQL → Node.js → JSON | ⚠️ JavaScript | ⚠️ Middleware required | ⚠️ Plugin-based |
Enterprise-grade APQ with pluggable storage backends:
from fraiseql import FraiseQLConfig
# Memory backend (zero configuration)
config = FraiseQLConfig(apq_storage_backend="memory")
# PostgreSQL backend (multi-instance coordination)
config = FraiseQLConfig(
apq_storage_backend="postgresql",
apq_storage_schema="apq_cache"
)
How it works:
Advanced operators for network types, hierarchical data, ranges, and nested arrays:
query {
servers(where: {
ipAddress: { eq: "192.168.1.1" } # → ::inet casting
port: { gt: 1024 } # → ::integer casting
location: { ancestor_of: "US.CA" } # → ltree operations
dateRange: { overlaps: "[2024-01-01,2024-12-31)" }
# Nested array filtering with logical operators
printServers(where: {
AND: [
{ operatingSystem: { in: ["Linux", "Windows"] } }
{ OR: [
{ nTotalAllocations: { gte: 100 } }
{ NOT: { ipAddress: { isnull: true } } }
]
}
]
}) {
hostname operatingSystem
}
}) {
id name ipAddress port
}
}
50+ Specialized Scalar Types:
Financial & Trading:
Network & Infrastructure:
Geospatial & Location:
Business & Logistics:
Technical & Data:
Advanced Filtering: Full-text search, JSONB queries, array operations, regex, vector similarity search on all types
from fraiseql import type
from fraiseql.types import (
EmailAddress, PhoneNumber, Money, Percentage,
CUSIP, ISIN, IPv4, MACAddress, LTree, DateRange
)
@fraiseql.type(sql_source="v_financial_data")
class FinancialRecord:
id: int
email: EmailAddress # Validated email addresses
phone: PhoneNumber # International phone numbers
balance: Money # Currency amounts with precision
margin: Percentage # Percentages (0.00-100.00)
security_id: CUSIP | ISIN # Financial instrument identifiers
@fraiseql.type(sql_source="v_network_device")
class NetworkDevice:
id: int
ip_address: IPv4 # IPv4 addresses with subnet operations
mac_address: MACAddress # MAC addresses with validation
location: LTree # Hierarchical location paths
maintenance_window: DateRange # Date ranges with overlap queries
# Advanced filtering with specialized types
query {
financialRecords(where: {
balance: { gte: "1000.00" } # Money comparison
margin: { between: ["5.0", "15.0"] } # Percentage range
security_id: { eq: "037833100" } # CUSIP validation
}) {
id balance margin security_id
}
networkDevices(where: {
ip_address: { inSubnet: "192.168.1.0/24" } # CIDR operations
location: { ancestor_of: "US.CA.SF" } # LTree hierarchy
maintenance_window: { overlaps: "[2024-01-01,2024-12-31)" }
}) {
id ip_address location
}
}
📖 Nested Array Filtering Guide
from fraiseql import authorized
@fraiseql.authorized(roles=["admin", "editor"])
@fraiseql.mutation
class DeletePost:
"""Only admins and editors can delete posts."""
input: DeletePostInput
success: DeleteSuccess
failure: PermissionDenied
# Features:
# - Field-level authorization with role inheritance
# - Row-level security via PostgreSQL RLS
# - Unified audit logging with cryptographic chain (SHA-256 + HMAC)
# - Multi-tenant isolation
# - Rate limiting and CSRF protection
Three types of identifiers per entity for different purposes:
@fraiseql.type(sql_source="v_post")
class Post(TrinityMixin):
"""
Trinity Pattern:
- pk_post (int): Internal SERIAL key (NOT exposed, only in database)
- id (UUID): Public API key (exposed, stable)
- identifier (str): Human-readable slug (exposed, SEO-friendly)
"""
# GraphQL exposed fields
id: UUID # Public API (stable, secure)
identifier: str | None # Human-readable (SEO-friendly, slugs)
title: str
content: str
# ... other fields
# pk_post is NOT a field - accessed via TrinityMixin.get_internal_pk()
Why three?
# Install
pip install fraiseql
# Create project
fraiseql init my-api
cd my-api
# Setup database
createdb my_api
psql my_api < schema.sql
# Start server
fraiseql dev
Your GraphQL API is live at http://localhost:8000/graphql 🎉
📖 Detailed Installation Guide - Platform-specific instructions, troubleshooting
# Project management
fraiseql init <name> # Create new project
fraiseql dev # Development server with hot reload
fraiseql check # Validate schema and configuration
# Code generation
fraiseql generate schema # Export GraphQL schema
fraiseql generate types # Generate TypeScript definitions
# Database utilities
fraiseql sql analyze <query> # Analyze query performance
fraiseql sql explain <query> # Show PostgreSQL execution plan
git clone https://github.com/fraiseql/fraiseql
cd fraiseql && make setup-dev
prek install # 7-10x faster than pre-commit
FraiseQL is created by Lionel Hamayon (@evoludigit).
The Idea: What if PostgreSQL returned JSON directly instead of Python serializing it? No ORM. No N+1 queries. No Python overhead. Just Rust transforming JSONB to HTTP.
The Result: A GraphQL framework that's 7-10x faster and designed for the LLM era.
MIT License - see LICENSE
MIT License - see LICENSE for details.
| Version | Location | Status | Purpose | For Users? |
|---|---|---|---|---|
| v1.9.4 | Root level | Stable | APQ security fixes + ID Policy configuration | ✅ Production Ready |
| Rust Pipeline | fraiseql_rs/ | Integrated | Included in v1.9.4+ | ✅ Stable |
New to FraiseQL? → First Hour Guide • Project Structure
Ready to build the most efficient GraphQL API in Python?
pip install fraiseql && fraiseql init my-api
🚀 PostgreSQL → Rust → Production
FAQs
GraphQL for the LLM era. Simple. Powerful. Rust-fast. Production-ready GraphQL API framework for PostgreSQL with CQRS, JSONB optimization, and type-safe mutations
We found that fraiseql demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh joins Insecure Agents to discuss CVE remediation and why supply chain attacks require a different security approach.
Security News
Tailwind Labs laid off 75% of its engineering team after revenue dropped 80%, as LLMs redirect traffic away from documentation where developers discover paid products.
Security News
The planned feature introduces a review step before releases go live, following the Shai-Hulud attacks and a rocky migration off classic tokens that disrupted maintainer workflows.