{"id":47315950,"url":"https://github.com/fraiseql/fraiseql-python","last_synced_at":"2026-06-07T00:01:43.508Z","repository":{"id":310121614,"uuid":"1033004350","full_name":"fraiseql/fraiseql-python","owner":"fraiseql","description":" The Explicit GraphQL Framework for the LLM Era  Simple patterns. High performance. PostgreSQL at the center..","archived":false,"fork":false,"pushed_at":"2026-05-19T02:55:59.000Z","size":80282,"stargazers_count":21,"open_issues_count":8,"forks_count":1,"subscribers_count":0,"default_branch":"dev","last_synced_at":"2026-05-19T04:57:10.824Z","etag":null,"topics":["fastapi","fraiseql-v1","graphql","postgresql","python","rag"],"latest_commit_sha":null,"homepage":"https://fraiseql.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fraiseql.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/security-ignore-patterns.txt","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-06T06:48:59.000Z","updated_at":"2026-05-15T10:41:37.000Z","dependencies_parsed_at":"2025-09-21T09:13:22.395Z","dependency_job_id":"8013a1b1-1160-4a20-abee-f63f649009ce","html_url":"https://github.com/fraiseql/fraiseql-python","commit_stats":null,"previous_names":["fraiseql/fraiseql"],"tags_count":193,"template":false,"template_full_name":null,"purl":"pkg:github/fraiseql/fraiseql-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraiseql%2Ffraiseql-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraiseql%2Ffraiseql-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraiseql%2Ffraiseql-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraiseql%2Ffraiseql-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fraiseql","download_url":"https://codeload.github.com/fraiseql/fraiseql-python/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fraiseql%2Ffraiseql-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34003814,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","fraiseql-v1","graphql","postgresql","python","rag"],"created_at":"2026-03-17T15:55:23.068Z","updated_at":"2026-06-07T00:01:43.433Z","avatar_url":"https://github.com/fraiseql.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FraiseQL\n\n[![Quality Gate](https://github.com/fraiseql/fraiseql-python/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/fraiseql/fraiseql-python/actions/workflows/ci.yml)\n[![Documentation](https://github.com/fraiseql/fraiseql-python/actions/workflows/docs.yml/badge.svg?branch=dev)](https://github.com/fraiseql/fraiseql-python/actions/workflows/docs.yml)\n[![Release](https://img.shields.io/github/v/release/fraiseql/fraiseql-python)](https://github.com/fraiseql/fraiseql-python/releases/latest)\n[![Python](https://img.shields.io/badge/Python-3.13+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**v1.9.17** | **Stable** | **Rust-Powered GraphQL for PostgreSQL**\n\n**Python**: 3.13+ | **PostgreSQL**: 13+\n\n---\n\n## GraphQL for the LLM era. Simple. Powerful. Rust-fast\n\nPostgreSQL returns JSONB. Rust transforms it. Zero Python overhead.\n\n```python\n# Complete GraphQL API in 15 lines\nimport fraiseql\nfrom fraiseql.fastapi import create_fraiseql_app\n\n@fraiseql.type(sql_source=\"v_user\", jsonb_column=\"data\")\nclass User:\n    \"\"\"A user in the system.\n\n    Fields:\n        id: Unique user identifier\n        name: User's full name\n        email: User's email address\n    \"\"\"\n    id: int\n    name: str\n    email: str\n\n@fraiseql.query\nasync def users(info) -\u003e list[User]:\n    \"\"\"Get all users.\"\"\"\n    db = info.context[\"db\"]\n    return await db.find(\"v_user\")\n\napp = create_fraiseql_app(\n    database_url=\"postgresql://localhost/mydb\",\n    types=[User],\n    queries=[users]\n)\n```\n\n---\n\n## 📌 FraiseQL Versions\n\nFraiseQL has two versions with overlapping but complementary strengths:\n\n### v1.9.16 (This Repository: `fraiseql-python`)\n\n**Python framework with integrated Rust pipeline**\n\n- ✅ **Stable, production-ready** (v1.9.16)\n- 🐍 **Python 3.13+ native** - write schema in Python decorators\n- 🚀 **Rust pipeline included** - 7-10x faster JSON transformation\n- 📡 **FastAPI runtime** - immediate deployment, hot reload, development-friendly\n- 🗄️ **PostgreSQL-only** - optimized for PostgreSQL expertise\n- 🔄 **Iterative development** - no build step, rapid feedback loops\n\n**Best for:** Python teams, rapid iteration, existing PostgreSQL codebases, teams that want Rust performance without leaving Python ecosystem\n\n**Repository:** [fraiseql/fraiseql-python](https://github.com/fraiseql/fraiseql-python)\n\n### v2 (Separate Repository: `fraiseql`)\n\n**Compiled Rust engine with polyglot schema authoring**\n\n- 🚀 **Beta stage** (v2.0.0-alpha.2) - feature-complete, actively developed\n- 🔧 **16+ language support** - Python, TypeScript, Go, Java, Rust, etc. (same schema authoring experience)\n- ⚡ **Compile-time optimization** - build-time schema validation, zero-cost abstractions\n- 🛠️ **CLI compiler** - `fraiseql-cli compile schema.json`\n- 🗄️ **Multi-database** - PostgreSQL, MySQL, SQLite, SQL Server\n- 🎯 **Maximum performance** - no runtime interpretation, fully compiled\n\n**Best for:** Teams with multiple language ecosystems, multi-database requirements, compile-time optimization, polyglot teams\n\n**Repository:** [fraiseql/fraiseql](https://github.com/fraiseql/fraiseql)\n\n### Comparison\n\n| Aspect | v1.9.16 | v2 |\n|--------|---------|-----|\n| **Schema in Python** | ✅ Native | ✅ Supported (1 of 16+ languages) |\n| **Rust Performance** | ✅ Included | ✅ Full engine in Rust |\n| **PostgreSQL Support** | ✅ Full | ✅ Full + 3 others |\n| **Deployment Model** | Runtime (FastAPI) | Build-time (CLI compile) |\n| **Development Experience** | Hot reload, iterative | Compile step, maximum optimization |\n| **Status** | ✅ Stable | 🚀 Beta |\n| **Best Migration Path** | Native Python → v2 Python | Python → any language |\n\n\u003e **If you're using Python:** Both versions work great! v1 for rapid iteration, v2 for compile-time guarantees and multi-DB future-proofing. Both are actively maintained.\n\n---\n\n## Why FraiseQL?\n\n- ⚡ **Rust Pipeline** - 7-10x faster JSON transformation, zero Python overhead\n- 🔒 **Secure by Design** - Explicit field contracts prevent data leaks\n- 🤖 **AI-Native** - LLMs generate correct code on first try\n- 💰 **Save $5-48K/year** - Eliminate Redis, Sentry, APM tools\n- 🔄 **GraphQL Cascade** - Automatic cache updates and side effect tracking\n- ✨ **Auto-populated mutations** - status, message, errors handled automatically (50-60% less boilerplate)\n- 🎯 **Auto-wired query params** - `where`, `orderBy`, `limit`, `offset` added automatically to list queries\n- 📝 **Auto-documentation** - Attribute docstrings become GraphQL descriptions automatically\n- 🔍 **Advanced filtering** - Full-text search, JSONB queries, array operations, regex\n- 🧠 **Vector search** - pgvector integration for semantic search, RAG, recommendations (6 distance operators)\n- 📋 **GraphQL compliant** - 85-90% GraphQL spec compliance with advanced fragment support\n\n---\n\n## Is This For You?\n\n**✅ Perfect if you:**\n\n- Build high-performance APIs with PostgreSQL\n- Want 7-10x faster JSON processing\n- Need enterprise security \u0026 compliance\n- Prefer database-first architecture\n- Use LLMs for code generation\n\n**❌ Consider alternatives if:**\n\n- You need multi-database support (PostgreSQL-only)\n- Building your first GraphQL API (use simpler frameworks)\n- Don't use JSONB columns in PostgreSQL\n\n---\n\n## How It Works\n\n**Traditional GraphQL** (slow):\n\n```\nPostgreSQL → Rows → ORM deserialize → Python objects → GraphQL serialize → JSON → Response\n            ╰─── Unnecessary roundtrips (2 conversions) ───╯\n```\n\n**FraiseQL** (fast):\n\n```\nPostgreSQL → JSONB → Rust field selection → HTTP Response\n           ╰─ Zero Python overhead (1 conversion) ─╯\n```\n\n### Why This Is Better\n\n1. **No ORM Overhead** - Database returns final JSONB, Rust transforms it\n2. **No N+1 Queries** - PostgreSQL composes everything in one query\n3. **Security Built-In** - View defines exactly what's exposed (impossible to leak)\n4. **Recursion Safe** - View structure prevents depth attacks naturally\n5. **AI-Friendly** - SQL + Python are massively trained; no magic frameworks\n\n---\n\n## Quick Start\n\n```bash\npip install fraiseql\nfraiseql init my-api\ncd my-api\nfraiseql dev\n```\n\n**Your GraphQL API is live at `http://localhost:8000/graphql`** 🎉\n\n**Next steps:**\n\n- [5-Minute Quickstart](docs/getting-started/quickstart.md)\n- [First Hour Guide](docs/getting-started/first-hour.md) - Build a complete blog API\n- [Understanding FraiseQL](docs/guides/understanding-fraiseql.md) - Architecture deep-dive\n\n---\n\n## Real Security, Not Theatre\n\n### The Problem (ORM-based frameworks)\n\n```python\nclass User(Base):  # SQLAlchemy\n    id = Column(Integer)\n    email = Column(String)\n    password_hash = Column(String)  # ← Sensitive!\n    api_key = Column(String)        # ← Sensitive!\n\n@strawberry.type\nclass UserType:\n    id: int\n    email: str\n    # Forgot to exclude password_hash and api_key!\n```\n\n**Result:** One mistake = data leak.\n\n### The Solution (FraiseQL)\n\n```sql\n-- PostgreSQL view defines what's exposed\nCREATE VIEW v_user AS\nSELECT id,\n  jsonb_build_object('id', id, 'email', email) as data\nFROM tb_user;\n-- password_hash and api_key aren't in JSONB = impossible to leak\n```\n\n**Result:** Structure defines the contract. No way to accidentally expose fields.\n\n---\n\n## Chaos Engineering \u0026 Resilience Testing\n\nFraiseQL separates testing into two workflows:\n\n| Aspect | Standard CI/CD | Chaos Engineering |\n|--------|---|---|\n| **Duration** | 15-20 min | 45-60 min |\n| **Purpose** | Correctness | Resilience |\n| **Trigger** | Every PR | Manual/Weekly |\n| **Tests** | Unit + Integration | 71 chaos scenarios |\n| **Blocks Merges** | Yes ✅ | No (informational) |\n| **Environment** | Lightweight | Real PostgreSQL + Docker |\n\n**Standard CI/CD:** Validates that features work correctly\n**Chaos Tests:** Validates that system recovers from failures\n\n[→ Learn about chaos engineering strategy](docs/archive/testing/chaos-engineering-strategy.md)\n\n---\n\n## Advanced Features\n\n### Specialized Type System (50+ scalar types)\n\n```python\nfrom fraiseql.types import EmailAddress, PhoneNumber, IPv4, Money, LTree\n\n@fraiseql.type(sql_source=\"v_users\")\nclass User:\n    email: EmailAddress      # Validated emails\n    phone: PhoneNumber       # International phone numbers\n    ip: IPv4                 # IP addresses with subnet operations\n    balance: Money           # Currency with precision\n    location: LTree          # Hierarchical paths\n```\n\n### Trinity Identifiers\n\nThree ID types for different purposes:\n\n- **pk_user** (int): Internal DB key, not exposed\n- **id** (UUID): Public API, stable, never changes\n- **identifier** (str): Human-readable slug, SEO-friendly\n\n### GraphQL Cascade\n\nAutomatic cache invalidation when mutations change related data:\n\n```graphql\nmutation {\n  createPost(input: {...}) {\n    post { id title }\n    cascade {\n      updated { __typename }     # What changed\n      invalidations { queryName } # Which queries to invalidate\n    }\n  }\n}\n```\n\n---\n\n## Enterprise Security Features\n\n- **KMS Integration:** Vault, AWS KMS, GCP Cloud KMS\n- **Security Profiles:** STANDARD, REGULATED, RESTRICTED (government-grade)\n- **SBOM Generation:** Automated compliance (FedRAMP, NIS2, HIPAA, PCI-DSS)\n- **Audit Logging:** Cryptographic chain (SHA-256 + HMAC)\n- **Row-Level Security:** PostgreSQL RLS integration\n- **Rate Limiting:** Per-endpoint and per-GraphQL operation\n\n[🔐 Security Configuration](docs/production/security.md)\n\n### 🔍 Security Feature Implementation Status\n\n| Feature | Configured | Enforced | Tested | Production Ready | Notes |\n|---------|-----------|----------|--------|------------------|-------|\n| **Authentication** | ✅ | ✅ | ⚠️ Partial | ⚠️ Use with caution | Rust-based JWT validation via `PyAuthProvider` |\n| **RBAC Framework** | ✅ | ✅ | ⚠️ Framework only | ⚠️ Use with caution | Permission resolution complete, enforcement verification tests pending |\n| **Security Profiles** | ✅ | ⚠️ Partial | ⚠️ Partial | ❌ Not production ready | TLS/rate limiting enforced; query limits/audit pending |\n| **Field Filtering (Mutations)** | ✅ | ✅ | ✅ | ✅ Production ready | Full implementation (v1.9.16+) |\n| **Field Filtering (APQ)** | ✅ | ✅ | ⚠️ Partial | ⚠️ Limited scope | APQ queries only |\n| **Field Filtering (Queries)** | ⚠️ | ⚠️ | ⚠️ | ⚠️ Verification needed | Non-APQ query filtering status unclear |\n| **Rate Limiting** | ✅ | ✅ | ✅ | ✅ Production ready | Per-endpoint and per-operation |\n| **CSRF Protection** | ✅ | ✅ | ✅ | ✅ Production ready | Automatic middleware |\n| **Security Headers** | ✅ | ✅ | ✅ | ✅ Production ready | Defense in depth |\n| **Body Size Limits** | ✅ | ✅ | ✅ | ✅ Production ready | Configurable per profile |\n| **TLS Enforcement** | ✅ | ✅ | ✅ | ✅ Production ready | Profile-based |\n| **Query Depth Limits** | ✅ Config | ❌ Pending | ❌ | ❌ Not ready | Validator middleware needed |\n| **Query Complexity** | ✅ Config | ❌ Pending | ❌ | ❌ Not ready | AST analysis pending |\n| **Introspection Policy** | ✅ Config | ❌ Pending | ❌ | ❌ Not ready | Control logic pending |\n| **Audit Logging** | ✅ Config | ❌ Pending | ❌ | ❌ Not ready | Middleware implementation needed |\n\n**Legend:**\n\n- ✅ Complete and verified\n- ⚠️ Partial implementation or limited scope\n- ❌ Not implemented or not production ready\n\n**Roadmap:**\n\n- **v1.9.16**: Complete security profile enforcement (Issue #225)\n- **v1.9.16**: Add RBAC enforcement verification tests\n- **v1.9.16**: Unified field filtering for all query types\n- **v1.9.16**: Full security audit and penetration testing\n\n\u003e **Important**: This matrix reflects current implementation status (v1.9.16). Security features are under active development. Always verify features meet your requirements before production deployment. See [Issue #225](https://github.com/fraiseql/fraiseql-python/issues/225) for implementation progress.\n\n---\n\n## Cost Savings: Replace 4 Services with 1 Database\n\n| Service | Cost | FraiseQL Approach | Savings |\n|---------|------|------------------|---------|\n| Redis (caching) | $50-500/mo | PostgreSQL UNLOGGED tables | $600-6,000/yr |\n| Sentry (error tracking) | $300-3,000/mo | PostgreSQL error logging | $3,600-36,000/yr |\n| APM Tool | $100-500/mo | PostgreSQL traces | $1,200-6,000/yr |\n| **Total** | **$450-4,000/mo** | **PostgreSQL only ($50/mo)** | **$5,400-48,000/yr** |\n\n### 📋 Software Bill of Materials (SBOM)\n\n- **Automated generation** via `fraiseql sbom generate`\n- **Global compliance**: US EO 14028, EU NIS2/CRA, PCI-DSS 4.0, ISO 27001\n- **CycloneDX 1.5 format** with cryptographic signing\n- **CI/CD integration** for continuous compliance\n\n### 🔑 Key Management Service (KMS)\n\n- **HashiCorp Vault**: Production-ready with transit engine\n- **AWS KMS**: Native integration with GenerateDataKey\n- **GCP Cloud KMS**: Envelope encryption support\n- **Local Provider**: Development-only with warnings\n\n### 🛡️ Security Profiles\n\n- `STANDARD`: Default protections for general applications\n- `REGULATED`: PCI-DSS/HIPAA/SOC 2 compliance\n- `RESTRICTED`: Government, defence, critical infrastructure\n  - 🇺🇸 FedRAMP, DoD, NIST 800-53\n  - 🇪🇺 NIS2 Essential Entities, EU CRA\n  - 🇨🇦 CPCSC (defence contractors)\n  - 🇦🇺 Essential Eight Level 3\n  - 🇸🇬 Singapore CII operators\n\n### 📊 Observability\n\n- OpenTelemetry tracing with sensitive data sanitization\n- Security event logging\n- Audit trail support\n\n### 🔒 Advanced Security Controls\n\n- **Rate limiting** for API endpoints and GraphQL operations\n- **CSRF protection** for mutations and forms\n- **Security headers** middleware for defense in depth\n- **Input validation** and sanitization\n- **Field-level authorization** with role inheritance\n- **Row-level security** via PostgreSQL RLS\n\n**[📋 KMS Architecture](https://github.com/fraiseql/fraiseql-python/blob/main/docs/architecture/decisions/0003-kms-architecture.md)**\n\n---\n\n## Code Examples\n\n### Complete CRUD API\n\n```python\n@fraiseql.input\nclass CreateUserInput:\n    email: str  # AI sees exact input structure\n    name: str\n\n@fraiseql.success\nclass UserCreated:\n    user_id: str  # AI sees success response\n    # Note: @success auto-injects: status, message, updated_fields, id\n\n@fraiseql.error\nclass ValidationError:\n    error: str    # AI sees failure cases\n    code: str = \"VALIDATION_ERROR\"\n\n@fraiseql.mutation(function=\"fn_create_user\", schema=\"public\")\nclass CreateUser:\n    input: CreateUserInput\n    success: UserCreated\n    failure: ValidationError  # Note: Use 'failure' field, not '@failure' decorator\n\n# That's it! FraiseQL automatically:\n# 1. Calls public.fn_create_user(input) with input as dict\n# 2. Parses JSONB result into UserCreated or ValidationError\n```\n\n### Why AI Loves This\n\n- ✅ **SQL + Python** - Massively trained languages (no proprietary DSLs)\n- ✅ **JSONB everywhere** - Clear data structures, obvious contracts\n- ✅ **Database functions** - Complete context in one file\n- ✅ **Explicit logging** - AI can trace execution without debugging\n- ✅ **No abstraction layers** - What you see is what executes\n\n**Real Impact:** Claude Code, GitHub Copilot, and ChatGPT generate correct FraiseQL code on first try.\n\n---\n\n## 📖 Core Concepts\n\n**New to FraiseQL?** Understanding these core concepts will help you make the most of the framework:\n\n**[📚 Concepts \u0026 Glossary](https://github.com/fraiseql/fraiseql-python/blob/main/docs/core/concepts-glossary.md)** - Essential terminology and mental models:\n\n- **CQRS Pattern** - Separate read models (views) from write models (functions)\n- **Trinity Identifiers** - Three-tier ID system (`pk_*`, `id`, `identifier`) for performance and UX\n- **JSONB Views** - PostgreSQL composes data once, eliminating N+1 queries\n- **Database-First Architecture** - Start with PostgreSQL, GraphQL follows\n- **Explicit Sync Pattern** - Table views (`tv_*`) for complex queries\n\n**Quick links:**\n\n- [Understanding FraiseQL](https://github.com/fraiseql/fraiseql-python/blob/main/docs/guides/understanding-fraiseql.md) - 10-minute architecture overview\n- [Database API](https://github.com/fraiseql/fraiseql-python/blob/main/docs/core/database-api.md) - Connection pooling and query execution\n- [Types and Schema](https://github.com/fraiseql/fraiseql-python/blob/main/docs/core/types-and-schema.md) - Complete type system guide\n- [Filter Operators](https://github.com/fraiseql/fraiseql-python/blob/main/docs/advanced/filter-operators.md) - Advanced PostgreSQL filtering (arrays, full-text search, JSONB, regex)\n\n---\n\n## ✨ See How Simple It Is\n\n### Complete CRUD API in 20 Lines\n\n```python\nfrom uuid import UUID\nfrom fraiseql import type, query, mutation, input, success\n\n@fraiseql.type(sql_source=\"v_note\", jsonb_column=\"data\")\nclass Note:\n    id: int\n    title: str\n    content: str | None\n\n@fraiseql.query\nasync def notes(info) -\u003e list[Note]:\n    return await info.context[\"db\"].find(\"v_note\")\n\n@fraiseql.query\nasync def note(info, id: UUID) -\u003e Note | None:\n    \"\"\"Get a note by ID.\"\"\"\n    db = info.context[\"db\"]\n    return await db.find_one(\"v_note\", id=id)\n\n# Step 3: Define mutations\n@fraiseql.input\nclass CreateNoteInput:\n    title: str\n    content: str | None = None\n\n@fraiseql.mutation\nclass CreateNote:\n    input: CreateNoteInput\n    success: Note\n\napp = create_fraiseql_app(\n    database_url=\"postgresql://localhost/mydb\",\n    types=[Note],\n    queries=[notes],\n    mutations=[CreateNote]\n)\n```\n\n### Database-First Pattern\n\n```sql\n-- PostgreSQL view (composable, no N+1)\nCREATE VIEW v_user AS\nSELECT id,\n  jsonb_build_object(\n    'id', id,\n    'name', name,\n    'email', email,\n    'posts', (\n      SELECT jsonb_agg(...)\n      FROM tb_post p\n      WHERE p.user_id = tb_user.id\n    )\n  ) as data\nFROM tb_user;\n```\n\n```python\n# Python type mirrors the view\n@fraiseql.type(sql_source=\"v_user\", jsonb_column=\"data\")\nclass User:\n    id: int\n    name: str\n    email: str\n    posts: list[Post]  # Nested relations! No N+1 queries!\n\n# Step 3: Query it\n@fraiseql.query\nasync def users(info) -\u003e list[User]:\n    db = info.context[\"db\"]\n    return await db.find(\"v_user\")\n```\n\n**No ORM. No complex resolvers. PostgreSQL composes data, Rust transforms it.**\n\n### Mutations with Business Logic\n\n```sql\nCREATE OR REPLACE FUNCTION fn_publish_post(p_post_id UUID) RETURNS JSONB AS $$\nDECLARE\n    v_post RECORD;\nBEGIN\n    -- Get post with user info (Trinity pattern: JOIN on pk_user)\n    SELECT p.*, u.email as user_email\n    INTO v_post\n    FROM tb_post p\n    JOIN tb_user u ON p.fk_user = u.pk_user  -- ✅ Trinity: INTEGER FK to pk_user\n    WHERE p.id = p_post_id;\n\n    -- Validate post exists\n    IF NOT FOUND THEN\n        RETURN jsonb_build_object('success', false, 'error', 'Post not found');\n    END IF;\n\n    -- Validate not already published\n    IF v_post.published_at IS NOT NULL THEN\n        RETURN jsonb_build_object('success', false, 'error', 'Post already published');\n    END IF;\n\n    -- Update post\n    UPDATE tb_post\n    SET published_at = NOW()\n    WHERE id = p_post_id;\n\n    -- Sync projection table\n    PERFORM fn_sync_tv_post(p_post_id);\n\n    -- Log event\n    INSERT INTO audit_log (action, details)\n    VALUES ('post_published', jsonb_build_object('post_id', p_post_id, 'user_email', v_post.user_email));\n\n    -- Return success\n    RETURN jsonb_build_object('success', true, 'post_id', p_post_id);\nEND;\n$$ LANGUAGE plpgsql;\n```\n\n**Business logic, validation, logging - all in the database function. Crystal clear for humans and AI.**\n\n### Selective CASCADE Querying\n\nRequest only the CASCADE data you need:\n\n```graphql\nmutation CreatePost($input: CreatePostInput!) {\n  createPost(input: $input) {\n    post { id title }\n\n    # Option 1: No CASCADE (smallest payload)\n    # Just omit the cascade field\n\n    # Option 2: Metadata only\n    cascade {\n      metadata { affectedCount }\n    }\n\n    # Option 3: Full CASCADE\n    cascade {\n      updated { __typename id entity }\n      deleted { __typename id }\n      invalidations { queryName }\n      metadata { affectedCount }\n    }\n  }\n}\n```\n\nPerformance: Not requesting CASCADE reduces response size by 2-10x.\n\n---\n\n## 💰 In PostgreSQL Everything\n\nReplace 4 services with 1 database.\n\n### Cost Savings Calculator\n\n| Traditional Stack | FraiseQL Stack | Annual Savings |\n|-------------------|----------------|----------------|\n| PostgreSQL: $50/mo | PostgreSQL: $50/mo | - |\n| **Redis Cloud:** $50-500/mo | ✅ **In PostgreSQL** | **$600-6,000/yr** |\n| **Sentry:** $300-3,000/mo | ✅ **In PostgreSQL** | **$3,600-36,000/yr** |\n| **APM Tool:** $100-500/mo | ✅ **In PostgreSQL** | **$1,200-6,000/yr** |\n| **Total: $500-4,050/mo** | **Total: $50/mo** | **$5,400-48,000/yr** |\n\n### How It Works\n\n**Caching (Replaces Redis)**\n\n```python\nfrom fraiseql.caching import PostgresCache\n\ncache = PostgresCache(db_pool)\nawait cache.set(\"user:123\", user_data, ttl=3600)\n\n# Uses PostgreSQL UNLOGGED tables\n# - No WAL overhead = fast writes\n# - Shared across instances\n# - TTL-based expiration\n# - Pattern-based deletion\n```\n\n**Error Tracking (Replaces Sentry)**\n\n```python\nfrom fraiseql.monitoring import init_error_tracker\n\ntracker = init_error_tracker(db_pool, environment=\"production\")\nawait tracker.capture_exception(error, context={...})\n\n# Features:\n# - Automatic error fingerprinting and grouping\n# - Full stack trace capture\n# - OpenTelemetry trace correlation\n# - Custom notifications (Email, Slack, Webhook)\n```\n\n**Observability (Replaces APM)**\n\n```sql\n-- All traces and metrics stored in PostgreSQL\nSELECT * FROM monitoring.traces\nWHERE error_id = 'error-123'\n  AND trace_id = 'trace-xyz';\n```\n\n**Grafana Dashboards**\nPre-built dashboards in `grafana/` query PostgreSQL directly:\n\n- Error monitoring dashboard\n- Performance metrics dashboard\n- OpenTelemetry traces dashboard\n\n### Operational Benefits\n\n- ✅ **70% fewer services** to deploy and monitor\n- ✅ **One database to backup** (not 4 separate systems)\n- ✅ **No Redis connection timeouts** or cluster issues\n- ✅ **No Sentry quota surprises** or rate limiting\n- ✅ **ACID guarantees** for everything (no eventual consistency)\n- ✅ **Self-hosted** - full control, no vendor lock-in\n\n---\n\n## 🏗️ Architecture Deep Dive\n\n### Rust-First Execution\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   GraphQL       │ →  │   PostgreSQL     │ →  │   Rust          │\n│   Request       │    │   JSONB Query    │    │   Transform     │\n│                 │    │                  │    │   (7-10x faster)│\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n                                                        ↓\n                                               ┌─────────────────┐\n                                               │   FastAPI       │\n                                               │   HTTP Response │\n                                               └─────────────────┘\n```\n\n**Unified path for all queries:**\n\n1. **GraphQL query** arrives at FastAPI\n2. **Python resolver** calls PostgreSQL view/function\n3. **PostgreSQL** returns pre-composed JSONB\n4. **Rust pipeline** transforms JSONB based on GraphQL selection\n5. **FastAPI** returns bytes directly (zero Python serialization)\n\n### CQRS Pattern\n\nFraiseQL implements Command Query Responsibility Segregation:\n\n```\n┌─────────────────────────────────────┐\n│         GraphQL API                 │\n├──────────────────┬──────────────────┤\n│   QUERIES        │   MUTATIONS      │\n│   (Reads)        │   (Writes)       │\n├──────────────────┼──────────────────┤\n│  v_* views       │  fn_* functions  │\n│  tv_* tables     │  tb_* tables     │\n│  JSONB ready     │  Business logic  │\n└──────────────────┴──────────────────┘\n```\n\n**Queries use views:**\n\n- `v_*` - Real-time views with JSONB computation\n- `tv_*` - Denormalized tables with generated JSONB columns (for complex queries)\n\n**Mutations use functions:**\n\n- `fn_*` - Business logic, validation, side effects\n- `tb_*` - Base tables for data storage\n\n**[📊 Detailed Architecture Diagrams](https://github.com/fraiseql/fraiseql-python/blob/main/docs/guides/understanding-fraiseql.md)**\n\n### Key Innovations\n\n**1. Exclusive Rust Pipeline**\n\n- PostgreSQL → Rust → HTTP (no Python JSON processing)\n- 7-10x faster JSON transformation vs Python\n- No GIL contention, compiled performance\n\n**2. JSONB Views**\n\n- Database composes data once\n- Rust selects fields based on GraphQL query\n- No N+1 query problems\n\n**3. Table Views (tv_*)**\n\n```sql\n-- Denormalized JSONB table with explicit sync\nCREATE TABLE tv_user (\n    id INT PRIMARY KEY,\n    data JSONB NOT NULL,  -- Regular column, not generated\n    updated_at TIMESTAMPTZ DEFAULT NOW()\n);\n\n-- Sync function populates tv_* from v_* view\nCREATE FUNCTION fn_sync_tv_user(p_user_id INT) RETURNS VOID AS $$\nBEGIN\n    INSERT INTO tv_user (id, data)\n    SELECT id, data FROM v_user WHERE id = p_user_id\n    ON CONFLICT (id) DO UPDATE SET\n        data = EXCLUDED.data,\n        updated_at = NOW();\nEND;\n$$ LANGUAGE plpgsql;\n\n-- Mutations call sync explicitly\nCREATE FUNCTION fn_create_user(p_name TEXT) RETURNS JSONB AS $$\nDECLARE v_user_id INT;\nBEGIN\n    INSERT INTO tb_user (name) VALUES (p_name) RETURNING id INTO v_user_id;\n    PERFORM fn_sync_tv_user(v_user_id);  -- ← Explicit sync call\n    RETURN (SELECT data FROM tv_user WHERE id = v_user_id);\nEND;\n$$ LANGUAGE plpgsql;\n```\n\nBenefits: Instant lookups, embedded relations, explicitly synchronized\n\n**4. Zero-Copy Response**\n\n- Direct RustResponseBytes to FastAPI\n- No Python serialization overhead\n- Optimal for high-throughput APIs\n\n---\n\n## 🎯 How FraiseQL Is Different\n\n### Execution Path Comparison\n\n| Framework | Data Flow | JSON Processing | Recursion Protection | Security Model |\n|-----------|-----------|-----------------|----------------------|----------------|\n| **FraiseQL** | PostgreSQL JSONB → Rust → HTTP | ✅ Rust (compiled) | ✅ View-enforced | ✅ Explicit contracts |\n| Strawberry + SQLAlchemy | PostgreSQL → ORM → Python dict → JSON | ❌ Python (2 steps) | ⚠️ Middleware required | ❌ ORM over-fetching risk |\n| Hasura | PostgreSQL → Haskell → JSON | ⚠️ Haskell | ⚠️ Middleware required | ⚠️ Complex permission system |\n| PostGraphile | PostgreSQL → Node.js → JSON | ⚠️ JavaScript | ⚠️ Middleware required | ⚠️ Plugin-based |\n\n### FraiseQL's Unique Advantages\n\n- ✅ **Database returns final structure** (JSONB views)\n- ✅ **Rust handles field selection** (compiled performance)\n- ✅ **No Python in hot path** (zero serialization overhead)\n- ✅ **No ORM abstraction** (SQL functions are business logic)\n- ✅ **Built-in recursion protection** (view defines max depth, no middleware needed)\n- ✅ **Secure by design** (explicit field contracts prevent data leaks)\n- ✅ **AI-readable** (clear contracts, full context visible)\n- ✅ **PostgreSQL-native** (caching, monitoring, APQ in one database)\n\n---\n\n## 🎯 Advanced Features\n\n### Automatic Persisted Queries (APQ)\n\nEnterprise-grade APQ with pluggable storage backends:\n\n```python\nfrom fraiseql import FraiseQLConfig\n\n# Memory backend (zero configuration)\nconfig = FraiseQLConfig(apq_storage_backend=\"memory\")\n\n# PostgreSQL backend (multi-instance coordination)\nconfig = FraiseQLConfig(\n    apq_storage_backend=\"postgresql\",\n    apq_storage_schema=\"apq_cache\"\n)\n```\n\n**How it works:**\n\n1. Client sends query hash instead of full query\n2. FraiseQL checks storage backend for cached query\n3. PostgreSQL → Rust → HTTP (same fast path)\n4. Bandwidth reduction with large queries\n\n**[⚡ APQ Details](https://github.com/fraiseql/fraiseql-python/blob/main/docs/diagrams/apq-cache-flow.md)**\n\n### Specialized Type System\n\nAdvanced operators for network types, hierarchical data, ranges, and nested arrays:\n\n```graphql\nquery {\n  servers(where: {\n    ipAddress: { eq: \"192.168.1.1\" }          # → ::inet casting\n    port: { gt: 1024 }                        # → ::integer casting\n    location: { ancestor_of: \"US.CA\" }        # → ltree operations\n    dateRange: { overlaps: \"[2024-01-01,2024-12-31)\" }\n\n    # Nested array filtering with logical operators\n    printServers(where: {\n      AND: [\n        { operatingSystem: { in: [\"Linux\", \"Windows\"] } }\n        { OR: [\n            { nTotalAllocations: { gte: 100 } }\n            { NOT: { ipAddress: { isnull: true } } }\n          ]\n        }\n      ]\n    }) {\n      hostname operatingSystem\n    }\n  }) {\n    id name ipAddress port\n  }\n}\n```\n\n**50+ Specialized Scalar Types:**\n\n**Financial \u0026 Trading:**\n\n- CUSIP, ISIN, SEDOL, MIC, LEI - Security identifiers\n- Money, Percentage, ExchangeRate - Financial values\n- CurrencyCode, StockSymbol - Trading symbols\n\n**Network \u0026 Infrastructure:**\n\n- IPv4, IPv6, CIDR, MACAddress - Network addresses with subnet operations\n- Hostname, DomainName, Port, EmailAddress - Internet identifiers\n- APIKey, HashSHA256 - Security tokens\n\n**Geospatial \u0026 Location:**\n\n- Coordinate, Latitude, Longitude - Geographic coordinates with distance calculations\n- PostalCode, Timezone - Location data\n\n**Business \u0026 Logistics:**\n\n- ContainerNumber, FlightNumber, TrackingNumber, VIN - Asset identifiers\n- IBAN, LicensePlate - Financial \u0026 vehicle identifiers\n- PhoneNumber, LocaleCode, LanguageCode - Contact \u0026 localization\n\n**Technical \u0026 Data:**\n\n- UUID, JSON, Date, DateTime, Time, DateRange - Standard types with validation\n- LTree - Hierarchical data with ancestor/descendant queries\n- SemanticVersion, Color, MIMEType, File, Image - Specialized formats\n- HTML, Markdown - Rich text content\n\n**Advanced Filtering:** Full-text search, JSONB queries, array operations, regex, vector similarity search on all types\n\n#### Scalar Type Usage Examples\n\n```python\nfrom fraiseql import type\nfrom fraiseql.types import (\n    EmailAddress, PhoneNumber, Money, Percentage,\n    CUSIP, ISIN, IPv4, MACAddress, LTree, DateRange\n)\n\n@fraiseql.type(sql_source=\"v_financial_data\")\nclass FinancialRecord:\n    id: int\n    email: EmailAddress           # Validated email addresses\n    phone: PhoneNumber           # International phone numbers\n    balance: Money               # Currency amounts with precision\n    margin: Percentage           # Percentages (0.00-100.00)\n    security_id: CUSIP | ISIN    # Financial instrument identifiers\n\n@fraiseql.type(sql_source=\"v_network_device\")\nclass NetworkDevice:\n    id: int\n    ip_address: IPv4             # IPv4 addresses with subnet operations\n    mac_address: MACAddress      # MAC addresses with validation\n    location: LTree              # Hierarchical location paths\n    maintenance_window: DateRange # Date ranges with overlap queries\n```\n\n```graphql\n# Advanced filtering with specialized types\nquery {\n  financialRecords(where: {\n    balance: { gte: \"1000.00\" }           # Money comparison\n    margin: { between: [\"5.0\", \"15.0\"] }   # Percentage range\n    security_id: { eq: \"037833100\" }       # CUSIP validation\n  }) {\n    id balance margin security_id\n  }\n\n  networkDevices(where: {\n    ip_address: { inSubnet: \"192.168.1.0/24\" }  # CIDR operations\n    location: { ancestor_of: \"US.CA.SF\" }       # LTree hierarchy\n    maintenance_window: { overlaps: \"[2024-01-01,2024-12-31)\" }\n  }) {\n    id ip_address location\n  }\n}\n```\n\n**[📖 Nested Array Filtering Guide](https://github.com/fraiseql/fraiseql-python/blob/main/docs/guides/nested-array-filtering.md)**\n\n### Enterprise Security\n\n```python\nfrom fraiseql import authorized\n\n@fraiseql.authorized(roles=[\"admin\", \"editor\"])\n@fraiseql.mutation\nclass DeletePost:\n    \"\"\"Only admins and editors can delete posts.\"\"\"\n    input: DeletePostInput\n    success: DeleteSuccess\n    failure: PermissionDenied\n\n# Features:\n# - Field-level authorization with role inheritance\n# - Row-level security via PostgreSQL RLS\n# - Unified audit logging with cryptographic chain (SHA-256 + HMAC)\n# - Multi-tenant isolation\n# - Rate limiting and CSRF protection\n```\n\n### Trinity Identifiers\n\nThree types of identifiers per entity for different purposes:\n\n```python\n@fraiseql.type(sql_source=\"v_post\")\nclass Post(TrinityMixin):\n    \"\"\"\n    Trinity Pattern:\n    - pk_post (int): Internal SERIAL key (NOT exposed, only in database)\n    - id (UUID): Public API key (exposed, stable)\n    - identifier (str): Human-readable slug (exposed, SEO-friendly)\n    \"\"\"\n\n    # GraphQL exposed fields\n    id: UUID                  # Public API (stable, secure)\n    identifier: str | None    # Human-readable (SEO-friendly, slugs)\n    title: str\n    content: str\n    # ... other fields\n\n    # pk_post is NOT a field - accessed via TrinityMixin.get_internal_pk()\n```\n\n**Why three?**\n\n- **pk_\\*:** Fast integer joins (PostgreSQL only, never in GraphQL schema)\n- **id:** Public API stability (UUID, exposed, never changes)\n- **identifier:** Human-friendly URLs (exposed, SEO, readability)\n\n---\n\n## 🚀 Get Started in 5 Minutes\n\n```bash\n# Install\npip install fraiseql\n\n# Create project\nfraiseql init my-api\ncd my-api\n\n# Setup database\ncreatedb my_api\npsql my_api \u003c schema.sql\n\n# Start server\nfraiseql dev\n```\n\n**Your GraphQL API is live at \u003chttp://localhost:8000/graphql\u003e** 🎉\n\n### Next Steps\n\n- **📚 [First Hour Guide](https://github.com/fraiseql/fraiseql-python/blob/main/docs/getting-started/first-hour.md)** - Build a complete blog API (60 minutes, hands-on)\n- **🧠 [Understanding FraiseQL](https://github.com/fraiseql/fraiseql-python/blob/main/docs/guides/understanding-fraiseql.md)** - Architecture deep dive (10 minute read)\n- **⚡ [5-Minute Quickstart](https://github.com/fraiseql/fraiseql-python/blob/main/docs/getting-started/quickstart.md)** - Copy, paste, run\n- **📖 [Full Documentation](https://github.com/fraiseql/fraiseql-python/tree/main/docs)** - Complete guides and references\n\n### Prerequisites\n\n- **Python 3.13+** (required for Rust pipeline integration and advanced type features)\n- **PostgreSQL 13+**\n\n**[📖 Detailed Installation Guide](docs/getting-started/installation.md)** - Platform-specific instructions, troubleshooting\n\n---\n\n## 🚦 Is FraiseQL Right for You?\n\n### ✅ Perfect For\n\n- **PostgreSQL-first teams** already using PostgreSQL extensively\n- **Performance-critical APIs** requiring efficient data access\n- **Multi-tenant SaaS** with per-tenant isolation needs\n- **Cost-conscious startups** ($5-48K annual savings vs traditional stack)\n- **AI-assisted development** teams using Claude/Copilot/ChatGPT\n- **Operational simplicity** - one database for everything\n- **Self-hosted infrastructure** - full control, no vendor lock-in\n\n### ❌ Consider Alternatives\n\n- **Multi-database support** - FraiseQL is PostgreSQL-specific\n- **Simple CRUD APIs** - Traditional REST may be simpler\n- **Non-PostgreSQL databases** - FraiseQL requires PostgreSQL\n- **Microservices** - Better for monolithic or database-per-service\n\n---\n\n## 🛠️ CLI Commands\n\n```bash\n# Project management\nfraiseql init \u003cname\u003e           # Create new project\nfraiseql dev                   # Development server with hot reload\nfraiseql check                 # Validate schema and configuration\n\n# Code generation\nfraiseql generate schema       # Export GraphQL schema\nfraiseql generate types        # Generate TypeScript definitions\n\n# Database utilities\nfraiseql sql analyze \u003cquery\u003e   # Analyze query performance\nfraiseql sql explain \u003cquery\u003e   # Show PostgreSQL execution plan\n```\n\n---\n\n## Learn More\n\n- **[Full Documentation](https://github.com/fraiseql/fraiseql-python/tree/main/docs)** - Comprehensive guides\n- **[Architecture Decisions](https://github.com/fraiseql/fraiseql-python/tree/main/docs/architecture)** - Why we built it this way\n- **[Performance Guide](https://github.com/fraiseql/fraiseql-python/blob/main/docs/performance/index.md)** - Optimization strategies\n- **[Examples](https://github.com/fraiseql/fraiseql-python/tree/main/examples)** - Real-world applications\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/fraiseql/fraiseql-python\ncd fraiseql-python \u0026\u0026 make setup-dev\nprek install  # 7-10x faster than pre-commit\n```\n\n[→ Contributing Guide](CONTRIBUTING.md)\n\n---\n\n## About\n\nFraiseQL is created by **Lionel Hamayon** ([@evoludigit](https://github.com/evoludigit)).\n\n**The Idea:** What if PostgreSQL returned JSON directly instead of Python serializing it? No ORM. No N+1 queries. No Python overhead. Just Rust transforming JSONB to HTTP.\n\n**The Result:** A GraphQL framework that's 7-10x faster and designed for the LLM era.\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n---\n\n## 📋 Project Navigation\n\n### FraiseQL Ecosystem\n\n| Project | Version | Repository | Status | Best For |\n|---------|---------|-----------|--------|----------|\n| **fraiseql-python** (v1) | v1.9.16 | [fraiseql/fraiseql-python](https://github.com/fraiseql/fraiseql-python) | ✅ Stable | Python teams, rapid iteration |\n| **fraiseql** (v2) | v2.0.0-alpha.2 | [fraiseql/fraiseql](https://github.com/fraiseql/fraiseql) | 🚀 Beta | Multi-language, multi-database |\n\n**This Repository:** `fraiseql-python` (v1.9.16 - Python-based with Rust pipeline)\n\n### Quick Navigation\n\n**New to FraiseQL?**\n\n- Start here: **[First Hour Guide](https://github.com/fraiseql/fraiseql-python/blob/main/docs/getting-started/first-hour.md)** (60 min, hands-on)\n- Architecture overview: **[Understanding FraiseQL](https://github.com/fraiseql/fraiseql-python/blob/main/docs/guides/understanding-fraiseql.md)** (10 min read)\n- Project structure: **[Strategic Overview](https://github.com/fraiseql/fraiseql-python/blob/main/docs/strategic/PROJECT_STRUCTURE.md)**\n\n**Exploring v2?**\n\n- v2 Repository: **[fraiseql/fraiseql](https://github.com/fraiseql/fraiseql)**\n- v2 Documentation: **[fraiseql.readthedocs.io](https://fraiseql.readthedocs.io)**\n\n**Troubleshooting:**\n\n- **[Complete Version Roadmap](https://github.com/fraiseql/fraiseql-python/blob/main/dev/audits/version-status.md)** - Version status and feature matrix\n\n---\n\n## 🚀 Get Started Now\n\n**Ready to build the most efficient GraphQL API in Python?**\n\n```bash\npip install fraiseql \u0026\u0026 fraiseql init my-api\n```\n\n📚 Documentation: [github.com/fraiseql/fraiseql-python](https://github.com/fraiseql/fraiseql-python)\n\n🚀 **PostgreSQL → Rust → Production**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraiseql%2Ffraiseql-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffraiseql%2Ffraiseql-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffraiseql%2Ffraiseql-python/lists"}