Introduction

FraiseQL is a database-first GraphQL framework. You write SQL views, FraiseQL maps them to GraphQL types, and every query resolves to a single SQL statement. No resolvers. No N+1. No magic.

FraiseQL serves three API transports from a single compiled schema: GraphQL, REST, and gRPC. You author the schema once in your preferred language, compile it, and run a single Rust binary that handles all three simultaneously.

One schema, three transports

Traditional approach:

• GraphQL service (Node.js/Go)
• REST API service (separate codebase)
• gRPC service (separate codebase)
• Three deployment units, three maintenance burdens

FraiseQL:

• One schema definition (Python, TypeScript, Go, and 8 more languages)
• One fraiseql compile step
• One Rust binary serving GraphQL + REST + gRPC

The Python API is the primary schema authoring layer. For teams that prefer a TOML-first workflow, SpecQL is an optional companion tool that compiles TOML schema definitions to FraiseQL Python decorators, with 56 built-in semantic scalar types (Email, IBAN, Money, and more).

The Problem with Traditional GraphQL

Traditional GraphQL frameworks require you to:

1. Write resolvers for every field and relationship
2. Handle N+1 queries manually with DataLoaders
3. Tune performance at runtime with caching layers
4. Debug surprises that only appear in production

This leads to boilerplate code, runtime unpredictability, and hours spent debugging performance issues.

The FraiseQL Approach

FraiseQL compiles the relationship between GraphQL types and SQL views at build time. At runtime, a GraphQL query becomes a single SQL statement — not a cascade of resolver calls.

Traditional GraphQL	FraiseQL
Write resolver functions	Write SQL views
Handle N+1 with DataLoaders	N+1 eliminated by design
Tune performance at runtime	Performance compiled in
YAML / JSON configuration	TOML you can read
Debug resolver chains	Debug SQL — you own it

How It Works

1. Write tables and views in SQL for your database.

   CREATE VIEW v_post AS
   SELECT
     p.id,
     jsonb_build_object(
       'id',      p.id::text,
       'title',   p.title,
       'author',  vu.data
     ) AS data
   FROM tb_post p
   JOIN tb_user u ON u.pk_user = p.fk_user
   JOIN v_user vu ON vu.id = u.id;

2. Define types in your preferred language.

   Python

   @fraiseql.type
   class Post:
       id: ID
       title: str
       author: User

   TypeScript

   import { Type } from 'fraiseql';
   
   @Type()
   class Post {
     id: string;
     title: string;
     author: User;
   }

   Go

   type Post struct {
     ID     string `fraiseql:"id"`
     Title  string `fraiseql:"title"`
     Author User   `fraiseql:"author"`
   }

3. Configure with a single TOML file.

   fraiseql.toml

   [project]
   name = "my-api"
   database_target = "postgresql"
   
   [database]
   url  = "${DATABASE_URL}"
   
   [server]
   port = 8080

4. Build and serve.

   fraiseql compile
   fraiseql run

   Your GraphQL API is live. Every query resolves to the SQL view you wrote.

Key Features

Any Database

PostgreSQL, MySQL, SQLite, and SQL Server. Full multi-database support with database-specific optimizations.

Any Language

Define schemas in Python, TypeScript, Go, Java, Rust, PHP, C#, Elixir, F#, Ruby, and Dart. All compile to the same output.

No N+1 by Design

SQL views pre-join relationships. FraiseQL never issues N+1 queries — it’s architecturally impossible.

Compile-Time Validation

Built-in validators catch errors at build time. Invalid schemas cannot be deployed.

You Own the SQL

You write the views. You see the query that runs. Full debuggability and control.

Rust Performance

Sub-millisecond query routing. The binary is a single compiled executable with no runtime dependencies.

Database Support

FraiseQL supports four databases:

Database	Status	Notes
PostgreSQL	✅ Recommended	Best JSONB support, row-level security, full-text search
MySQL	✅ Supported	JSON column support, MySQL 8.0+
SQLite	✅ Supported	Ideal for development and embedded use
SQL Server	✅ Supported	FOR JSON PATH, SQL Server 2019+
Oracle	❌ Not supported	No plans to add support

When to Use FraiseQL

FraiseQL is ideal when you need:

• High performance — query latency driven by SQL, not resolver chains
• Predictability — deterministic, compiled behavior; no runtime surprises
• SQL ownership — your team writes and reviews the queries that run
• Rapid development — no resolver boilerplate to write or maintain

When NOT to Use FraiseQL

FraiseQL isn’t the right tool for every use case. Consider alternatives if you need:

• Complex business logic in resolvers — FraiseQL is database-first; intricate middleware logic belongs in a service layer
• GraphQL federation across microservices — FraiseQL federates databases, not arbitrary services
• Oracle — explicitly not supported

Next Steps

5-Minute Quickstart

Zero to a working API with one command

Manual Setup

Install locally and connect your database

Full Tutorial

Build a complete blog API step by step

How It Works

Understand the architecture and SQL view pattern