Guides Overview

Comprehensive guides for building, deploying, and optimizing FraiseQL applications.

New to FraiseQL? Start with the Getting Started guide for your first steps. Once you have a working API, explore Custom Queries to learn filtering, search, and pagination.

Transports

• REST vs GraphQL — When to use each transport (you don’t have to choose — FraiseQL serves both)
• REST Transport — Annotation-driven REST endpoints, OpenAPI spec generation
• gRPC Transport — Transport-aware DB views, auto-generated .proto
• Transport Overview — GraphQL, REST, and gRPC from one binary

Getting Started

• Custom Queries — Add filtering, full-text search, and cursor-based pagination to queries
• Error Handling — Return structured errors from SQL functions and handle them in resolvers
• Authentication — JWT, OAuth, API keys, and custom auth middleware

Architecture & Design

• Schema Design — Best practices for naming, types, and view organisation
• Multi-Tenancy — Row-level security and per-tenant isolation patterns
• Advanced Patterns — Soft deletes, audit trails, and schema versioning
• Projection Tables — Materialised read models and CQRS with PostgreSQL
• Threaded Comments — Recursive CTEs and nested GraphQL types

Operations

• Testing — Unit, integration, and contract tests for FraiseQL resolvers
• Performance — Query optimisation, indexes, and connection pooling
• Performance Benchmarks — Reproducible comparisons vs Hasura, PostGraphile, async-graphql, and strawberry
• Deployment — Docker, Kubernetes, and cloud deployment checklist

Integration

• Observers — Trigger side effects after mutations — send emails, update projections, publish events
• Observer & Webhook Patterns — Webhooks and fan-out from observer events
• Custom Resolvers — Override generated resolvers with custom Python logic
• Custom Scalars — Define and serialise custom GraphQL scalar types
• Apollo Sandbox Security — Lock down GraphQL introspection in production
• Federation & NATS Integration — Multi-database federation over NATS
• Federation Configuration — Detailed federation setup and routing rules
• Advanced Federation — Cross-service queries and federated subscriptions
• Advanced NATS — Durable consumers, JetStream, and NATS clustering

Reference

• FAQ — Frequently asked questions with runnable answers
• Troubleshooting — Diagnose and fix common runtime errors

---

By Use Case

Building APIs

1. Start with Custom Queries
2. Add Error Handling
3. Implement Testing
4. Review Schema Design

Going to Production

1. Plan Deployment
2. Set up Authentication
3. Configure Performance
4. Monitor with Benchmarks

Multi-Tenant Applications

1. Learn Multi-Tenancy architecture
2. Implement Advanced Patterns
3. Set up Federation if needed
4. Test with Testing guide

---

Quick Reference

Guide	Purpose	Audience
Custom Queries	Filtering, search, and pagination	All developers
Schema Design	Structure your data model	All developers
Advanced Patterns	Enterprise patterns	Experienced developers
Multi-Tenancy	SaaS architectures	SaaS developers
Testing	Ensure code quality	QA engineers, developers
Performance	Optimise queries	DevOps, backend developers
Deployment	Go to production	DevOps engineers
Authentication	Secure your API	Backend developers
Error Handling	Handle errors gracefully	All developers
FAQ	Common questions	All users

---

Most Important Guides

Custom Queries

Add filtering, full-text search, and cursor-based pagination to your GraphQL queries. Custom Queries →

Error Handling

Return structured errors from PostgreSQL functions and surface them cleanly in GraphQL. Error Handling →

Multi-Tenancy

Row-level security and per-tenant isolation for SaaS applications. Multi-Tenancy →

Performance

Indexes, connection pooling, and query optimisation for production workloads. Performance →

---

Next Steps

New to FraiseQL?

Getting Started — Introduction and first steps

Specific problem?

Troubleshooting — Common issues and solutions

Need examples?

Examples — Browse code examples