Manual Setup

Tip

Just want to see it work? The 5-Minute Quickstart gets you from zero to a working API with one docker compose up command — no installation required.

Get a FraiseQL GraphQL API running with your own database. 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

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;
}

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
}

Step 4: Configure Your Project

Create fraiseql.toml with your database connection string:

PostgreSQL

fraiseql.toml

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

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

[server]
port = 8080
host = "127.0.0.1"

MySQL

fraiseql.toml

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

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

[server]
port = 8080
host = "127.0.0.1"

SQLite

fraiseql.toml

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

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

[server]
port = 8080
host = "127.0.0.1"

SQL Server

fraiseql.toml

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

[database]
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

Tip

If your schema uses inject_params (e.g., multi-tenant schemas), add --dev-claims '{"tenant_id": "dev"}' to bypass JWT requirements during local development. See Dev Mode.

Your API is now also available via REST and gRPC alongside GraphQL. REST endpoints are served at /rest/v1/ by default when you add rest_path/rest_method annotations to your schema operations. The default path is /rest/v1. Configure with [rest] path to use /api or any other value. gRPC is served on the same port via HTTP/2 content-type negotiation.

To expose an operation via REST, add transport annotations to your query decorator:

@fraiseql.query(
    sql_source="v_post",
    rest_path="/posts",
    rest_method="GET",
)
def posts(limit: int = 10) -> list[Post]: ...

With that annotation in place, both of the following work simultaneously:

# GraphQL (always available)
curl -X POST http://localhost:8080/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ posts { id title } }"}'

# REST (available when rest_path annotation is present)
curl http://localhost:8080/rest/v1/posts

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 →

Sanity check

If anything doesn’t work, run fraiseql doctor to check your schema, config, database connection, and secrets in one step. See the CLI reference for details.

Before going to production

The fraiseql.toml in this guide is a minimal development configuration. Before deploying:

• Enable TLS ([server.tls]) or terminate at your load balancer
• Configure authentication: set JWT_SECRET environment variable
• Set admin_token (or FRAISEQL_ADMIN_TOKEN) to enable and protect the RBAC management API
• Review the production checklist

ServerConfig::default() (used in unit tests and local dev) disables TLS, authentication, and rate limiting. Always use ServerConfig::from_file("fraiseql.toml") in production.

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