Getting Started

1. Installation

Install latest stable version

# Using pip
pip install fraiseql

# Or with uv (recommended for faster installs)
uv pip install fraiseql

# Verify installation
python -c "import fraiseql; print(f'FraiseQL {fraiseql.__version__}')"

💡 Tip: The pip install fraiseql command always installs the latest stable version. Check PyPI for version history.

🦀 Rust Extension Included: FraiseQL ships with precompiled Rust binaries for Linux, macOS, and Windows. No Rust compiler needed—the 7-10x faster JSON processing is automatic when you pip install fraiseql.

2. Your First GraphQL API

Define Your GraphQL Types

Create a Python class with type hints. FraiseQL automatically generates the GraphQL schema.

src/types.py

from datetime import datetime
import fraiseql

@fraiseql.type
class User:
    """A user account with authentication and profile information."""
    id: int
    email: fraiseql.EmailAddress
    name: str
    created_at: datetime

Create Projection Table

FraiseQL uses projection tables (tv_*) for fast reads. Pre-computed JSONB means one query, no JOINs.

migrations/001_user_projection.sql

-- Projection table stores pre-computed JSONB
CREATE TABLE tv_user (
    id UUID PRIMARY KEY,
    data JSONB NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Sync function rebuilds from base table
CREATE FUNCTION fn_sync_tv_user(p_id UUID) RETURNS VOID AS $$
BEGIN
    INSERT INTO tv_user (id, data, updated_at)
    SELECT id, jsonb_build_object(
        'id', id,
        'email', email,
        'name', name,
        'createdAt', created_at
    ), NOW()
    FROM tb_user WHERE id = p_id
    ON CONFLICT (id) DO UPDATE SET
        data = EXCLUDED.data,
        updated_at = NOW();
END;
$$ LANGUAGE plpgsql;

💡 Naming conventions: tb_* base tables, v_* simple views, tv_* projection tables, fn_* functions. All views/tables expose id + data JSONB.

Define GraphQL Query

Use the @fraiseql.query decorator to expose a query resolver.

src/queries.py

import fraiseql
from .types import User

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

Start Development Server

FraiseQL includes a built-in development server with hot reload.

Terminal

fraiseql dev
# Server starts at http://localhost:8000/graphql

Test Your API

Open http://localhost:8000/graphql in your browser and run:

GraphQL Query

{
  users {
    id
    name
    email
  }
}

Prerequisites

Python

PostgreSQL

Knowledge

1. Installation

2. Your First GraphQL API

Define Your GraphQL Types

Create Projection Table

Define GraphQL Query

Start Development Server

Test Your API

Next Steps

🏗️ Add Mutations

⚡ Enable APQ

🤖 LLM-Assisted Development

📚 Full Documentation

Ready for Production?