🦀 Foundational Architecture

PostgreSQL → Rust → HTTP

The Rust pipeline is always active. It performs field selection, snake_case → camelCase transformation, and streams JSON to clients. No ORM, no Python in the data path.

Core layer: Every FraiseQL query uses this. TurboRouter is an optional optimization on top.

Get Started →

The FraiseQL Architecture

Traditional GraphQL

PostgreSQL → Rows

↓ ORM deserialize

Python objects

↓ GraphQL serialize

JSON Response

Multiple steps, object hydration

FraiseQL Architecture

PostgreSQL → JSONB

↓ Rust: field selection

↓ Rust: snake → camelCase

↓ FastAPI: HTTP response

To client

No ORM, no object hydration

Why This Architecture Works

The ORM Problem

Traditional GraphQL frameworks are built on ORMs. ORMs return Python objects, which means:

Double serialization: Database → Python objects → JSON
Memory overhead: Python objects consume more memory than raw data
Complex abstractions: Layers of ORM magic hide what's actually happening
N+1 queries: Requires DataLoader patterns to mitigate

FraiseQL's Database-First Design

FraiseQL is database-first. PostgreSQL returns pre-composed JSONB from projection tables:

Skip object hydration: Rust handles field selection directly on JSONB
Key transformation: Rust converts snake_case → camelCase efficiently
FastAPI HTTP layer: Async Python serves responses (still very fast)
Explicit contracts: No ORM magic, clear data flow

Trinity Identifiers: Smart Data Design

Three Types of Identifiers Per Entity

FraiseQL uses three types of identifiers per entity for different purposes, optimizing for performance, stability, and usability.

pk_* (int): Fast internal joins, PostgreSQL-only, never exposed
id (UUID): Public API stability, exposed, never changes
identifier (str): Human-friendly URLs, SEO, readability

🔧 Internal Performance

-- Fast joins, never exposed
CREATE TABLE tb_user (
    pk_user serial PRIMARY KEY,
    id uuid UNIQUE DEFAULT gen_random_uuid(),
    identifier text UNIQUE,
    email text UNIQUE,
    data jsonb
);

-- Internal operations use pk_*
SELECT * FROM tb_post
WHERE pk_author = 123;

🌐 Public API Stability

# UUIDs for API stability
{
  user(id: "550e8400-e29b-41d4-a716-446655440000") {
    name
    email
  }
}

# Never changes, even if data migrates

👥 Human-Friendly

# SEO-friendly URLs
{
  user(identifier: "john-doe-2024") {
    name
    posts {
      title
    }
  }
}

# Readable, shareable, SEO-optimized

What Rust Actually Does

🎯

Field Selection

Extracts only the fields requested in the GraphQL query from the JSONB document.

🔄

Key Transformation

Converts PostgreSQL snake_case keys to GraphQL camelCase convention.

📤

Memory-Efficient I/O

Processes JSONB without creating Python objects. Predictable memory usage.

Honest Assessment

Rust is not doing heavy computation—the real work is done by PostgreSQL's projection tables. But Rust does give real efficiency in the hot path: no ORM, no object hydration, predictable multi-core concurrency, and memory-efficient JSON slicing. FastAPI handles the HTTP layer and is itself quite fast for async Python.

Architecture Benefits

🔒 Memory Safety

Rust's ownership system prevents buffer overflows, use-after-free bugs, and data races in the JSON processing layer.

The Rust component is memory-safe by design.

🏗️ Clear Data Flow

PostgreSQL → Rust → FastAPI → Client. No hidden ORM queries, no magic. What you see is what executes.

Explicit architecture makes debugging and optimization straightforward.

Simple to Use

FraiseQL - Clean Python, Efficient Execution

# Your Python code stays clean and simple
import fraiseql

@fraiseql.type
class User:
    id: int
    name: str
    posts: list[Post]

@fraiseql.query
async def users(info) -> list[User]:
    # PostgreSQL returns JSONB from projection tables
    # Rust handles field selection and key transformation
    # FastAPI serves the HTTP response
    return await info.context.repo.fetch()

# The Rust adapter is included automatically.
# No configuration needed.

Rust Powers AI Features

🔍 Vector Search

pgvector similarity search results pass through the Rust pipeline for field selection. Sub-millisecond processing for RAG and semantic search.

Learn about pgvector →

🌊 GraphQL Cascade

Cascade metadata filtering uses Rust for <0.5ms field selection, enabling real-time cache updates without performance overhead.

Learn about Cascade →