Skip to content

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:

  1. Direct instantiation (highest priority)
  2. Environment variables with FRAISEQL_ prefix
  3. .env file in project root
  4. 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 sorting
  • None - 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 default
  • development: Enables debugging features
  • testing: 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; None before)
  • 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 a QUERY_TOO_DEEP GraphQL error (extensions.depth, extensions.maxDepth) before any resolver or SQL runs, on POST and GET /graphql, APQ persisted queries included. Introspection (__schema, __type) is not counted: introspection_policy governs 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() and execute_function: set as a transaction-local statement_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 lone db.find / db.find_one root 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 have apq_response_cache_ttl; CachedRepository.find takes cache_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_app installs RateLimiterMiddleware, which counts requests per client IP (request.client.host) in a sliding window, in each process's memory. A request over the limit gets 429 with Retry-After and X-RateLimit-* headers; /health, /ready, /metrics and / 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_score and complexity_max_depth. Setting either of them (in code or from the environment) turns it on, unless complexity_enabled is set too; complexity_enabled=False keeps the limits off.

complexity_max_score

  • Type: int
  • Default: 1000
  • Description: Reject a query whose complexity score is higher, with a QUERY_TOO_COMPLEX GraphQL 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 its limit / first argument (literal, variable, or the argument's schema default), else complexity_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 / first to

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 .graphql files 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 (memory and postgresql backends); 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_source names, and an unqualified name resolves through the connection's search_path. Qualify it (sql_source="api.v_user") to pick a schema. Setting it emits a DeprecationWarning.

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 @mutation decorator

Impact:

  • When set, all mutations without an explicit error_config parameter will use this global default
  • Individual mutations can override the global default by specifying error_config in 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:

  1. Explicit error_config in @mutation decorator (highest priority)
  2. default_error_config from FraiseQLConfig
  3. None (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:

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