FraiseQL Performance Guide¶
FraiseQL is designed for high performance with PostgreSQL-native optimizations and Rust-powered JSON processing.
Overview¶
FraiseQL achieves exceptional performance through:
- Rust JSON Pipeline: Fast JSON transformation and response building
- PostgreSQL Views: Optimized read-path with materialized views
- Efficient SQL Generation: Smart query planning and execution
- Connection Pooling: Optimal database connection management
- Caching Layer: Optional pg_fraiseql_cache extension
Performance Features¶
1. Rust-Powered JSON Processing¶
FraiseQL uses a Rust extension, shipped inside the fraiseql package, for JSON
operations. db.find / db.find_one and class mutations call it; applications don't
need to. On its own:
from fraiseql import fraiseql_rs
# snake_case keys to camelCase, without loading the JSON into Python objects
print(fraiseql_rs.transform_json('{"user_name": "John", "email_address": "john@example.com"}'))
# {"userName":"John","emailAddress":"john@example.com"}
Performance Benchmarks (fraiseql_rs v0.2.0):
| Test Case | Data Size | Python Time | Rust Time | Speedup |
|---|---|---|---|---|
| Simple (10 fields) | 0.23 KB | 0.055 ms | 0.006 ms | 9.1x |
| Medium (42 fields) | 1.07 KB | 0.122 ms | 0.016 ms | 7.7x |
| Nested (User + 15 posts) | 7.39 KB | 0.915 ms | 0.094 ms | 9.7x |
| Large (100 fields, deep) | 32.51 KB | 2.157 ms | 0.453 ms | 4.8x |
Benefits:
- 7-10x faster JSON processing vs pure Python (measured benchmarks)
- 2-4x faster end-to-end queries including database time
- Zero-copy transformations where possible
- Efficient camelCase conversion
- Negligible transformation overhead (< 0.1ms for most queries)
2. PostgreSQL View Optimization¶
Read queries use PostgreSQL views for optimal performance:
import fraiseql
from fraiseql.types import ID
@fraiseql.type(sql_source="v_user")
class User:
id: ID
name: str
@fraiseql.query
async def users(info, limit: int = 100) -> list[User]:
# Reads the view's data column; Rust builds the response
return await info.context["db"].find("v_user", "users", info, limit=limit)
Best Practices:
- Use views for read operations
- Create indexes on frequently queried columns
- Use materialized views for expensive aggregations
3. Efficient N+1 Query Prevention¶
The first defence is the view itself: compose related data into the parent's
data column (a jsonb_agg of a user's posts in v_user), so one query answers the
whole tree. For fields that can't be composed in the view, FraiseQL has DataLoader
integration (@fraiseql.dataloader_field with a DataLoader subclass from
fraiseql.optimization.dataloader); see
Avoid N+1 Query Problem.
4. Query Complexity Analysis¶
Prevent expensive queries with complexity limits:
from fraiseql.fastapi import FraiseQLConfig
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
max_query_depth=10, # QUERY_TOO_DEEP past 10 levels
complexity_max_score=1000, # QUERY_TOO_COMPLEX over 1000
)
Both are checked before the query runs; no limit is on by default.
Performance Benchmarks¶
Latest Results (2025-10-17, fraiseql v0.11.5 with fraiseql_rs v0.2.0):
Transformation Performance¶
- Rust vs Python: 7-10x faster JSON transformation
- End-to-end queries: 2-4x faster including database time
- Transformation overhead: < 0.1ms (negligible)
Typical Query Performance¶
- Simple Query: < 1ms (with Rust pipeline)
- Complex Query with Joins: < 5ms
- Nested relationships: < 10ms (pre-composed in views)
- Mutation: < 10ms
- Bulk Operations: ~1ms per record
APQ + TurboRouter Performance Stack¶
- Base GraphQL: 100ms average response
- + APQ: 20-80ms faster (eliminates parsing)
- + TurboRouter: Additional 2-3x speedup (bypasses GraphQL entirely)
- Total: Up to 6-9x faster for registered queries
See benchmarks/benchmark-results.md for detailed performance tests and reproducibility instructions.
Optimization Tips¶
1. Database Indexes¶
Create indexes for frequently filtered columns:
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_posts_user_id ON posts(user_id);
2. Connection Pooling¶
Configure the pool size of the app's connection pool:
from fraiseql.fastapi import FraiseQLConfig
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
database_pool_size=20, # Adjust based on load
database_max_overflow=10,
)
create_fraiseql_app(config=config, ...) opens the pool; connection_pool_size= and
connection_pool_max_overflow= on create_fraiseql_app set the same values.
3. Caching¶
Enable the pg_fraiseql_cache extension:
CREATE EXTENSION IF NOT EXISTS pg_fraiseql_cache;
4. Field Selection¶
Only select needed fields:
query {
users {
id
name
# Don't select unnecessary fields
}
}
5. Pagination¶
Always paginate large result sets:
@fraiseql.query
async def users_page(info, limit: int = 100, offset: int = 0) -> list[User]:
return await info.context["db"].find(
"v_user", "usersPage", info, limit=limit, offset=offset, order_by=[{"id": "ASC"}]
)
For cursor pagination, @fraiseql.connection pages a view with first / after
(see paginate()).
Monitoring¶
Query Performance¶
Monitor query execution time:
Time the SQL in PostgreSQL itself, where every statement FraiseQL sends shows up:
-- Log every statement slower than 100 ms
ALTER SYSTEM SET log_min_duration_statement = '100ms';
SELECT pg_reload_conf();
or read pg_stat_statements (fraiseql.monitoring.init_query_stats reads it for
you).
Metrics¶
Track key metrics:
- Query execution time
- Database connection pool utilization
- Cache hit rate
- GraphQL complexity scores
Troubleshooting¶
Slow Queries¶
- Check EXPLAIN ANALYZE output
- Verify indexes exist
- Review query complexity
- Check connection pool status
High Memory Usage¶
- Reduce result set size with pagination
- Limit query depth
- Review DataLoader batch sizes
- Check for N+1 queries
Database Connection Issues¶
- Review pool configuration
- Check connection timeouts
- Verify max_connections in PostgreSQL
- Monitor connection lifecycle
Advanced Topics¶
Query Planning¶
Understand PostgreSQL query plans:
EXPLAIN ANALYZE
SELECT * FROM users_view WHERE email = 'user@example.com';
Further Reading¶
- PostgreSQL Performance Tips
- GraphQL Query Complexity
- FraiseQL Benchmarks:
benchmarks/README.md
For questions about performance optimization, open a GitHub discussion.