Quick Start

Get a FraiseQL GraphQL API running in 5 minutes. This guide assumes you have a PostgreSQL database with tables already set up. For the full workflow including database setup with 🍯 Confiture, see Your First API.

Prerequisites

• PostgreSQL database with tables created
• Your preferred schema language installed (Python 3.10+, Node.js 18+, or Go 1.21+)

Step 1: Install FraiseQL

FraiseQL is a Rust binary. Install it once, use it from any project regardless of language.

# Install script (macOS / Linux)
curl -fsSL https://fraiseql.dev/install.sh | sh

# Homebrew (macOS)
brew install fraiseql

# From source (requires Rust toolchain)
cargo install fraiseql

Verify:

fraiseql --version

Step 1b: Install the Schema SDK

The schema SDK lets you define GraphQL types in your preferred language using decorators or structs.

Python

uv add fraiseql
# or: pip install fraiseql

TypeScript

npm install fraiseql
# or: pnpm add fraiseql

Go

go get github.com/fraiseql/fraiseql-go

Step 2: Write Your SQL Views

Tip

The tb_/v_/fn_ prefixes aren’t mandatory, but FraiseQL uses them to find your objects automatically. fraiseql compile scans for views matching v_{query_name} and functions matching fn_{mutation_name}. If you already have a different naming convention, you can override it with sql_source="my_posts_view" on the decorator — but following the convention means less config everywhere.

Create SQL views that follow the .data JSONB pattern. Each view has an id column and a data column:

PostgreSQL

db/schema/02_read/v_user.sql

CREATE VIEW v_user AS
SELECT
    u.id,
    jsonb_build_object(
        'id', u.id::text,
        'name', u.name,
        'email', u.email,
        'created_at', u.created_at
    ) AS data
FROM tb_user u;

db/schema/02_read/v_post.sql

CREATE VIEW v_post AS
SELECT
    p.id,
    jsonb_build_object(
        'id', p.id::text,
        'title', p.title,
        'content', p.content,
        '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;

MySQL

db/schema/02_read/v_user.sql

CREATE VIEW v_user AS
SELECT
    u.id,
    JSON_OBJECT(
        'id', u.id,
        'name', u.name,
        'email', u.email,
        'created_at', u.created_at
    ) AS data
FROM tb_user u;

db/schema/02_read/v_post.sql

CREATE VIEW v_post AS
SELECT
    p.id,
    JSON_OBJECT(
        'id', p.id,
        'title', p.title,
        'content', p.content,
        '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;

SQLite

db/schema/02_read/v_user.sql

CREATE VIEW v_user AS
SELECT
    u.id,
    json_object(
        'id', u.id,
        'name', u.name,
        'email', u.email,
        'created_at', u.created_at
    ) AS data
FROM tb_user u;

db/schema/02_read/v_post.sql

CREATE VIEW v_post AS
SELECT
    p.id,
    json_object(
        'id', p.id,
        'title', p.title,
        'content', p.content,
        '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;

SQL Server

db/schema/02_read/v_user.sql

CREATE VIEW dbo.v_user
WITH SCHEMABINDING AS
SELECT
    u.id,
    (
        SELECT u.id, u.name, u.email, u.created_at
        FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
    ) AS data
FROM dbo.tb_user u;

db/schema/02_read/v_post.sql

CREATE VIEW dbo.v_post
WITH SCHEMABINDING AS
SELECT
    p.id,
    (
        SELECT p.id, p.title, p.content, vu.data AS author
        FOR JSON PATH, WITHOUT_ARRAY_WRAPPER
    ) AS data
FROM dbo.tb_post p
JOIN dbo.tb_user u ON u.pk_user = p.fk_user
JOIN dbo.v_user vu ON vu.id = u.id;

Apply these views to your database (or use confiture build — see 🍯 Confiture).

Step 3: Define Your GraphQL Schema

Python

Create a file called schema.py:

schema.py

import fraiseql
from fraiseql.scalars import ID, Email, DateTime

@fraiseql.type
class User:
    """A user in the system."""
    id: ID
    name: str
    email: Email
    created_at: DateTime

@fraiseql.type
class Post:
    """A blog post."""
    id: ID
    title: str
    content: str
    author: User
    published: bool

TypeScript

Create a file called schema.ts:

schema.ts

import { type } from 'fraiseql';
import { ID, Email, DateTime } from 'fraiseql/scalars';

@type()
class User {
  /** A user in the system. */
  id: ID;
  name: string;
  email: Email;
  createdAt: DateTime;
}

@type()
class Post {
  /** A blog post. */
  id: ID;
  title: string;
  content: string;
  author: User;
  published: boolean;
}

Go

Create a file called schema.go:

schema.go

package schema

import "github.com/fraiseql/fraiseql-go/scalars"

// User represents a user in the system.
type User struct {
    ID        scalars.ID       `fraiseql:"type"`
    Name      string
    Email     scalars.Email
    CreatedAt scalars.DateTime
}

// Post represents a blog post.
type Post struct {
    ID        scalars.ID `fraiseql:"type"`
    Title     string
    Content   string
    Author    User
    Published bool
}

Step 4: Configure Your Project

Create fraiseql.toml with your database connection string:

PostgreSQL

fraiseql.toml

[project]
name = "quickstart"
version = "0.1.0"

[database]
type = "postgresql"
url = "postgresql://localhost:5432/mydb"

[server]
port = 8080
host = "127.0.0.1"

MySQL

fraiseql.toml

[project]
name = "quickstart"
version = "0.1.0"

[database]
type = "mysql"
url = "mysql://localhost:3306/mydb"

[server]
port = 8080
host = "127.0.0.1"

SQLite

fraiseql.toml

[project]
name = "quickstart"
version = "0.1.0"

[database]
type = "sqlite"
url = "sqlite://./mydb.db"

[server]
port = 8080
host = "127.0.0.1"

SQL Server

fraiseql.toml

[project]
name = "quickstart"
version = "0.1.0"

[database]
type = "sqlserver"
url = "sqlserver://localhost:1433;Database=mydb;Trusted_Connection=true"

[server]
port = 8080
host = "127.0.0.1"

Step 5: Compile and Serve

# Compile the mapping between your types and SQL views
fraiseql compile

# Start the server
fraiseql run

You should see:

✓ Compiled 2 types → mapped to SQL views
✓ Built query executor
→ GraphQL API running at http://localhost:8080/graphql

Step 6: Query Your API

Open your browser to http://localhost:8080/graphql or use curl:

curl -s -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ users { id name email } }"}' | jq .

Response:

{
  "data": {
    "users": [
      {
        "id": "1",
        "name": "Alice",
        "email": "alice@example.com"
      }
    ]
  }
}

If a query references a field that doesn’t exist, FraiseQL returns a structured error:

{
  "errors": [
    {
      "message": "Cannot query field 'phone' on type 'User'",
      "locations": [{ "line": 1, "column": 28 }]
    }
  ]
}

What Just Happened?

1. SQL views created — You wrote views following the .data JSONB pattern
2. Schema compiled — FraiseQL mapped your GraphQL types to those SQL views
3. Query executor built — Pre-compiled query paths for each type
4. API served — Every GraphQL query resolves to a single SQL statement

No resolvers. No N+1 problems. No generated SQL you can’t read.

Try It Without Installing

Query the same schema — users, posts, comments, tags — against a live FraiseQL server backed by real PostgreSQL. No account required.

FraiseQL Demo API

Try the schema from this guide against a live server.

Loading Apollo Sandbox...

This sandbox uses Apollo Sandbox (the same GraphQL IDE as fraiseql serve). Your queries execute against the endpoint below. No data is sent to Apollo. Learn more about privacy →

Next Steps

• Your First API — Build a complete blog API with 🍯 Confiture
• Developer-Owned SQL — Why you write the views
• TOML Configuration — All configuration options
• Schema Definition — Advanced schema patterns