FraiseQLConfig API Reference¶
Complete API reference for FraiseQLConfig class with all configuration options for v1.6.1.
Overview¶
from fraiseql import FraiseQLConfig
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
environment="production"
)
Import¶
from fraiseql import FraiseQLConfig
from fraiseql.fastapi.config import IntrospectionPolicy # For introspection settings
Configuration Sources¶
Configuration values can be set via:
- Direct instantiation (highest priority)
- Environment variables with
FRAISEQL_prefix - .env file in project root
- Default values
Database Settings¶
database_url¶
- Type:
PostgresUrl(str with validation) - Required: Yes
- Default: None
- Description: PostgreSQL connection URL with JSONB support required
Formats:
# Standard PostgreSQL URL
"postgresql://user:password@host:port/database"
# Unix domain socket
"postgresql://user@/var/run/postgresql:5432/database"
# With password in socket connection
"postgresql://user:password@/var/run/postgresql:5432/database"
Environment Variable: FRAISEQL_DATABASE_URL
Examples:
# Direct
config = FraiseQLConfig(database_url="postgresql://localhost/mydb")
# From environment
export FRAISEQL_DATABASE_URL="postgresql://localhost/mydb"
config = FraiseQLConfig()
# .env file
FRAISEQL_DATABASE_URL=postgresql://localhost/mydb
database_pool_size¶
- Type:
int - Default:
20 - Description: Maximum number of database connections in pool
database_max_overflow¶
- Type:
int - Default:
10 - Description: Extra connections allowed beyond pool_size
database_pool_timeout¶
- Type:
int - Default:
30 - Description: Connection timeout in seconds
database_echo¶
- Type:
bool - Default:
False - Description: Deprecated, and has no effect: nothing reads it. Setting it emits a
DeprecationWarning; it will be removed.
Examples:
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
database_pool_size=50,
database_max_overflow=20,
database_pool_timeout=60,
)
default_string_collation¶
- Type:
str | None - Default:
None - Description: Default PostgreSQL collation for string ORDER BY clauses
Applied to all text fields in ORDER BY unless overridden per-field in queries.
Text fields only
Each sort key is resolved against the type registered for the view, and the default is applied only to fields that resolve to a string. A field that resolves to anything else -- or that cannot be resolved at all, because the view is unregistered or the field is not declared on its type -- is left alone. Collating a numeric field would either sort it lexicographically (1, 10, 2) or fail with collations are not supported by type integer.
Common Values:
"C"- Byte-order sorting (fastest, case-sensitive)"POSIX"- Equivalent to"C""en_US.utf8"- US English locale-aware sorting"fr_FR.utf8"- French locale-aware sorting (handles accents)"de_DE.utf8"- German locale-aware sortingNone- Use PostgreSQL database default collation
Environment Variable: FRAISEQL_DEFAULT_STRING_COLLATION
Examples:
# Global default for French locale
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
default_string_collation="fr_FR.utf8"
)
# Per-query override in GraphQL
query {
users(orderBy: [
{ field: "name", direction: ASC, collation: "en_US.utf8" }
]) {
id
name
}
}
Performance: For best performance with collation, create matching indexes:
CREATE INDEX idx_users_name_fr
ON users ((data->>'name') COLLATE "fr_FR.utf8");
See Also: ORDER BY Collation Support
Application Settings¶
app_name¶
- Type:
str - Default:
"FraiseQL API" - Description: Application name displayed in API documentation
app_version¶
- Type:
str - Default:
"1.0.0" - Description: Application version string
environment¶
- Type:
Literal["development", "production", "testing"] - Default:
"development" - Description: Current environment mode
Impact:
production: Disables playground and introspection by defaultdevelopment: Enables debugging featurestesting: Used for test suites
Examples:
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
app_name="My GraphQL API",
app_version="2.1.0",
environment="production"
)
GraphQL Settings¶
introspection_policy¶
- Type:
IntrospectionPolicy - Default:
IntrospectionPolicy.PUBLIC(development),IntrospectionPolicy.DISABLED(production) - Description: Schema introspection access control policy
Values:
| Value | Description |
|---|---|
IntrospectionPolicy.DISABLED |
No introspection for anyone |
IntrospectionPolicy.PUBLIC |
Introspection allowed for everyone |
IntrospectionPolicy.AUTHENTICATED |
Introspection only for authenticated users |
Examples:
from fraiseql.fastapi.config import IntrospectionPolicy
# Disable introspection in production
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
environment="production",
introspection_policy=IntrospectionPolicy.DISABLED
)
# Require auth for introspection
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
introspection_policy=IntrospectionPolicy.AUTHENTICATED
)
enable_playground¶
- Type:
bool - Default:
True(development),False(production) - Description: Enable GraphQL playground IDE
playground_tool¶
- Type:
Literal["graphiql", "apollo-sandbox"] - Default:
"graphiql" - Description: Which GraphQL IDE to use
max_query_depth¶
- Type:
int | None - Default:
15(since 1.31.1;Nonebefore) - Description: Reject a query nested deeper than this (
None= unlimited).{ users { id } }has depth 1,{ users { posts { id } } }depth 2; fragments add no depth of their own. A deeper query gets aQUERY_TOO_DEEPGraphQL error (extensions.depth,extensions.maxDepth) before any resolver or SQL runs, onPOSTandGET /graphql, APQ persisted queries included. Introspection (__schema,__type) is not counted:introspection_policygoverns it. Must be at least 1.
query_timeout¶
- Type:
int - Default:
30 - Description: Statement timeout, in seconds, of every database read (
find,find_one,count, ...),db.run()andexecute_function: set as a transaction-localstatement_timeout; 0 sets none.
include_execution_metadata¶
- Type:
bool - Default:
False - Description: Add
extensions.execution(mode,time_ms) to GraphQL responses in production too. Outside production it is always added. A response served as raw Rust bytes (a lonedb.find/db.find_oneroot field, for instance) carries no extensions either way.
auto_camel_case¶
- Type:
bool - Default:
True - Description: Auto-convert snake_case fields to camelCase in GraphQL
Examples:
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
introspection_policy=IntrospectionPolicy.DISABLED,
enable_playground=False,
max_query_depth=10,
query_timeout=15,
auto_camel_case=True
)
Performance Settings¶
cache_ttl¶
- Type:
int - Default:
300 - Description: Deprecated, and has no effect: nothing reads it. A value other than
the default emits a
DeprecationWarning. APQ responses haveapq_response_cache_ttl;CachedRepository.findtakescache_ttl=per call.
turbo_router_cache_size¶
- Type:
int - Default:
1000 - Description: Maximum number of queries the TurboRouter registry holds. The TurboRouter is always on: no setting turns it off.
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.
JSON Passthrough Settings¶
None. Query results go from PostgreSQL through the Rust pipeline to the response on every
query. 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 Settings¶
jsonb_field_limit_threshold¶
- Type:
int - Default:
20 - Description: Copied into the request context as
info.context["jsonb_field_limit_threshold"], for resolvers that want it. FraiseQL's own queries don't read it.
Examples:
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
jsonb_field_limit_threshold=30,
)
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).
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.
Configuration Options: none in FraiseQLConfig. Field selection always happens in
Rust. The Rust schema registry is initialized by create_fraiseql_app, which takes
enable_schema_registry=False to skip it.
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)
Migration from v0.11.4 and earlier: Remove all execution mode configuration.
# v0.11.4 and earlier (OLD - remove these)
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
execution_mode_priority=["turbo", "passthrough", "normal"], # ❌ Remove
enable_python_fallback=True, # ❌ Remove
passthrough_detection_enabled=True, # ❌ Remove
)
# v1.0.0+ - Exclusive Rust pipeline
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
# ✅ Rust pipeline always active, minimal config needed
)
Authentication Settings¶
auth_enabled¶
- Type:
bool - Default:
True - Description: Enable authentication system
auth_provider¶
- Type:
Literal["auth0", "custom", "none"] - Default:
"none" - Description: Authentication provider to use
auth0_domain¶
- Type:
str | None - Default:
None - Description: Auth0 tenant domain (required if using Auth0)
Required when: auth_provider="auth0"
auth0_api_identifier¶
- Type:
str | None - Default:
None - Description: Auth0 API identifier (required if using Auth0)
Required when: auth_provider="auth0"
auth0_algorithms¶
- Type:
list[str] - Default:
["RS256"] - Description: Auth0 JWT algorithms
dev_auth_username¶
- Type:
str | None - Default:
"admin" - Description: Development mode username
dev_auth_password¶
- Type:
str | None - Default:
None - Description: 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 auth
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
environment="development",
auth_provider="custom",
dev_auth_username="admin",
dev_auth_password="secret"
)
CORS Settings¶
cors_enabled¶
- Type:
bool - Default:
False - Description: Enable CORS (disabled by default to avoid conflicts with reverse proxies)
cors_origins¶
- Type:
list[str] - Default:
[] - Description: Allowed CORS origins (empty by default, must be explicitly configured)
Warning: Using ["*"] in production is a security risk
cors_methods¶
- Type:
list[str] - Default:
["GET", "POST"] - Description: Allowed HTTP methods for CORS
cors_headers¶
- Type:
list[str] - Default:
["Content-Type", "Authorization"] - Description: Allowed headers for CORS requests
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"]
)
Rate Limiting Settings¶
rate_limit_enabled¶
- Type:
bool - Default:
False - Description:
create_fraiseql_appinstallsRateLimiterMiddleware, which counts requests per client IP (request.client.host) in a sliding window, in each process's memory. A request over the limit gets429withRetry-AfterandX-RateLimit-*headers;/health,/ready,/metricsand/are not counted. See Rate Limiting.
rate_limit_requests_per_minute¶
- Type:
int - Default:
60 - Description: Requests a client may make in any 60 seconds
rate_limit_requests_per_hour¶
- Type:
int - Default:
1000 - Description: Requests a client may make in any hour
rate_limit_burst_size¶
- Type:
int - Default:
10 - Description: Requests a minute always allowed, even above
rate_limit_requests_per_minute(the hour limit still applies)
rate_limit_window_type¶
- Type:
str - Default:
"sliding" - Description: Only
"sliding"is implemented; another value logs a warning and counts in a sliding window
rate_limit_whitelist¶
- Type:
list[str] - Default:
[] - Description: Client IPs that are never limited
rate_limit_blacklist¶
- Type:
list[str] - Default:
[] - Description: Client IPs that always get
403
Examples:
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¶
complexity_enabled¶
- Type:
bool - Default:
False - Description: Enforce
complexity_max_scoreandcomplexity_max_depth. Setting either of them (in code or from the environment) turns it on, unlesscomplexity_enabledis set too;complexity_enabled=Falsekeeps the limits off.
complexity_max_score¶
- Type:
int - Default:
1000 - Description: Reject a query whose complexity score is higher, with a
QUERY_TOO_COMPLEXGraphQL error (extensions.complexity,extensions.maxComplexity), before it runs. A scalar costs 1, an object field 1 plus its selections, a list field 1 plus its selections times itslimit/firstargument (literal, variable, or the argument's schema default), elsecomplexity_default_list_size. Introspection is not counted. Must be at least 1.
complexity_max_depth¶
- Type:
int - Default:
10 - Description: Reject a query nested deeper, like
max_query_depth, when complexity limits are on. When both apply, the lower one wins.
complexity_default_list_size¶
- Type:
int - Default:
10 - Description: List size assumed for a list field the query passes no
limit/firstto
complexity_include_in_response¶
- Type:
bool - Default:
False - Description: Deprecated, and has no effect: no response carries the complexity score.
Setting it emits a
DeprecationWarning; it will be removed.
complexity_field_multipliers¶
- Type:
dict[str, int] - Default:
{} - Description: Cost of a field instead of 1, keyed by field name (
"search") or"Type.field"
Examples:
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
complexity_enabled=True,
complexity_max_score=500,
complexity_max_depth=8,
complexity_field_multipliers={
"users": 2,
"posts": 1,
"comments": 3
}
)
APQ Settings¶
apq_mode¶
- Type:
Literal["optional", "required", "disabled"] - Default:
"optional" - Description: APQ mode for controlling query acceptance
| Mode | Behavior |
|---|---|
"optional" |
Accept both persisted query hashes and full queries (default) |
"required" |
Only run hashes the server already knows (from apq_queries_dir or a backend's register_queries); a query text is refused, with or without a hash, and nothing is stored |
"disabled" |
Ignore APQ extensions entirely, always require full query |
In optional and required mode, a query whose text doesn't hash to its sha256Hash
gets HTTP 400 (provided sha does not match query).
New in FraiseQL v1.6.1
apq_storage_backend¶
- Type:
Literal["memory", "postgresql", "custom"] - Default:
"memory" - Description: Storage backend for APQ (Automatic Persisted Queries)
apq_queries_dir¶
- Type:
str | None - Default:
None - Description: Directory containing
.graphqlfiles to auto-register at startup
When set, the operations of every .graphql and .gql file in this directory (recursively) are registered as persisted queries, each under the SHA-256 of its text, when the first APQ request creates the backend. A missing directory makes the app fail at startup; the directory isn't read in apq_mode="disabled". It is how queries get approved in apq_mode="required".
New in FraiseQL v1.6.1
apq_cache_responses¶
- Type:
bool - Default:
False - Description: Cache the response of APQ queries. Mutations, subscriptions and responses with errors are not cached; the key is the hash, the variables, the tenant and the authenticated user's id (an authenticated request without one is not cached)
apq_response_cache_ttl¶
- Type:
int - Default:
600 - Description: Seconds a cached APQ response is served (
memoryandpostgresqlbackends); 0 keeps it
apq_backend_config¶
- Type:
dict[str, Any] - Default:
{} - Description: 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
)
# APQ with custom Redis backend (bring your own implementation)
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
apq_storage_backend="custom",
apq_backend_config={
"backend_class": "myapp.storage.RedisAPQBackend",
"redis_url": "redis://localhost:6379/0",
"key_prefix": "apq:"
}
)
# Security-hardened: Only allow pre-registered queries (v1.6.0+)
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
apq_mode="required", # Reject arbitrary queries
apq_queries_dir="./graphql/queries/", # Auto-register from directory
apq_storage_backend="postgresql", # Persist across restarts
)
Token Revocation Settings¶
revocation_enabled¶
- Type:
bool - Default:
True - Description: Enable token revocation
revocation_check_enabled¶
- Type:
bool - Default:
True - Description: Check revocation status on requests
revocation_ttl¶
- Type:
int - Default:
86400 - Description: Token revocation TTL in seconds (24 hours)
revocation_cleanup_interval¶
- Type:
int - Default:
3600 - Description: Cleanup interval in seconds (1 hour)
revocation_store_type¶
- Type:
str - Default:
"memory" - Description: Storage type ("memory" or "redis")
Rust Pipeline Settings¶
None. field_projection and schema_registry aren't FraiseQLConfig fields, and
FraiseQLConfig ignores them: field selection always happens in Rust. To skip
initializing the Rust schema registry, pass enable_schema_registry=False to
create_fraiseql_app:
app = create_fraiseql_app(
types=[User],
config=FraiseQLConfig(database_url="postgresql://localhost/mydb"),
enable_schema_registry=False,
)
Schema Settings¶
default_mutation_schema¶
- Type:
str - Default:
"public" - Description: Default schema for mutations when not specified
default_query_schema¶
- Type:
str - Default:
"public" - Description: Deprecated, and has no effect: a query reads the view its
sql_sourcenames, and an unqualified name resolves through the connection'ssearch_path. Qualify it (sql_source="api.v_user") to pick a schema. Setting it emits aDeprecationWarning.
Examples:
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
default_mutation_schema="app",
)
Mutation Error Handling Settings¶
default_error_config¶
- Type:
MutationErrorConfig | None - Default:
None - Description: Default error configuration for all mutations when not explicitly specified in the
@mutationdecorator
Impact:
- When set, all mutations without an explicit
error_configparameter will use this global default - Individual mutations can override the global default by specifying
error_configin the decorator - Only used in non-HTTP mode (direct GraphQL execution); HTTP mode uses status string taxonomy
Available Configurations:
| Configuration | Description |
|---|---|
DEFAULT_ERROR_CONFIG |
Standard error handling with common error keywords and prefixes |
STRICT_STATUS_CONFIG |
Strict prefix-based error detection, fewer keywords |
ALWAYS_DATA_CONFIG |
Returns all statuses as data (never raises GraphQL errors) |
Custom MutationErrorConfig |
Define your own error detection rules |
Examples:
from fraiseql import FraiseQLConfig, DEFAULT_ERROR_CONFIG, STRICT_STATUS_CONFIG
# Development: Use standard error handling globally
dev_config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
environment="development",
default_error_config=DEFAULT_ERROR_CONFIG,
)
# Production: Use stricter error handling globally
prod_config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
environment="production",
default_error_config=STRICT_STATUS_CONFIG,
)
# Custom error configuration
from fraiseql import MutationErrorConfig
custom_config = MutationErrorConfig(
success_keywords={"success", "ok", "done"},
error_prefixes={"error:", "failed:"},
always_return_as_data=False,
)
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
default_error_config=custom_config,
)
With Mutations:
from fraiseql import mutation, FraiseQLConfig, DEFAULT_ERROR_CONFIG, STRICT_STATUS_CONFIG
# Global config with default error handling
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
default_error_config=DEFAULT_ERROR_CONFIG, # Applied to all mutations by default
)
# Mutation uses global default (no error_config specified)
@mutation(function="create_user")
class CreateUser:
input: CreateUserInput
success: CreateUserSuccess
error: CreateUserError
# Uses DEFAULT_ERROR_CONFIG from config
# Mutation overrides global default
@mutation(
function="delete_user",
error_config=STRICT_STATUS_CONFIG, # Override: Use stricter config for deletions
)
class DeleteUser:
input: DeleteUserInput
success: DeleteUserSuccess
error: DeleteUserError
# Uses STRICT_STATUS_CONFIG (explicit override)
Resolution Order:
- Explicit
error_configin@mutationdecorator (highest priority) default_error_configfromFraiseQLConfigNone(no error configuration, uses default behavior)
Benefits:
- DRY Principle: Set error handling once, apply everywhere
- Environment-aware: Different configs for dev/staging/prod
- Maintainability: Change error strategy in one place
- Flexibility: Override per-mutation when needed
See Also:
- Mutation Decorator - Mutation decorator reference
- Status Strings - Status string conventions (HTTP mode)
Entity Routing Settings¶
entity_routing¶
- Type:
EntityRoutingConfig | dict | None - Default:
None - Description: Deprecated, and has no effect. It is validated and stored, but no query
is routed by entity: every query runs the same execution path. Setting it emits a
DeprecationWarning. It will be removed.
Properties¶
enable_introspection¶
- Type:
bool(read-only property) - Description: Backward compatibility property for enable_introspection
Returns True if introspection_policy != IntrospectionPolicy.DISABLED
Complete Example¶
from fraiseql import FraiseQLConfig
from fraiseql.fastapi.config import IntrospectionPolicy
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,
# 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"],
# Rate Limiting
rate_limit_enabled=True,
rate_limit_requests_per_minute=30,
# Complexity
complexity_enabled=True,
complexity_max_score=500
)
See Also¶
- Configuration Guide - Configuration patterns and examples
- Deployment - Production configuration