TOML Configuration

FraiseQL uses a single fraiseql.toml file for all project configuration. Secrets (database passwords, JWT keys) stay in environment variables — the TOML file references them by name.

Config Stability

Section	Since	Stability
[project]	—	Stable
[database]	—	Stable
[server]	—	Stable
[server.cors]	—	Stable
[server.tls]	—	Stable
[fraiseql]	—	Stable
[caching]	—	Stable
[mcp]	—	Stable
[query_defaults]	—	Stable
[security]	—	Stable
[security.enterprise]	—	Stable
[security.error_sanitization]	—	Stable
[security.constant_time]	—	Stable
[security.rate_limiting]	—	Stable
[security.state_encryption]	—	Stable
[security.pkce]	—	Stable
[security.api_keys]	—	Stable
[security.token_revocation]	—	Stable
[security.trusted_documents]	—	Stable
[validation]	—	Stable
[subscriptions]	—	Stable
[analytics]	—	Stable
[debug]	—	Stable
[federation]	—	Stable
[observers]	—	Stable
[tracing]	2.1.0	Stable
[server.limits]	2.1.0	Stable
[rest]	v2.1	Stable
[grpc]	v2.1	Stable
[session_variables]	v2.1	Stable
[inject_defaults]	v2.1	Stable
[cascade]	v2.1	Stable
[dev]	v2.2	Stable
[gateway]	v2.1	Stable

File Location

my-project/
├── fraiseql.toml
├── schema.json
└── db/

Minimal Configuration

Generated by fraiseql init. The only required fields are the database URL reference and schema path.

[project]
name = "my-api"
version = "0.1.0"
database_target = "postgresql"

[database]
url = "${DATABASE_URL}"

[fraiseql]
schema_file = "schema.json"
output_file = "schema.compiled.json"

Run with:

DATABASE_URL="postgresql://localhost:5432/mydb" fraiseql run

CLI Flag Overrides

Every TOML value can be overridden at runtime with a CLI flag or environment variable. CLI flags take precedence over environment variables, which take precedence over TOML.

# Override port at runtime without changing fraiseql.toml
fraiseql run --port 9000

# Environment variable override (FRAISEQL_ prefix, __ for nesting)
FRAISEQL_SERVER__PORT=9000 fraiseql run

TOML key	Environment variable
server.port	FRAISEQL_SERVER__PORT
server.host	FRAISEQL_SERVER__HOST
database.url	DATABASE_URL or FRAISEQL_DATABASE__URL
database.pool_max	FRAISEQL_DATABASE__POOL_MAX

---

Sections

[project]

Project metadata used during compilation.

[project]
name = "my-api"
version = "1.0.0"
description = "My GraphQL API"
database_target = "postgresql"

Field	Type	Default	Description
name	string	"my-fraiseql-app"	Project identifier
version	string	"1.0.0"	Semantic version
description	string	—	Human-readable description
database_target	string	—	Optional. postgresql, mysql, sqlite, sqlserver

---

[database]

Database connection and connection pool settings. Never put credentials directly in this file — use ${ENV_VAR} references.

[database]
url = "${DATABASE_URL}"
pool_min = 2
pool_max = 20
connect_timeout_ms = 5000
idle_timeout_ms = 600000
ssl_mode = "prefer"

Field	Type	Default	Description
url	string	—	Connection URL or env var reference
pool_min	integer	2	Minimum pool connections
pool_max	integer	20	Maximum pool connections
connect_timeout_ms	integer	5000	Connection acquisition timeout in ms
idle_timeout_ms	integer	600000	Idle connection lifetime in ms
ssl_mode	string	"prefer"	disable, allow, prefer, or require

Env var reference syntax:

url = "${DATABASE_URL}"                              # Required env var
url = "${DATABASE_URL:-postgresql://localhost/mydb}" # With fallback

---

[server]

HTTP server binding and request handling.

[server]
host        = "0.0.0.0"
port        = 8080
request_timeout_ms = 30000
keep_alive_secs    = 75
admin_token = "${FRAISEQL_ADMIN_TOKEN}"  # protects RBAC management + admin API
admin_api_enabled = true                 # enable /api/v1/admin/* endpoints
admin_readonly_token = "${FRAISEQL_ADMIN_READONLY_TOKEN}"  # optional: read-only admin access

Field	Type	Default	Description
host	string	"0.0.0.0"	Bind address
port	integer	8080	Listen port
request_timeout_ms	integer	30000	Request timeout in ms
keep_alive_secs	integer	75	TCP keep-alive in seconds
admin_token	string	—	Bearer token protecting /api/rbac/* and /api/v1/admin/* write endpoints. If not set, both the RBAC management API and admin API are disabled entirely (endpoints return 404). Use FRAISEQL_ADMIN_TOKEN env var. Minimum 32 characters.
admin_api_enabled	bool	false	Enable admin API endpoints (/api/v1/admin/*) for schema reload, cache management, and diagnostics. Requires admin_token to be set.
admin_readonly_token	string	—	Separate bearer token for admin read-only endpoints (cache stats, config, explain). Falls back to admin_token if not set. Use FRAISEQL_ADMIN_READONLY_TOKEN env var. Minimum 32 characters.

[server.cors]

Cross-Origin Resource Sharing. Required when your frontend is served from a different origin.

[server.cors]
origins = ["https://app.example.com", "http://localhost:3000"]
credentials = true

Field	Type	Default	Description
origins	array	[]	Allowed origins (empty = all origins)
credentials	bool	false	Allow cookies and auth headers

[server.tls]

TLS termination. For most deployments, terminate TLS at the load balancer and run fraiseql on plain HTTP internally.

[server.tls]
enabled = true
cert_file = "/etc/ssl/certs/server.pem"
key_file  = "/etc/ssl/private/server.key"
min_version = "1.2"

Field	Type	Default	Description
enabled	bool	false	Enable TLS
cert_file	string	—	Path to certificate file (PEM)
key_file	string	—	Path to private key file (PEM)
min_version	string	"1.2"	Minimum TLS version: "1.2" or "1.3"

---

[fraiseql]

Compilation settings.

[fraiseql]
schema_file = "schema.json"
output_file = "schema.compiled.json"

Field	Type	Default	Description
schema_file	string	"schema.json"	Path to the schema definition
output_file	string	"schema.compiled.json"	Path for the compiled output

[rest]

Note

Available since v2.1. Requires the rest-transport Cargo feature. REST endpoints are derived from queries and mutations at compile time using CQRS naming conventions. Override auto-derived routes with explicit rest_path / rest_method annotations.

[rest]
enabled = true
path = "/rest/v1"                # base path for all REST routes
require_auth = false             # require OIDC/JWT for all REST endpoints
include = []                     # whitelist operations by name (empty = all)
exclude = []                     # blacklist operations by name
delete_response = "no_content"   # "no_content" (204) or "entity" (200 + body)
max_page_size = 100              # maximum limit value for pagination
default_page_size = 20           # default limit when not specified
etag = true                      # enable ETag / If-None-Match conditional requests
max_filter_bytes = 4096          # maximum size of ?filter= JSON param
max_embedding_depth = 3          # max nesting for ?select=posts(comments(...))
openapi_enabled = false          # serve OpenAPI 3.0.3 spec
openapi_path = "/rest/v1/openapi.json"  # path for OpenAPI spec endpoint
title = "My API"                 # OpenAPI info.title
api_version = "1.0.0"           # OpenAPI info.version

Field	Type	Default	Description
enabled	bool	true	Enable/disable REST transport. Default: true when the rest-transport Cargo feature is active.
path	string	"/rest/v1"	Base URL path for all REST routes
require_auth	string	false	Require OIDC/JWT authentication for all REST endpoints
include	array	[]	Whitelist of operation names to expose (empty = all)
exclude	array	[]	Blacklist of operation names to hide from REST
delete_response	string	"no_content"	Default DELETE response: "no_content" (204) or "entity" (200 with body). Per-request override via Prefer: return=minimal or Prefer: return=representation header.
max_page_size	integer	100	Maximum allowed limit value. Requests exceeding this are clamped.
default_page_size	integer	20	Default limit when not specified in the request
etag	bool	true	Enable ETag and If-None-Match conditional request support (xxHash64)
max_filter_bytes	integer	4096	Maximum size in bytes for the ?filter= JSON query parameter
max_embedding_depth	integer	3	Maximum nesting depth for ?select=posts(comments(...)) embedding
openapi_enabled	bool	false	Serve OpenAPI 3.0.3 spec at openapi_path
openapi_path	string	"/rest/v1/openapi.json"	Path for the OpenAPI spec endpoint
title	string	"FraiseQL REST API"	OpenAPI info.title
api_version	string	"1.0.0"	OpenAPI info.version
max_bulk_affected	integer	1000	Maximum rows a bulk mutation can affect
default_cache_ttl	integer	60	Default Cache-Control: max-age for GET responses (seconds)
cdn_max_age	integer	—	s-maxage value for CDN proxies (seconds). Omitted from header if unset.
idempotency_ttl_seconds	integer	86400	How long idempotency keys are retained

[grpc]

Note

Available since v2.1. Requires the grpc-transport Cargo feature. When enabled, gRPC endpoints are auto-generated for all queries and mutations. Use fraiseql compile --output-proto to generate the .proto file for gRPC clients.

[grpc]
enabled = true
port = 50052
reflection = true
max_message_size_bytes = 4194304
descriptor_path = "proto/descriptor.binpb"
stream_batch_size = 500
# include_types = ["User", "Post"]
# exclude_types = ["InternalAudit"]

Field	Type	Default	Description
enabled	bool	false	Enable gRPC transport
port	integer	50052	gRPC listen port (separate from the HTTP server)
reflection	bool	true	Enable gRPC server reflection for grpcurl / gRPC UI discovery
max_message_size_bytes	integer	4194304	Maximum inbound message size in bytes (4 MiB)
descriptor_path	string	"proto/descriptor.binpb"	Path to the compiled FileDescriptorSet binary
stream_batch_size	integer	500	Rows per batch in server-streaming RPCs (list queries)
include_types	string[]	[]	Whitelist of type names to expose as gRPC services (empty = all)
exclude_types	string[]	[]	Blacklist of type names to hide from gRPC services

gRPC runs on a separate port (default 50052) from the HTTP server.

---

[tracing]

Distributed tracing and OTLP export. OpenTelemetry tracing is compiled into the server by default — zero overhead when no endpoint is configured (no gRPC connection attempt).

[tracing]
enabled              = true       # default: true
level                = "info"     # log level filter: error | warn | info | debug | trace
format               = "json"    # log format: json | pretty
service_name         = "fraiseql" # service name for distributed tracing
otlp_endpoint        = "http://otel-collector:4317"  # OTLP exporter endpoint
otlp_export_timeout_secs = 10    # OTLP exporter timeout in seconds

Field	Type	Default	Description
enabled	bool	true	Enable tracing and structured logging
level	string	"info"	Log level filter: error, warn, info, debug, trace
format	string	"json"	Log output format: "json" (production) or "pretty" (development)
service_name	string	"fraiseql"	Service name for distributed tracing spans
otlp_endpoint	string	—	OTLP exporter endpoint (e.g. "http://otel-collector:4317"). When not set, falls back to the OTEL_EXPORTER_OTLP_ENDPOINT environment variable. If neither is set, no OTLP export occurs.
otlp_export_timeout_secs	integer	10	How long the OTLP exporter waits for a collector response before timing out

Tip

You can mix TOML and environment variables. The OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME standard OpenTelemetry env vars still work as fallbacks when the corresponding TOML fields are omitted.

---

[server.limits]

Per-request body size, timeout, and concurrency limits. These control the admission controller that protects the server from overload.

[server.limits]
max_request_size        = "10MB"  # maximum request body size
request_timeout         = "30s"   # per-request processing timeout
max_concurrent_requests = 1000    # simultaneous requests in flight
max_queue_depth         = 5000    # requests waiting in the accept queue

Field	Type	Default	Description
max_request_size	string	"10MB"	Maximum allowed request body size (human-readable, e.g. "10MB", "512KB")
request_timeout	string	"30s"	Maximum time to process a single request (e.g. "30s", "5m")
max_concurrent_requests	integer	1000	Maximum requests processed simultaneously. Excess requests are queued.
max_queue_depth	integer	5000	Maximum requests waiting in the accept queue. Requests beyond this limit receive 503 Service Unavailable.

Caution

When max_concurrent_requests permits are exhausted, new requests queue up to max_queue_depth. If the queue also fills, the server sheds load by returning 503. Monitor fraiseql_http_responses_5xx for sustained 503 spikes — this indicates you need more replicas or a higher concurrency limit.

---

[caching]

Caution

The [caching] section has not been fully verified against the FraiseQL engine and may cause unexpected behavior. Cache is disabled by default (enabled = false). If you enable it, test thoroughly in staging first. See Caching for usage guidance and known caveats.

Response caching for query results. Reduces database load for read-heavy workloads.

[caching]
enabled   = true
backend   = "redis"              # "memory" or "redis"
redis_url = "${REDIS_URL}"       # required when backend = "redis"

Field	Type	Default	Description
enabled	bool	false	Enable response caching
backend	string	"redis"	Cache backend: "memory" (single-instance) or "redis" (distributed)
redis_url	string	—	Redis connection URL (required when backend = "redis")

Per-query TTL is set via cache_ttl_seconds= in fraiseql.config() in the function body. See Caching.

---

[mcp]

Model Context Protocol server — exposes FraiseQL queries and mutations as MCP tools for AI agents (Claude Desktop, etc.).

[mcp]
enabled      = true
transport    = "http"    # "http" | "stdio" | "both"
path         = "/mcp"    # HTTP endpoint path
require_auth = true      # Require JWT/API key for MCP requests

# Restrict which operations are exposed
include = []             # Whitelist by operation name (empty = all)
exclude = []             # Blacklist by operation name

Field	Type	Default	Description
enabled	bool	false	Enable the MCP server
transport	string	"http"	Transport: "http" (in-process endpoint), "stdio" (for CLI agents), or "both"
path	string	"/mcp"	HTTP path for the MCP endpoint
require_auth	bool	true	Require the same JWT/API key as the GraphQL endpoint
include	array	[]	Whitelist of operation names to expose (empty = all)
exclude	array	[]	Blacklist of operation names to hide from MCP clients

See MCP Server for setup with Claude Desktop.

---

[query_defaults]

Project-wide defaults for which auto-parameters (where, order_by, limit, offset) are enabled on list queries. Per-query auto_params= overrides remain possible and are now partial — only specify the flags that differ from the project default.

Priority (lowest → highest):

1. Built-in default: all four params enabled
2. [query_defaults] in fraiseql.toml
3. Per-query auto_params={"limit": True} in Python decorator

[query_defaults]
where    = true   # default: true
order_by = true   # default: true
limit    = true   # default: true
offset   = true   # default: true

Field	Type	Default	Description
where	bool	true	Enable where filter argument on list queries
order_by	bool	true	Enable orderBy sort argument
limit	bool	true	Enable limit argument
offset	bool	true	Enable offset argument

Example — Relay-first project (disable offset pagination globally):

[query_defaults]
limit  = false
offset = false

# Only this admin query re-enables limit/offset
@fraiseql.query
def admin_logs() -> list[AdminLog]:
    return fraiseql.config(sql_source="v_admin_log", auto_params={"limit": True, "offset": True})

Compile-time warnings:

• limit = false on a non-relay list query → unbounded table scan warning
• limit = true + order_by = false → non-deterministic pagination warning

Caution

Using [queries.defaults] (wrong key) produces a hard error with a hint to use [query_defaults] instead.

---

[security]

Authorization policies enforced at runtime. JWT secret keys are never stored in TOML — only in environment variables. OIDC client configuration (issuer URL, client ID, redirect URI) is configured via environment variables (OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_REDIRECT_URI). There is no [auth] TOML section — it does not exist and causes a parse error.

[security]
default_policy = "authenticated"  # or "public"

[[security.rules]]
name              = "owner_only"
rule              = "user.id == object.owner_id"
description       = "User can only access their own data"
cacheable         = true
cache_ttl_seconds = 300

[[security.policies]]
name              = "admin_only"
type              = "rbac"         # rbac | abac | custom | hybrid
roles             = ["admin"]
strategy          = "any"          # any | all | exactly
cache_ttl_seconds = 600

[[security.field_auth]]
type_name  = "User"
field_name = "email"
policy     = "admin_only"

Field	Type	Default	Description
default_policy	string	"authenticated"	Default access: "authenticated" or "public"

[security.enterprise]

Enterprise feature flags for audit logging and legacy rate limiting.

[security.enterprise]
rate_limiting_enabled        = true
auth_endpoint_max_requests   = 100
auth_endpoint_window_seconds = 60
audit_logging_enabled        = true
audit_log_backend            = "postgresql"

Field	Type	Default	Description
rate_limiting_enabled	bool	true	Enable built-in rate limiting
auth_endpoint_max_requests	integer	100	Max auth endpoint requests per window
auth_endpoint_window_seconds	integer	60	Auth rate limit window in seconds
audit_logging_enabled	bool	true	Enable audit logging
audit_log_backend	string	"postgresql"	Audit log storage backend (e.g. "postgresql")
audit_retention_days	integer	365	How many days to retain audit log entries

[security.error_sanitization]

Controls what error detail is returned to clients. Disabled by default — enable in production to prevent SQL errors and stack traces from reaching clients.

[security.error_sanitization]
enabled                     = false  # opt-in
hide_implementation_details = true   # maximally safe when enabled
sanitize_database_errors    = true
custom_error_message        = "An internal error occurred"

Field	Type	Default	Description
enabled	bool	false	Enable error sanitization (opt-in)
hide_implementation_details	bool	true	Strip stack traces and implementation paths
sanitize_database_errors	bool	true	Replace DB error messages with generic text
custom_error_message	string	"An internal error occurred"	Message sent to clients when sanitizing

ValidationError, Forbidden, and NotFound codes pass through unchanged — clients need these to act on errors. Only InternalServerError and DatabaseError codes are sanitized.

[security.constant_time]

Enables constant-time comparison for token validation to prevent timing attacks. All fields default to true — this section only needs to appear in fraiseql.toml if you need to selectively disable individual token types.

[security.constant_time]
enabled                 = true
apply_to_jwt            = true
apply_to_session_tokens = true
apply_to_csrf_tokens    = true
apply_to_refresh_tokens = true

Field	Type	Default	Description
enabled	bool	true	Master switch for constant-time comparisons
apply_to_jwt	bool	true	Use constant-time comparison for JWT signature validation
apply_to_session_tokens	bool	true	Use constant-time comparison for session tokens
apply_to_csrf_tokens	bool	true	Use constant-time comparison for CSRF tokens
apply_to_refresh_tokens	bool	true	Use constant-time comparison for refresh tokens

[security.rate_limiting]

Token bucket rate limiting applied globally, plus per-endpoint limits for auth routes. In-memory per instance (no cross-instance coordination).

[security.rate_limiting]
enabled                      = false  # opt-in
requests_per_second          = 100
requests_per_second_per_user = 1000   # default: 10× requests_per_second
burst_size                   = 200
trust_proxy_headers          = false  # set true only when behind a trusted reverse proxy
auth_start_max_requests      = 5
auth_start_window_secs       = 60
auth_callback_max_requests   = 10
auth_callback_window_secs    = 60
auth_refresh_max_requests    = 20
auth_refresh_window_secs     = 300
auth_logout_max_requests     = 30
auth_logout_window_secs      = 60
failed_login_max_attempts    = 10
failed_login_lockout_secs    = 900
# redis_url = "${REDIS_URL}"  # requires redis-rate-limiting Cargo feature

Field	Type	Default	Description
enabled	bool	false	Enable rate limiting (opt-in)
requests_per_second	integer	100	Global token bucket refill rate
requests_per_second_per_user	integer	requests_per_second × 10	Per-authenticated-user limit
burst_size	integer	200	Maximum burst above steady-state rate
trust_proxy_headers	bool	false	Read X-Real-IP / X-Forwarded-For for client IP. Enable only when behind a trusted reverse proxy — spoofable otherwise
redis_url	string	—	Redis connection URL for distributed rate limiting (requires redis-rate-limiting feature)
auth_start_max_requests	integer	5	Max /auth/start requests per window
auth_start_window_secs	integer	60	Window for /auth/start limit
auth_callback_max_requests	integer	10	Max /auth/callback requests per window
auth_callback_window_secs	integer	60	Window for /auth/callback limit
auth_refresh_max_requests	integer	20	Max /auth/refresh requests per window
auth_refresh_window_secs	integer	300	Window for /auth/refresh limit
auth_logout_max_requests	integer	30	Max /auth/logout requests per window
auth_logout_window_secs	integer	60	Window for /auth/logout limit
failed_login_max_attempts	integer	10	Failed auth attempts before lockout
failed_login_lockout_secs	integer	900	Lockout duration in seconds

Note

When redis_url is set, an atomic Lua token-bucket script runs in Redis — limits are shared across all replicas. Requires the redis-rate-limiting Cargo feature in your deployment image. Fails open (requests allowed through) if Redis is unavailable; monitor fraiseql_rate_limit_redis_errors_total.

For multi-replica deployments where distributed limiting is a hard requirement, set FRAISEQL_REQUIRE_REDIS=1 to prevent the server from starting with the in-memory backend.

[security.state_encryption]

AEAD encryption for OAuth state blobs stored between /auth/start and /auth/callback. Requires a 32-byte key as a 64-character hex string.

[security.state_encryption]
enabled    = false                # opt-in
algorithm  = "chacha20-poly1305"  # or "aes-256-gcm"
key_source = "env"
key_env    = "STATE_ENCRYPTION_KEY"

Generate a key: openssl rand -hex 32

Field	Type	Default	Description
enabled	bool	false	Enable state encryption (opt-in)
algorithm	string	"chacha20-poly1305"	AEAD cipher: "chacha20-poly1305" or "aes-256-gcm"
key_source	string	"env"	Key source — only "env" supported
key_env	string	"STATE_ENCRYPTION_KEY"	Environment variable with the 64-char hex key

Caution

If enabled = true and the key_env variable is not set, the server refuses to start. Set enabled = false in CI and local dev environments that do not need state encryption.

[security.pkce]

PKCE (Proof Key for Code Exchange) for the OAuth /auth/start → /auth/callback flow.

Caution

[security.pkce] requires [security.state_encryption] to also be enabled. If pkce.enabled = true and state_encryption.enabled = false, the engine emits a startup warning: “PKCE state will be stored unencrypted.”

[security.pkce]
enabled               = false   # opt-in; requires state_encryption.enabled = true
code_challenge_method = "S256"  # or "plain" (warns at startup in non-dev environments)
state_ttl_secs        = 600
# redis_url = "${REDIS_URL}"    # requires redis-pkce Cargo feature

Field	Type	Default	Description
enabled	bool	false	Enable PKCE (opt-in)
code_challenge_method	string	"S256"	Challenge method: "S256" (recommended) or "plain"
state_ttl_secs	integer	600	OAuth state token lifetime in seconds
redis_url	string	—	Redis connection URL for distributed PKCE state (requires redis-pkce feature)

Caution

In multi-replica deployments, PKCE state must be stored in Redis. Without it, a user’s /auth/start may hit replica A while /auth/callback hits replica B, causing the state lookup to fail silently. Requires the redis-pkce Cargo feature. Set FRAISEQL_REQUIRE_REDIS=1 to enforce this at startup.

[security.api_keys]

API key authentication for service-to-service and CI/CD access. Keys are stored hashed — the plaintext is returned once at creation and never stored.

[security.api_keys]
enabled        = true
header         = "X-API-Key"       # HTTP header name
hash_algorithm = "sha256"          # "sha256" (fast) or "argon2" (production)
storage        = "postgres"        # "postgres" or "env" (static keys, CI only)

# Static keys — testing and CI only. Never in production.
[[security.api_keys.static]]
key_hash = "sha256:abc123..."      # echo -n "secret" | sha256sum
scopes   = ["read:*"]
name     = "ci-readonly"

Field	Type	Default	Description
enabled	bool	false	Enable API key authentication
header	string	"X-API-Key"	HTTP header to read the key from
hash_algorithm	string	"sha256"	Hashing algorithm: "sha256" or "argon2"
storage	string	"postgres"	Key storage backend: "postgres" (production) or "env" (static, CI only)

For production, store hashed keys in the fraiseql_api_keys table. See Authentication for the table schema and mutation patterns.

[security.token_revocation]

Revoke JWTs before their exp claim expires — for logout, key rotation, or security incidents.

[security.token_revocation]
enabled     = true
backend     = "redis"   # "redis" or "postgres"
require_jti = true      # reject JWTs without a jti claim
fail_open   = false     # if store unreachable, deny (not allow) the request

Field	Type	Default	Description
enabled	bool	false	Enable token revocation
backend	string	—	Storage backend: "redis" (recommended) or "postgres"
require_jti	bool	false	Reject tokens that have no jti claim
fail_open	bool	false	When false (default), deny requests if the revocation store is unreachable. Set true to allow through on store failure

When enabled, two endpoints become available:

• POST /auth/revoke — revoke the caller’s own token (self-logout)
• POST /auth/revoke-all — revoke all tokens for a user (requires admin:revoke scope)

Revoked JTIs are stored until the token’s exp expires — no manual cleanup needed.

[security.trusted_documents]

Query allowlisting — only permit GraphQL operations present in a pre-approved manifest. Useful for hardening production APIs against arbitrary query execution.

[security.trusted_documents]
enabled              = true
mode                 = "strict"       # "strict" | "permissive"
manifest_path        = "./trusted-documents.json"
reload_interval_secs = 300            # 0 = no hot-reload

Field	Type	Default	Description
enabled	bool	false	Enable trusted document enforcement
mode	string	"permissive"	"strict" rejects unknown operations; "permissive" logs them but allows through
manifest_path	string	—	Path to local JSON manifest (hash → query)
manifest_url	string	—	URL to fetch the manifest from at startup
reload_interval_secs	integer	0	How often to poll for manifest changes (0 = no reload)

Tip

In "strict" mode, no ad-hoc queries can reach the server — only operations registered in the manifest. Build manifest generation into your CI/CD pipeline so new queries are approved before deployment.

---

[validation]

Query depth and complexity limits enforced at parse time, before execution. Queries exceeding either limit receive a validation error — no database round-trip occurs.

[validation]
max_query_depth      = 10
max_query_complexity = 100

Field	Type	Default	Description
max_query_depth	integer	10	Maximum allowed field nesting depth
max_query_complexity	integer	100	Maximum allowed query complexity score

Complexity is calculated by summing field weights (lists count more than scalars). Adjust thresholds based on your schema — a schema with many list fields may need a higher limit for legitimate queries.

---

[subscriptions]

WebSocket subscription settings. FraiseQL supports both graphql-transport-ws (modern) and graphql-ws (Apollo legacy) — protocol is negotiated from the Sec-WebSocket-Protocol header automatically.

[subscriptions]
max_subscriptions_per_connection = 10

[subscriptions.hooks]
on_connect    = "https://auth.example.com/ws/connect"
on_subscribe  = "https://auth.example.com/ws/subscribe"
on_disconnect = "https://auth.example.com/ws/disconnect"
timeout_ms    = 500

Field	Type	Default	Description
max_subscriptions_per_connection	integer	unlimited	Maximum concurrent subscriptions per WebSocket connection

[subscriptions.hooks] — webhook URLs invoked during connection lifecycle:

Field	Type	Default	Description
on_connect	string	—	URL to POST on connection_init. Fail-closed: connection rejected if hook returns non-2xx
on_subscribe	string	—	URL to POST before a subscription is registered. Fail-closed
on_disconnect	string	—	URL to POST on WebSocket close. Fire-and-forget (errors ignored)
timeout_ms	integer	500	Timeout for fail-closed hooks (on_connect, on_subscribe)

Caution

on_connect and on_subscribe hooks are fail-closed — a hook timeout or non-2xx response rejects the connection or subscription. Set timeout_ms conservatively (the default 500 ms is usually fine) and ensure your auth service has low latency.

---

[debug]

Development and diagnostics features. All debug capabilities are disabled by default and gated behind a master enabled switch. Never enable in production.

[debug]
enabled          = true   # master switch — required for all other flags
database_explain = true   # include EXPLAIN output in /api/v1/query/explain responses
expose_sql       = true   # include generated SQL in explain responses (default when enabled)

Field	Type	Default	Description
enabled	bool	false	Master switch. All debug features require this to be true
database_explain	bool	false	Run EXPLAIN against the database and include the query plan in /api/v1/query/explain responses
expose_sql	bool	true	Include generated SQL in explain responses

Explain endpoint:

POST /api/v1/query/explain
Content-Type: application/json

{"query": "{ users { id name } }"}

Response includes the generated SQL and (when database_explain = true) the Postgres query plan. Use this to diagnose slow queries without enabling general query logging.

Caution

expose_sql = true reveals your internal view and function names to anyone who can reach the endpoint. Protect /api/v1/ behind a firewall or VPN in development environments.

---

[analytics]

Analytics query cache and Arrow Flight columnar query definitions. Controls whether the analytics subsystem is active.

[analytics]
enabled = false

Field	Type	Default	Description
enabled	bool	false	Controls the analytics query cache and Arrow Flight columnar query definitions.

---

[federation]

Apollo Federation v2 support and multi-database federation settings.

[federation]
enabled        = true
apollo_version = 2

[[federation.entities]]
name       = "User"
key_fields = ["id"]

[federation.circuit_breaker]

Per-entity circuit breaker for Apollo Federation subgraph calls. Automatically opens after consecutive errors, returning 503 Service Unavailable with a Retry-After header instead of cascading to a gateway timeout.

[federation.circuit_breaker]
enabled               = true
failure_threshold     = 5    # open after N consecutive errors
recovery_timeout_secs = 30   # half-open probe after this many seconds
success_threshold     = 2    # successes in HalfOpen needed to close

# Per-entity override
[[federation.circuit_breaker.per_database]]
database              = "Order"
failure_threshold     = 3
recovery_timeout_secs = 60

Field	Type	Default	Description
enabled	bool	true	Enable the circuit breaker
failure_threshold	integer	5	Consecutive errors before opening
recovery_timeout_secs	integer	30	Seconds before attempting a recovery probe
success_threshold	integer	2	Successes in HalfOpen state before closing

[[federation.circuit_breaker.per_database]] accepts an array of per-entity overrides. Each entry requires a database key matching the federation entity name. All three threshold fields are optional (inherit from the global config if omitted).

Prometheus gauge: fraiseql_federation_circuit_breaker_state{entity="..."} (0 = Closed, 1 = Open, 2 = HalfOpen).

---

[observers]

Event observer system. Supports in-memory, Redis, NATS, and PostgreSQL backends.

When enabled, the observer runtime runs inside the server process and adds:

• 1 PostgreSQL connection (for LISTEN/NOTIFY)
• 1 thread pool (max_concurrency workers)
• Memory: channel_capacity × average event size + up to max_dlq_size × average DLQ entry

Production sizing

Always set max_dlq_size in production. The default is unbounded — persistent action failures will grow the DLQ without limit until OOM. A value of 10,000 is a safe starting point.

[observers]
enabled           = true
backend           = "redis"            # "redis" | "nats" | "postgresql" | "in-memory"
max_concurrency   = 50                 # thread pool for concurrent action execution
channel_capacity  = 1000              # in-process event buffer size
max_dlq_size      = 10000             # dead letter queue cap; set this in production
checkpoint_strategy = "at_least_once"  # "at_least_once" or "effectively_once"
idempotency_table = "observer_idempotency_keys"  # required when checkpoint_strategy = "effectively_once"
nats_url          = "${FRAISEQL_NATS_URL}"  # required when backend = "nats"
# redis_url       = "${REDIS_URL}"    # required when backend = "redis"

[[observers.handlers]]
name        = "notify-new-user"
event       = "user.created"
action      = "webhook"
webhook_url = "https://api.example.com/notify"
synchronous = false                    # true = block mutation response until complete

Field	Type	Default	Description
enabled	bool	false	Enable the observer system
backend	string	"redis"	Event backend: redis, nats, postgresql, in-memory
max_concurrency	integer	50	Maximum concurrent action executions (thread pool size). Size to match your expected peak event rate and action latency.
channel_capacity	integer	1000	In-process event buffer. Events exceeding capacity trigger backpressure.
max_dlq_size	integer	unbounded	Dead letter queue maximum entries. Always set in production to prevent unbounded memory growth on persistent action failures. Use null to keep unbounded (not recommended).
checkpoint_strategy	string	"at_least_once"	"at_least_once" (fast, may duplicate) or "effectively_once" (dedup via PostgreSQL idempotency table)
idempotency_table	string	"observer_idempotency_keys"	PostgreSQL table for deduplication (required when checkpoint_strategy = "effectively_once")
nats_url	string	—	NATS server URL (required when backend = "nats"). Override via FRAISEQL_NATS_URL.
redis_url	string	—	Redis connection URL (required when backend = "redis").

[[observers.handlers]] — each entry maps an event to an action:

Field	Type	Default	Description
name	string	required	Handler identifier
event	string	required	Event name to match (e.g., user.created)
action	string	required	Action type: "webhook"
webhook_url	string	—	URL to POST to (required when action = "webhook")
synchronous	bool	false	Block mutation response until this handler completes

Sizing Guidelines

Workload	max_concurrency	channel_capacity	max_dlq_size
Low volume (< 100 events/s)	10	500	1,000
Medium (100–1,000 events/s)	50 (default)	2,000	10,000
High (> 1,000 events/s)	100–200	5,000	50,000

See Observer Operations Runbook for DLQ recovery procedures.

---

[session_variables]

Inject per-request context into PostgreSQL via SET LOCAL before each query/mutation. SQL views and functions can read these values with current_setting('app.tenant_id').

[session_variables]
inject_started_at = true  # auto-inject fraiseql.started_at timestamp (default: true)

[[session_variables.variables]]
pg_name = "app.tenant_id"
source = "jwt"
claim = "tenant_id"

[[session_variables.variables]]
pg_name = "app.locale"
source = "header"
name = "Accept-Language"

[[session_variables.variables]]
pg_name = "app.user_id"
source = "jwt"
claim = "sub"

Field	Type	Default	Description
inject_started_at	boolean	true	Auto-inject fraiseql.started_at timestamp

[[session_variables.variables]] — each entry maps a PostgreSQL GUC variable to a request context source:

Field	Type	Required	Description
pg_name	string	yes	PostgreSQL variable name (e.g., app.tenant_id)
source	string	yes	"jwt" or "header"
claim	string	when source = "jwt"	JWT claim name to extract
name	string	when source = "header"	HTTP header name to extract

Use app.* namespaced variables (PostgreSQL custom GUC prefix) to avoid conflicts with built-in settings. Access in SQL:

CREATE VIEW v_tenant_posts AS
SELECT id, jsonb_build_object(...) AS data
FROM tb_post
WHERE tenant_id = current_setting('app.tenant_id')::uuid;

See Multi-Tenancy for the full RLS pattern.

---

[inject_defaults]

Apply inject parameters globally to all queries and/or mutations, instead of repeating inject={"tenant_id": "jwt:tenant_id"} on every decorator.

[inject_defaults]
tenant_id = "jwt:tenant_id"   # applied to ALL queries and mutations

[inject_defaults.queries]
# Query-specific overrides (merged with top-level defaults)

[inject_defaults.mutations]
user_id = "jwt:sub"            # applied to mutations only

Field	Type	Description
Top-level keys	string	Applied to both queries and mutations
[inject_defaults.queries]	table	Applied to queries only (merged with top-level)
[inject_defaults.mutations]	table	Applied to mutations only (merged with top-level)

Per-decorator inject= overrides take precedence over defaults. This is particularly useful with tenant_scoped=True on @fraiseql.type, which generates the inject configuration automatically.

---

[cascade]

Controls the GraphQL Cascade protocol — automatic cache consistency through mutation responses that include all affected entities.

When enabled, mutations whose SQL functions return cascade data in mutation_response.cascade will expose it in the GraphQL response. The server also feeds cascade entities into the cache invalidation pipeline, evicting stale entries automatically.

[cascade]
enabled = true   # expose cascade data in mutation responses (default: false)

Field	Type	Default	Description
enabled	bool	false	Global default: include cascade field in mutation responses when the SQL function returns cascade data. Per-mutation overrides via cascade=True on the @fraiseql.mutation decorator take precedence.

When enabled = true, the compiler auto-generates Cascade GraphQL types (Cascade, CascadeEntity, CascadeInvalidation, CascadeMetadata) and adds a cascade: Cascade field to every mutation success type. When enabled = false (default), you can still opt in per-mutation using the decorator parameter.

Tip

Even without [cascade], the server-side cache invalidation pipeline uses cascade data internally when present. The [cascade] toggle only controls whether clients can see the cascade payload in GraphQL responses.

---

[dev]

Development-only settings. Ignored when FRAISEQL_ENV=production.

[dev]
enabled = true
default_claims = { tenant_id = "dev-tenant", sub = "dev-user" }

Field	Type	Default	Description
enabled	boolean	false	Enable dev mode (bypass JWT for inject_params)
default_claims	table	{}	Default JWT claims when no token is present

Caution

Dev mode bypasses authentication checks. Never enable in production. FRAISEQL_ENV=production explicitly disables dev mode regardless of TOML settings.

See Dev Mode Guide for usage.

---

Gateway Configuration (gateway.toml)

The federation gateway uses a separate config file from fraiseql.toml. See Federation Gateway Guide for usage.

[gateway]
port = 4000
bind = "0.0.0.0"

[[gateway.subgraphs]]
name = "users"
url = "http://user-service:4001/graphql"

[[gateway.subgraphs]]
name = "orders"
url = "http://order-service:4002/graphql"

[gateway.circuit_breaker]
failure_threshold = 5
recovery_timeout_secs = 30

[gateway.cache]
sdl_ttl_secs = 300
query_plan_cache_size = 1000

[gateway]

Field	Type	Default	Description
port	integer	4000	Gateway listen port
bind	string	"0.0.0.0"	Bind address

[[gateway.subgraphs]]

Field	Type	Default	Description
name	string	required	Subgraph identifier
url	string	required	Subgraph GraphQL endpoint URL

[gateway.circuit_breaker]

Field	Type	Default	Description
failure_threshold	integer	5	Failures before circuit opens
recovery_timeout_secs	integer	30	Seconds before half-open retry

[gateway.cache]

Field	Type	Default	Description
sdl_ttl_secs	integer	300	Cache subgraph SDL for this duration
query_plan_cache_size	integer	1000	Max cached query plans

---

Complete Example

[project]
name = "blog-api"
version = "1.0.0"
description = "Blog GraphQL API"
database_target = "postgresql"

[database]
url = "${DATABASE_URL}"
pool_min = 5
pool_max = 50
connect_timeout_ms = 5000
ssl_mode = "prefer"

[server]
host = "0.0.0.0"
port = 8080
request_timeout_ms = 30000

[server.limits]
max_concurrent_requests = 1000
max_queue_depth         = 5000

[server.cors]
origins = ["https://blog.example.com", "http://localhost:3000"]
credentials = true

[fraiseql]
schema_file = "schema.json"
output_file = "schema.compiled.json"

[security]
default_policy = "authenticated"

[[security.policies]]
name     = "admin_only"
type     = "rbac"
roles    = ["admin"]
strategy = "any"

[security.enterprise]
audit_logging_enabled = true
audit_log_backend     = "postgresql"

[security.error_sanitization]
enabled = true

[security.rate_limiting]
enabled                   = true
requests_per_second       = 100
burst_size                = 200
auth_start_max_requests   = 5
failed_login_max_attempts = 5
failed_login_lockout_secs = 900

[security.api_keys]
enabled        = true
hash_algorithm = "argon2"
storage        = "postgres"

[security.token_revocation]
enabled     = true
backend     = "redis"
require_jti = true
fail_open   = false

[security.trusted_documents]
enabled   = true
mode      = "strict"
manifest_path = "./trusted-documents.json"

[tracing]
service_name  = "blog-api"
otlp_endpoint = "http://otel-collector:4317"

[validation]
max_query_depth      = 10
max_query_complexity = 100

[subscriptions]
max_subscriptions_per_connection = 10

[cascade]
enabled = true

Run in production:

DATABASE_URL="postgresql://..." fraiseql run

---

Next Steps

CLI Reference

CLI Reference — all runtime flags

Security

Security features — detailed security guide

Deployment

Deployment — production configuration