title: FraiseQL Guides description: Practical how-to guides for developers, DevOps, and DBAs building PostgreSQL-backed GraphQL APIs with FraiseQL. keywords: ["debugging", "implementation", "best-practices", "deployment", "tutorial"] tags: ["documentation", "reference"]

FraiseQL Guides¶

Practical how-to guides for developers, DevOps teams, and DBAs building PostgreSQL-backed GraphQL APIs with FraiseQL. FraiseQL is a Python runtime framework: you define types, queries, and mutations with decorators, and the schema is built in memory at app startup and served over FastAPI.

🚀 Getting Started¶

Understanding FraiseQL in 10 Minutes — Core concepts: the CQRS read/write split, views, and fn_ functions
Common Patterns — Real-world schema design patterns and solutions
Trinity Pattern Guide — The pk_/id/identifier identifier pattern

🎯 Evaluation & Decision Making¶

Before you start building:

Choosing FraiseQL — Is FraiseQL right for your project? Use case analysis and decision matrix
Decision Matrices — Comparison tables for common architectural choices
Consistency Model — FraiseQL's CAP theorem positioning (CP: Consistency + Partition Tolerance)

🛠️ Development Guides¶

Developer Guide — Development environment setup
Schema Design Best Practices — Designing tables, views, and types
DDL Generation Guide — Creating table-backed (tv_) views
Database Schema Migration Guide — Evolving your PostgreSQL schema safely
Mutation SQL Requirements — Writing fn_ functions for mutations
Filtering Guide — WHERE operators and query filters
Nested Array Filtering — Filtering inside nested JSONB arrays
Error Handling Patterns — Success/error union results and error shaping
Advanced Features — Less common features and techniques

🔐 Authorization¶

Authorization & RBAC Quick Start — Field- and operation-level authorization in 5 minutes

⚡ Performance¶

Performance Guide — End-to-end performance practices
Performance & Optimization Guide — Tuning queries, views, and caching
Analytics Patterns — Runtime auto-aggregation and analytical query patterns
Cascade Best Practices — Cache cascade invalidation rules
Migrating to Cascade — Adopting cascade-based cache invalidation

📊 Operations & Monitoring¶

Production Deployment Guide — Deploying the FastAPI app to production
Production Security Checklist — Pre-launch security review
Monitoring & Observability — Prometheus metrics and OpenTelemetry tracing
Observability Guide — Logging, tracing, and metrics best practices

🔌 Integrations¶

Client Implementation Guides — Querying FraiseQL from React, Vue, Flutter, React Native, and Node.js
LangChain Integration — Using FraiseQL with LangChain
Integrations Overview — Authentication providers and monitoring integrations

🩺 Troubleshooting¶

Troubleshooting Guide — General troubleshooting
Troubleshooting Decision Tree — Diagnose issues by symptom
Troubleshooting Mutations — Debugging fn_-backed mutations
Common Gotchas & Pitfalls — Frequent surprises and how to avoid them
Common Mistakes — Anti-patterns in FraiseQL implementations

🎯 By Use Case¶

I want to...

Evaluate if FraiseQL is right for me → Choosing FraiseQL
Understand the core model → Understanding FraiseQL in 10 Minutes
Understand consistency guarantees → Consistency Model
Design a schema → Schema Design Best Practices
Write a mutation → Mutation SQL Requirements
Filter query results → Filtering Guide
Add authorization → Authorization Quick Start
Tune performance → Performance & Optimization Guide
Deploy to production → Production Deployment
Set up monitoring → Monitoring & Observability
Integrate with Auth0 → Auth0 Setup
Query from a frontend → Client Implementation Guides

Architecture — Deep dive into FraiseQL design
Specifications — Complete API and feature specifications
Operations — Day-to-day operations and troubleshooting
Configuration — Security and operational configuration
Enterprise — RBAC, audit logging, KMS

📋 Document Metadata Guide¶

All guides in this directory follow a consistent metadata format for discoverability and context:

| Metadata | Values | Example |
|----------|--------|---------|
| **Status** | ✅ Production Ready, ⚠️ Beta, 📝 Draft | ✅ Production Ready |
| **Audience** | Developers, DevOps, DBAs, Architects, SREs | Developers, Architects |
| **Reading Time** | Estimated minutes | 10-15 minutes |
| **Last Updated** | YYYY-MM-DD | 2026-02-05 |

What these mean:

Status: Indicates feature stability and support level
✅ Production Ready - Fully tested, supported, recommended for production use
⚠️ Beta - Functional but may have breaking changes, use in staging first
📝 Draft - Under development, may be incomplete or unstable
Audience: Who should read this guide
Developers - Application engineers building with FraiseQL
DevOps - Infrastructure and deployment specialists
DBAs - Database administrators
Architects - System architects and technical leads
SREs - Site reliability engineers
Reading Time: Estimated time to read the full guide
Quick references (3-5 minutes)
Quick starts (5-10 minutes)
Detailed guides (15-30 minutes)
Deep dives (30+ minutes)