FastAPI-Native Integration

Why FastAPI?

FraiseQL isn't just compatible with FastAPI—it's built for FastAPI. This opinionated choice aligns performance, architecture, and developer experience around a common philosophy: speed, type safety, and clarity.

Benefit	Why It Matters	Result
Async-First	Both FraiseQL and FastAPI built on async/await	✅ Fully non-blocking stack
Minimal Overhead	FastAPI adds <0.5ms, FraiseQL adds <0.1ms	✅ Sub-50ms responses
Type Safety	Pydantic + Python 3.13+ type hints	✅ Catch errors at dev time
CQRS Architecture	Database-layer separation (Views/Functions)	✅ Queries → Views, Mutations → Functions
LLM-Optimized	Explicit types, decorators, DI patterns	✅ AI-assisted development

How It Works

1. Define Your Schema

import fraiseql
from uuid import UUID

@fraiseql.type
class User:
    """User account.

    Fields:
        id: Unique identifier
        username: Display name
        email: Contact email
    """
    id: UUID
    username: str
    email: str

@fraiseql.query
async def users(info) -> list[User]:
    """Get all users."""
    db = info.context["db"]
    return await db.find("users")

@fraiseql.mutation
async def create_user(
    info,
    username: str,
    email: str
) -> User:
    """Create new user."""
    db = info.context["db"]
    user_id = await db.insert(
        "users",
        {"username": username, "email": email}
    )
    return await db.find_one(
        "users", id=user_id
    )

2. Create FastAPI App

from fraiseql.fastapi import (
    create_fraiseql_app
)

# Create complete app
app = create_fraiseql_app(
    database_url="postgresql://...",
    types=[User],
    mutations=[create_user],
    queries=[users],
    title="My API",
    production=False
)

# FastAPI instance ready
# /graphql endpoint configured

3. Run and Query

# Start server
import uvicorn
uvicorn.run(
    app,
    host="0.0.0.0",
    port=8000
)

# Query (POST /graphql)
query {
  users {
    id
    username
    email
  }
}

# Mutation (POST /graphql)
mutation {
  createUser(
    username: "alice"
    email: "alice@example.com"
  ) {
    id
    username
  }
}

Key Benefits

⚡

Performance Alignment

Async/await throughout. FastAPI + FraiseQL + asyncpg = fully non-blocking, sub-50ms responses.

🏗️

Database-Layer CQRS

GraphQL queries execute PostgreSQL Views, mutations execute Functions. True separation of concerns at the database level.

🤖

LLM-Optimized

Explicit type hints, decorator patterns, dependency injection. AI tools understand and generate code confidently.

🔧

Dependency Injection

FastAPI's DI system integrates seamlessly. Clean, testable, maintainable code.

📊

Auto-Documentation

OpenAPI schema + GraphQL schema. Your API is self-documenting out of the box.

🎯

Type Safety

Pydantic models + Python 3.13+ type hints. Catch errors before deployment.

LLM-Optimized Development

FraiseQL + FastAPI is designed for the AI-assisted development era. Here's why Claude, Copilot, and other LLMs excel with this stack:

1. Explicit Type Hints

LLMs understand intent from function signatures

@fraiseql.query
async def user(
    info, id: UUID
) -> User | None:
    """Get user by ID.

    Returns:
        User if found, else None
    """
    db = info.context["db"]
    return await db.find_one(
        "users", id=id
    )

2. Decorator Patterns + Docstrings

Self-documenting code with clear, repeatable patterns

@fraiseql.type
class Post:
    """Blog post.

    Fields:
        id: Unique identifier
        title: Post headline
        author_id: Ref to User.id
    """
    id: UUID
    title: str
    author_id: UUID

3. Input Validation

Clear contracts with documented fields

@fraiseql.input
class CreatePostInput:
    """Input for new post.

    Fields:
        title: Headline
        content: Post body
        tags: Optional tags
    """
    title: str
    content: str
    tags: list[str] | None = None

4. Result Types

LLMs understand success/error shapes from type signatures

@fraiseql.mutation
async def create_post(
    info,
    input: CreatePostInput
) -> CreatePostSuccess | CreatePostError:
    """Create new post.

    Returns:
        Success with post or Error
    """
    db = info.context["db"]
    # Validation logic...
    return CreatePostSuccess(
        post=new_post
    )

✅ AI tools generate correct, maintainable code

The FastAPI + FraiseQL Philosophy

Every layer of the stack is opinionated for the same goals:

Client

GraphQL Query/Mutation (POST /graphql)

FastAPI

Async HTTP server, type-safe routing

FraiseQL

GraphQL schema → PostgreSQL translator

PostgreSQL

Views for reads, Functions for writes

TurboRouter

Zero-copy JSONB passthrough