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 thePOST /graphql/rustpassthrough 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¶
- ID Type - ID type and policy documentation
- API Reference - Config - Complete config reference
- Deployment - Production deployment guides