Skip to content

Configuration

FraiseQLConfig class for comprehensive application configuration.

📖 Before configuring: Make sure FraiseQL is installed and your environment is set up.

Overview

from fraiseql import FraiseQLConfig, create_fraiseql_app

config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    environment="production",
    enable_playground=False
)

app = create_fraiseql_app(types=[User, Post], config=config)

Core Settings

Database

Option Type Default Description
database_url PostgresUrl Required PostgreSQL connection URL (supports Unix sockets)
database_pool_size int 20 (prod), 10 (dev) Maximum number of connections in pool
database_max_overflow int 10 Extra connections allowed beyond pool_size
database_pool_timeout int 30 Connection timeout in seconds
database_pool_recycle int 3600 Recycle connections after N seconds (default: 1 hour)
database_echo bool False Deprecated, no effect: nothing reads it

Connection Pool Configuration:

FraiseQL uses psycopg3's AsyncConnectionPool for efficient connection management. You can configure the pool using either FraiseQLConfig or directly via create_fraiseql_app() parameters.

Method 1: Using FraiseQLConfig

# Standard PostgreSQL URL
config = FraiseQLConfig(
    database_url="postgresql://user:pass@localhost:5432/mydb"
)

# Unix socket connection
config = FraiseQLConfig(
    database_url="postgresql://user@/var/run/postgresql:5432/mydb"
)

# With connection pool tuning
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    database_pool_size=50,
    database_max_overflow=20,
    database_pool_timeout=60,
    database_pool_recycle=7200  # Recycle every 2 hours
)

Method 2: Using create_fraiseql_app() parameters

# Quick configuration without creating FraiseQLConfig
app = create_fraiseql_app(
    database_url="postgresql://localhost/mydb",
    types=[User, Post],
    connection_pool_size=30,  # Base pool size
    connection_pool_max_overflow=20,  # Additional connections for spikes
    connection_pool_timeout=60.0,  # Connection wait timeout
    connection_pool_recycle=3600,  # Recycle connections after 1 hour
    production=True
)

Pool Size Guidelines:

Use Case Pool Size Max Overflow Notes
Development 5-10 5 Minimal resources
Small API (<100 req/s) 10-20 10 Default settings
Medium API (100-500 req/s) 20-40 20 Most production apps
Large API (>500 req/s) 40-100 30 Monitor connection saturation

⚠️ Warning: Too many connections can exhaust PostgreSQL max_connections (default: 100). Coordinate pool sizes across all application instances with your database administrator.

Application

Option Type Default Description
app_name str "FraiseQL API" Application name displayed in API documentation
app_version str "1.0.0" Application version string
environment Literal "development" Environment mode (development/production/testing)

Examples:

config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    app_name="My GraphQL API",
    app_version="2.1.0",
    environment="production"
)

GraphQL Settings

Option Type Default Description
introspection_policy IntrospectionPolicy PUBLIC Schema introspection access control
enable_playground bool True Enable GraphQL playground IDE
playground_tool Literal "graphiql" GraphQL IDE to use (graphiql/apollo-sandbox)
max_query_depth int | None 15 Reject queries nested deeper than this, with a QUERY_TOO_DEEP error (None = unlimited; introspection not counted)
query_timeout int 30 Statement timeout, in seconds, of every database read (find, find_one, count, ...), db.run() and execute_function: set as a transaction-local statement_timeout; 0 sets none
auto_camel_case bool True Auto-convert snake_case fields to camelCase
include_execution_metadata bool False Add extensions.execution (mode, time_ms) to responses in production too (outside production it is always added); a response served as raw Rust bytes carries no extensions either way

Introspection Policies:

Policy Description
IntrospectionPolicy.DISABLED No introspection for anyone
IntrospectionPolicy.PUBLIC Introspection allowed for everyone (default)
IntrospectionPolicy.AUTHENTICATED Introspection only for authenticated users

Examples:

from fraiseql.fastapi.config import IntrospectionPolicy

# Production configuration (introspection disabled)
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    environment="production",
    introspection_policy=IntrospectionPolicy.DISABLED,
    enable_playground=False,
    max_query_depth=10,
    query_timeout=15
)

# Development configuration
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    environment="development",
    introspection_policy=IntrospectionPolicy.PUBLIC,
    enable_playground=True,
    playground_tool="graphiql",
)

Performance Settings

Query Caching

Option Type Default Description
cache_ttl int 300 Deprecated, and has no effect: nothing reads it (a non-default value warns). Per-call TTLs are CachedRepository.find(..., cache_ttl=)

TurboRouter

The TurboRouter is always on: no setting turns it off.

Option Type Default Description
turbo_router_cache_size int 1000 Maximum number of queries the registry holds

enable_query_caching, enable_turbo_router, turbo_router_auto_register, turbo_max_complexity, turbo_max_total_weight and turbo_enable_adaptive_caching aren't FraiseQLConfig fields, and FraiseQLConfig ignores them.

Examples:

# High-performance configuration
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    turbo_router_cache_size=5000,
)

JSON Passthrough

There are no passthrough settings: query results go from PostgreSQL through the Rust pipeline to the response on every query (see Rust Pipeline below). json_passthrough_enabled, json_passthrough_in_production, json_passthrough_cache_nested and the passthrough_* options of earlier releases aren't FraiseQLConfig fields, and FraiseQLConfig ignores them.

JSONB

Option Type Default Description
jsonb_field_limit_threshold int 20 Copied into the request context as info.context["jsonb_field_limit_threshold"]; FraiseQL's own queries don't read it

jsonb_extraction_enabled, jsonb_default_columns and jsonb_auto_detect aren't FraiseQLConfig fields, and FraiseQLConfig ignores them. A type reads its JSONB column from jsonb_column= on @fraiseql.type (data by default):

@fraiseql.type(sql_source="tv_machine", jsonb_column="machine_data")
class Machine:
    id: ID
    name: str

Rust Pipeline (v1.0.0+)

v0.11.5 Architectural Change: FraiseQL now uses an exclusive Rust pipeline for all query execution. No mode detection or conditional logic.

Benefits:

  • ✅ Single execution path - PostgreSQL → Rust → HTTP
  • ✅ 7-10x faster JSON transformation - Zero Python overhead
  • ✅ Always active - No configuration needed
  • ✅ Automatic camelCase - snake_case → camelCase conversion
  • ✅ Built-in __typename - Written wherever the query selects it (and only there)

All queries execute through the Rust pipeline automatically. The old multi-mode execution system (NORMAL, PASSTHROUGH, TURBO) has been removed.

# v1.0.0+ - Exclusive Rust pipeline
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    # Rust pipeline always active, minimal config needed
)

Migration from v0.11.4 and earlier: Remove all execution mode configuration.

Authentication Settings

Option Type Default Description
auth_enabled bool True Enable authentication system
auth_provider Literal "none" Auth provider (auth0/custom/none)
auth0_domain str | None None Auth0 tenant domain
auth0_api_identifier str | None None Auth0 API identifier
auth0_algorithms list[str] ["RS256"] Auth0 JWT algorithms
dev_auth_username str | None "admin" Development mode username
dev_auth_password str | None None Development mode password

Examples:

# Auth0 configuration
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    auth_enabled=True,
    auth_provider="auth0",
    auth0_domain="myapp.auth0.com",
    auth0_api_identifier="https://api.myapp.com",
    auth0_algorithms=["RS256"]
)

# Development authentication
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    environment="development",
    auth_provider="custom",
    dev_auth_username="admin",
    dev_auth_password="secret"
)

CORS Settings

Option Type Default Description
cors_enabled bool False Enable CORS (disabled by default)
cors_origins list[str] [] Allowed CORS origins
cors_methods list[str] ["GET", "POST"] Allowed HTTP methods
cors_headers list[str] ["Content-Type", "Authorization"] Allowed headers

Examples:

# Production CORS (specific origins)
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    cors_enabled=True,
    cors_origins=[
        "https://app.example.com",
        "https://admin.example.com"
    ],
    cors_methods=["GET", "POST", "OPTIONS"],
    cors_headers=["Content-Type", "Authorization", "X-Request-ID"]
)

# Development CORS (permissive)
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    environment="development",
    cors_enabled=True,
    cors_origins=["http://localhost:3000", "http://localhost:8080"]
)

Rate Limiting Settings

Option Type Default Description
rate_limit_enabled bool False create_fraiseql_app installs RateLimiterMiddleware, counting requests per client IP in each process's memory
rate_limit_requests_per_minute int 60 Requests a client may make in any 60 seconds
rate_limit_requests_per_hour int 1000 Requests a client may make in any hour
rate_limit_burst_size int 10 Requests a minute always allowed, even above the per-minute limit (the hour limit still applies)
rate_limit_window_type str "sliding" Only "sliding" is implemented; another value logs a warning
rate_limit_whitelist list[str] [] Client IPs never limited
rate_limit_blacklist list[str] [] Client IPs always rejected with 403

A request over the limit gets 429 with Retry-After and X-RateLimit-* headers. /health, /ready, /metrics and / are not counted. See Rate Limiting, also for running behind a proxy.

Examples:

# Strict rate limiting
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    rate_limit_enabled=True,
    rate_limit_requests_per_minute=30,
    rate_limit_requests_per_hour=500,
    rate_limit_burst_size=5,
    rate_limit_whitelist=["10.0.0.1", "10.0.0.2"]
)

Complexity Settings

Option Type Default Description
complexity_enabled bool False Enforce complexity_max_score and complexity_max_depth; turned on when either is set
complexity_max_score int 1000 Reject a query whose complexity score is higher (QUERY_TOO_COMPLEX)
complexity_max_depth int 10 Reject a query nested deeper (QUERY_TOO_DEEP); the lower of it and max_query_depth wins
complexity_default_list_size int 10 List size assumed for a list field without a limit / first argument
complexity_include_in_response bool False Deprecated, no effect: no response carries the score
complexity_field_multipliers dict[str, int] {} Cost of a field instead of 1, by field name or "Type.field"

The score is computed from the schema before the query runs: a scalar costs 1, an object field 1 plus its selections, and a list field 1 plus its selections times its limit / first argument (or complexity_default_list_size). So { users { posts { id } } } without limits scores 1 + 10 * (1 + 10 * 1) = 111. Introspection (__schema, __type) is not counted; introspection_policy governs it. A rejected query gets a GraphQL error and runs no resolver or SQL.

The FastAPI app reads these limits from its config. The other entry points take them too, from a config or as an explicit QueryLimits (fraiseql.gql.query_limits): GraphNoteRouter(schema, config=config) for the plain Starlette router, and SubscriptionManager(config=config) (or WebSocketConnection(..., query_limits=...)) for subscriptions over WebSocket. Without either, they apply no limit.

Examples:

# Complexity limits
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    complexity_enabled=True,
    complexity_max_score=500,
    complexity_max_depth=8,
    complexity_default_list_size=20,
    complexity_field_multipliers={
        "users": 2,  # Users query costs 2x
        "posts": 1,  # Standard cost
        "comments": 3  # Comments query costs 3x
    }
)

APQ (Automatic Persisted Queries) Settings

Option Type Default Description
apq_mode APQMode OPTIONAL optional: hashes and full queries; required: only hashes the server already knows (a client can't register one); disabled: APQ extensions ignored
apq_queries_dir str | None None Directory whose .graphql / .gql operations are registered as persisted queries (must exist at startup; not read in disabled mode)
apq_storage_backend Literal "memory" Storage backend (memory/postgresql/custom); postgresql stores in apq_queries / apq_responses, created on first use
apq_cache_responses bool False Cache the response of APQ queries (not mutations, nor responses with errors), per variables, tenant and user
apq_response_cache_ttl int 600 Seconds a cached APQ response is served; 0 keeps it
apq_backend_config dict[str, Any] {} Backend-specific configuration options

Examples:

# APQ with PostgreSQL backend
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    apq_storage_backend="postgresql",
    apq_cache_responses=True,
    apq_response_cache_ttl=900  # 15 minutes
)

# Only operations shipped with the app run
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    apq_mode="required",
    apq_queries_dir="./graphql",
)

In required mode a request with a query text and no known hash is refused (PERSISTED_QUERY_NOT_IN_LIST, or ARBITRARY_QUERY_NOT_ALLOWED without APQ extensions), so apq_queries_dir is how queries get approved. A query whose text doesn't hash to its sha256Hash gets 400 in optional and required mode. See Persisted Queries.

Token Revocation Settings

Option Type Default Description
revocation_enabled bool True Enable token revocation
revocation_check_enabled bool True Check revocation status on requests
revocation_ttl int 86400 Token revocation TTL (24 hours)
revocation_cleanup_interval int 3600 Cleanup interval (1 hour)
revocation_store_type str "memory" Storage type (memory/redis)

Rust Pipeline Configuration

FraiseQL uses an exclusive Rust pipeline for all query execution.

Configuration Options

  • enable_rust_endpoint: bool = False - Mount the POST /graphql/rust passthrough route

Field selection always happens in Rust: field_projection and schema_registry aren't FraiseQLConfig fields, and FraiseQLConfig ignores them. The Rust schema registry is initialized by create_fraiseql_app, which takes enable_schema_registry=False to skip it.

Example

config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    # Rust pipeline is always active
)
app = create_fraiseql_app(types=[User], config=config, enable_schema_registry=False)

enable_rust_endpoint (opt-in, issue #365)

POST /graphql/rust is a Rust passthrough that bypasses Python resolvers entirely. It is off by default — a resolver-bypass route should not exist unless explicitly requested — and is mounted only when enable_rust_endpoint=True:

config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    enable_rust_endpoint=True,  # or FRAISEQL_ENABLE_RUST_ENDPOINT=true
)

When disabled the route is not mounted (a request 404s). When enabled it is still authorization-gated (issue #362); row scoping relies on session variables + RLS, not per-row filter injection. Behavior change: apps that relied on /graphql/rust must now set this flag.

Schema Settings

Option Type Default Description
default_mutation_schema str "public" Default schema for mutations
default_query_schema str "public" Deprecated, no effect: a query reads the view its sql_source names (qualify it to pick a schema)

Examples:

# Custom schema configuration
config = FraiseQLConfig(
    database_url="postgresql://localhost/mydb",
    default_mutation_schema="app",
)

Entity Routing (deprecated)

entity_routing has no effect and will be removed. It is validated and stored, but no query is routed by entity: every query runs the same execution path. Setting it emits a DeprecationWarning; remove it from your configuration.

Environment Variables

All configuration options can be set via environment variables with the FRAISEQL_ prefix:

# Database
export FRAISEQL_DATABASE_URL="postgresql://localhost/mydb"
export FRAISEQL_DATABASE_POOL_SIZE=50

# Application
export FRAISEQL_APP_NAME="My API"
export FRAISEQL_ENVIRONMENT="production"

# GraphQL
export FRAISEQL_INTROSPECTION_POLICY="disabled"
export FRAISEQL_ENABLE_PLAYGROUND="false"
export FRAISEQL_MAX_QUERY_DEPTH=10

# Auth
export FRAISEQL_AUTH_PROVIDER="auth0"
export FRAISEQL_AUTH0_DOMAIN="myapp.auth0.com"
export FRAISEQL_AUTH0_API_IDENTIFIER="https://api.myapp.com"

.env File Support

Configuration can also be loaded from .env files:

# .env file
FRAISEQL_DATABASE_URL=postgresql://localhost/mydb
FRAISEQL_ENVIRONMENT=production
FRAISEQL_INTROSPECTION_POLICY=disabled
FRAISEQL_ENABLE_PLAYGROUND=false
# Automatically loads from .env
config = FraiseQLConfig()

Complete Example

from fraiseql import FraiseQLConfig, create_fraiseql_app
from fraiseql.fastapi.config import IntrospectionPolicy

# Production-ready configuration
config = FraiseQLConfig(
    # Database
    database_url="postgresql://user:pass@db.example.com:5432/prod",
    database_pool_size=50,
    database_max_overflow=20,
    database_pool_timeout=60,

    # Application
    app_name="Production API",
    app_version="2.0.0",
    environment="production",

    # GraphQL
    introspection_policy=IntrospectionPolicy.DISABLED,
    enable_playground=False,
    max_query_depth=10,
    query_timeout=15,
    auto_camel_case=True,

    # Performance
    turbo_router_cache_size=5000,

    # Auth
    auth_enabled=True,
    auth_provider="auth0",
    auth0_domain="myapp.auth0.com",
    auth0_api_identifier="https://api.myapp.com",

    # CORS
    cors_enabled=True,
    cors_origins=["https://app.example.com"],
    cors_methods=["GET", "POST"],

    # Rate Limiting
    rate_limit_enabled=True,
    rate_limit_requests_per_minute=30,
    rate_limit_requests_per_hour=500,

    # Complexity
    complexity_enabled=True,
    complexity_max_score=500,
    complexity_max_depth=8,

    # APQ
    apq_storage_backend="postgresql",
    apq_cache_responses=True,
    apq_response_cache_ttl=900
)

app = create_fraiseql_app(types=[User, Post, Comment], config=config)

Schema Configuration

SchemaConfig controls GraphQL schema generation behavior, separate from runtime FraiseQLConfig.

ID Policy (v1.9.2+)

Option Type Default Description
id_policy IDPolicy UUID How ID scalars behave
camel_case_fields bool True Convert snake_case to camelCase

ID Policies:

Policy Description Use Case
IDPolicy.UUID IDs must be valid UUIDs (default) FraiseQL opinionated apps
IDPolicy.OPAQUE IDs accept any string GraphQL spec compliance

Examples:

from fraiseql.config.schema_config import SchemaConfig, IDPolicy

# Default: UUID enforcement (recommended)
SchemaConfig.set_config(id_policy=IDPolicy.UUID)

# GraphQL spec-compliant: accepts any string
SchemaConfig.set_config(id_policy=IDPolicy.OPAQUE)

# Disable camelCase conversion
SchemaConfig.set_config(camel_case_fields=False)

Type Mapping by Policy:

Python Type UUID Policy OPAQUE Policy
ID IDScalar (enforces UUID) GraphQLID (any string)
uuid.UUID UUIDScalar (name="UUID") UUIDScalar (name="UUID")

Important: uuid.UUID always maps to UUIDScalar, regardless of policy. Only the ID type annotation is affected by the policy.

See ID Type for detailed ID documentation.

See Also