| Name | fraiseql JSON |
| Version |
0.7.21
JSON |
| download |
| home_page | None |
| Summary | Production-ready GraphQL API framework for PostgreSQL with CQRS, JSONB optimization, and type-safe mutations |
| upload_time | 2025-09-14 18:04:19 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.13 |
| license | MIT |
| keywords |
api
async
database
fastapi
graphql
jsonb
orm
postgresql
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# FraiseQL
[](https://github.com/fraiseql/fraiseql/actions/workflows/quality-gate.yml)
[](https://github.com/fraiseql/fraiseql/actions/workflows/docs.yml)
[](https://github.com/fraiseql/fraiseql/releases/latest)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
**The fastest Python GraphQL framework.** Pre-compiled queries, PostgreSQL-native caching, and sub-millisecond responses out of the box.
> **4-100x faster** than traditional GraphQL frameworks • **Database-first architecture** • **Zero external dependencies**
## 🚀 Why FraiseQL?
### **⚡ Blazing Fast Performance**
- **Pre-compiled queries**: SHA-256 hash lookup instead of parsing (4-10x faster)
- **PostgreSQL-native caching**: No Redis, no external dependencies
- **Sub-millisecond responses**: 2-5ms cached, 25-60ms uncached
- **Real production benchmarks**: 85-95% cache hit rate
### **🏗️ Database-First Architecture**
- **CQRS by design**: Commands via PostgreSQL functions, queries via views
- **JSONB-powered**: Flexible schema evolution with full type safety
- **View-based queries**: `v_*` for real-time, `tv_*` for materialized performance
- **PostgreSQL does the heavy lifting**: Joins, aggregations, transformations in-database
### **🔧 Developer Experience**
- **Type-safe**: Full Python 3.13+ type hints with automatic GraphQL schema generation
- **One command setup**: `fraiseql init my-api && fraiseql dev`
- **Intelligent WHERE clauses**: Automatic type-aware SQL optimization for network types, dates, and more
- **Built-in security**: Field-level authorization, rate limiting, CSRF protection
## 🏁 Quick Start
```bash
# Install and create project
pip install fraiseql
fraiseql init my-api && cd my-api
# Define your types
cat > src/types.py << 'EOF'
import fraiseql
from fraiseql import ID, EmailAddress
@fraiseql.type
class User:
id: ID
email: EmailAddress
name: str
created_at: str
EOF
# Create database view (returns JSONB)
cat > db/001_user_view.sql << 'EOF'
CREATE VIEW v_user AS
SELECT jsonb_build_object(
'id', pk_user,
'email', email,
'name', name,
'created_at', created_at::text
) AS data FROM tb_users;
EOF
# Define queries
cat > src/queries.py << 'EOF'
import fraiseql
from .types import User
@fraiseql.query
async def users(info) -> list[User]:
repo = info.context["repo"]
return await repo.find("v_user")
EOF
# Start development server
fraiseql dev
```
Your GraphQL API is live at `http://localhost:8000/graphql` 🎉
## 🎯 Core Features
### **Advanced Type System**
Specialized operators for network types, hierarchical data, and ranges:
```graphql
query {
servers(where: {
ipAddress: { eq: "192.168.1.1" } # → ::inet casting
port: { gt: 1024 } # → ::integer casting
macAddress: { eq: "aa:bb:cc:dd:ee:ff" } # → ::macaddr casting
location: { ancestor_of: "US.CA" } # → ltree operations
dateRange: { overlaps: "[2024-01-01,2024-12-31)" }
}) {
id name ipAddress port
}
}
```
**Supported specialized types:**
- **Network**: `IPv4`, `IPv6`, `CIDR`, `MACAddress` with subnet/range operations
- **Hierarchical**: `LTree` with ancestor/descendant queries
- **Temporal**: `DateRange` with overlap/containment operations
- **Standard**: `EmailAddress`, `UUID`, `JSON` with validation
### **Intelligent Mutations**
PostgreSQL functions handle business logic with structured error handling:
```python
@fraiseql.input
class CreateUserInput:
name: str
email: EmailAddress
@fraiseql.success
class CreateUserSuccess:
user: User
message: str = "User created successfully"
@fraiseql.failure
class CreateUserError:
message: str
error_code: str
class CreateUser(
FraiseQLMutation,
function="fn_create_user", # PostgreSQL function
validation_strict=True
):
input: CreateUserInput
success: CreateUserSuccess
failure: CreateUserError
```
### **Multi-Tenant Architecture**
Built-in tenant isolation with per-tenant caching:
```python
# Automatic tenant context
@fraiseql.query
async def users(info) -> list[User]:
repo = info.context["repo"]
tenant_id = info.context["tenant_id"] # Auto-injected
return await repo.find("v_user", tenant_id=tenant_id)
```
## 📊 Performance Comparison
| Framework | Simple Query | Complex Query | Cache Hit |
|-----------|-------------|---------------|-----------|
| **FraiseQL** | **2-5ms** | **2-5ms** | **95%** |
| PostGraphile | 50-100ms | 200-400ms | N/A |
| Strawberry | 100-200ms | 300-600ms | External |
| Hasura | 25-75ms | 150-300ms | External |
*Real production benchmarks with PostgreSQL 15, 10k+ records*
## 🏗️ Architecture
FraiseQL's **storage-for-speed** philosophy trades disk space for exceptional performance:
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ GraphQL │ → │ Pre-compiled │ → │ PostgreSQL │
│ Query │ │ SHA-256 Hash │ │ Cached Result │
│ │ │ Lookup (O(1)) │ │ (JSONB) │
└─────────────────┘ └──────────────────┘ └─────────────────┘
100-300ms 1-2ms 2-5ms
Traditional FraiseQL FraiseQL + Cache
```
### **Key Innovations**
1. **TurboRouter**: Pre-compiles GraphQL queries into optimized SQL with hash-based lookup
2. **JSONB Views**: PostgreSQL returns GraphQL-ready JSON, eliminating serialization overhead
3. **Intelligent Caching**: Database-native caching with automatic invalidation on data changes
4. **Type-Aware SQL**: Automatic PostgreSQL type casting based on GraphQL field types
## 🚦 When to Choose FraiseQL
### **✅ Perfect For:**
- **High-performance APIs**: Sub-10ms response time requirements
- **Multi-tenant SaaS**: Per-tenant isolation and caching
- **PostgreSQL-first**: Teams already using PostgreSQL extensively
- **Enterprise applications**: ACID guarantees, no eventual consistency
- **Cost-sensitive projects**: 70% infrastructure cost reduction
### **❌ Consider Alternatives:**
- **Simple CRUD**: Basic applications without performance requirements
- **Non-PostgreSQL databases**: FraiseQL is PostgreSQL-specific
- **Microservices**: Better suited for monolithic or database-per-service architectures
## 🛠️ CLI Commands
```bash
# Project management
fraiseql init <name> # Create new project
fraiseql dev # Development server with hot reload
fraiseql check # Validate schema and configuration
# Code generation
fraiseql generate schema # Export GraphQL schema
fraiseql generate types # Generate TypeScript definitions
# Database utilities
fraiseql sql analyze <query> # Analyze query performance
fraiseql sql explain <query> # Show PostgreSQL execution plan
```
## 🤝 Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Development setup and testing
- Architecture decisions and patterns
- Code style and review process
## 📚 Learn More
- **[Documentation](https://fraiseql.dev)** - Complete guides and API reference
- **[Examples](./examples/)** - Real-world applications and patterns
- **[Architecture](./docs/architecture/)** - Design decisions and trade-offs
## 🙏 Acknowledgments
FraiseQL draws inspiration from:
- **[Strawberry GraphQL](https://strawberry.rocks/)** - Excellent Python GraphQL library ("Fraise" = French for strawberry)
- **Harry Percival's "Architecture Patterns with Python"** - Clean architecture and repository patterns
- **Eric Evans' "Domain-Driven Design"** - Database-centric domain modeling
- **PostgreSQL community** - For building the world's most advanced open source database
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
---
**Ready to build the fastest GraphQL API in Python?**
```bash
pip install fraiseql && fraiseql init my-fast-api
```
Raw data
{
"_id": null,
"home_page": null,
"name": "fraiseql",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "api, async, database, fastapi, graphql, jsonb, orm, postgresql",
"author": null,
"author_email": "Lionel Hamayon <lionel.hamayon@evolution-digitale.fr>",
"download_url": "https://files.pythonhosted.org/packages/09/46/98605cf3d90f7faf5ad28a74ade3cdb538e06894285e2b3b1fe2fff2116c/fraiseql-0.7.21.tar.gz",
"platform": null,
"description": "# FraiseQL\n\n[](https://github.com/fraiseql/fraiseql/actions/workflows/quality-gate.yml)\n[](https://github.com/fraiseql/fraiseql/actions/workflows/docs.yml)\n[](https://github.com/fraiseql/fraiseql/releases/latest)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n**The fastest Python GraphQL framework.** Pre-compiled queries, PostgreSQL-native caching, and sub-millisecond responses out of the box.\n\n> **4-100x faster** than traditional GraphQL frameworks \u2022 **Database-first architecture** \u2022 **Zero external dependencies**\n\n## \ud83d\ude80 Why FraiseQL?\n\n### **\u26a1 Blazing Fast Performance**\n- **Pre-compiled queries**: SHA-256 hash lookup instead of parsing (4-10x faster)\n- **PostgreSQL-native caching**: No Redis, no external dependencies\n- **Sub-millisecond responses**: 2-5ms cached, 25-60ms uncached\n- **Real production benchmarks**: 85-95% cache hit rate\n\n### **\ud83c\udfd7\ufe0f Database-First Architecture**\n- **CQRS by design**: Commands via PostgreSQL functions, queries via views\n- **JSONB-powered**: Flexible schema evolution with full type safety\n- **View-based queries**: `v_*` for real-time, `tv_*` for materialized performance\n- **PostgreSQL does the heavy lifting**: Joins, aggregations, transformations in-database\n\n### **\ud83d\udd27 Developer Experience**\n- **Type-safe**: Full Python 3.13+ type hints with automatic GraphQL schema generation\n- **One command setup**: `fraiseql init my-api && fraiseql dev`\n- **Intelligent WHERE clauses**: Automatic type-aware SQL optimization for network types, dates, and more\n- **Built-in security**: Field-level authorization, rate limiting, CSRF protection\n\n## \ud83c\udfc1 Quick Start\n\n```bash\n# Install and create project\npip install fraiseql\nfraiseql init my-api && cd my-api\n\n# Define your types\ncat > src/types.py << 'EOF'\nimport fraiseql\nfrom fraiseql import ID, EmailAddress\n\n@fraiseql.type\nclass User:\n id: ID\n email: EmailAddress\n name: str\n created_at: str\nEOF\n\n# Create database view (returns JSONB)\ncat > db/001_user_view.sql << 'EOF'\nCREATE VIEW v_user AS\nSELECT jsonb_build_object(\n 'id', pk_user,\n 'email', email,\n 'name', name,\n 'created_at', created_at::text\n) AS data FROM tb_users;\nEOF\n\n# Define queries\ncat > src/queries.py << 'EOF'\nimport fraiseql\nfrom .types import User\n\n@fraiseql.query\nasync def users(info) -> list[User]:\n repo = info.context[\"repo\"]\n return await repo.find(\"v_user\")\nEOF\n\n# Start development server\nfraiseql dev\n```\n\nYour GraphQL API is live at `http://localhost:8000/graphql` \ud83c\udf89\n\n## \ud83c\udfaf Core Features\n\n### **Advanced Type System**\nSpecialized operators for network types, hierarchical data, and ranges:\n\n```graphql\nquery {\n servers(where: {\n ipAddress: { eq: \"192.168.1.1\" } # \u2192 ::inet casting\n port: { gt: 1024 } # \u2192 ::integer casting\n macAddress: { eq: \"aa:bb:cc:dd:ee:ff\" } # \u2192 ::macaddr casting\n location: { ancestor_of: \"US.CA\" } # \u2192 ltree operations\n dateRange: { overlaps: \"[2024-01-01,2024-12-31)\" }\n }) {\n id name ipAddress port\n }\n}\n```\n\n**Supported specialized types:**\n- **Network**: `IPv4`, `IPv6`, `CIDR`, `MACAddress` with subnet/range operations\n- **Hierarchical**: `LTree` with ancestor/descendant queries\n- **Temporal**: `DateRange` with overlap/containment operations\n- **Standard**: `EmailAddress`, `UUID`, `JSON` with validation\n\n### **Intelligent Mutations**\nPostgreSQL functions handle business logic with structured error handling:\n\n```python\n@fraiseql.input\nclass CreateUserInput:\n name: str\n email: EmailAddress\n\n@fraiseql.success\nclass CreateUserSuccess:\n user: User\n message: str = \"User created successfully\"\n\n@fraiseql.failure\nclass CreateUserError:\n message: str\n error_code: str\n\nclass CreateUser(\n FraiseQLMutation,\n function=\"fn_create_user\", # PostgreSQL function\n validation_strict=True\n):\n input: CreateUserInput\n success: CreateUserSuccess\n failure: CreateUserError\n```\n\n### **Multi-Tenant Architecture**\nBuilt-in tenant isolation with per-tenant caching:\n\n```python\n# Automatic tenant context\n@fraiseql.query\nasync def users(info) -> list[User]:\n repo = info.context[\"repo\"]\n tenant_id = info.context[\"tenant_id\"] # Auto-injected\n return await repo.find(\"v_user\", tenant_id=tenant_id)\n```\n\n## \ud83d\udcca Performance Comparison\n\n| Framework | Simple Query | Complex Query | Cache Hit |\n|-----------|-------------|---------------|-----------|\n| **FraiseQL** | **2-5ms** | **2-5ms** | **95%** |\n| PostGraphile | 50-100ms | 200-400ms | N/A |\n| Strawberry | 100-200ms | 300-600ms | External |\n| Hasura | 25-75ms | 150-300ms | External |\n\n*Real production benchmarks with PostgreSQL 15, 10k+ records*\n\n## \ud83c\udfd7\ufe0f Architecture\n\nFraiseQL's **storage-for-speed** philosophy trades disk space for exceptional performance:\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 GraphQL \u2502 \u2192 \u2502 Pre-compiled \u2502 \u2192 \u2502 PostgreSQL \u2502\n\u2502 Query \u2502 \u2502 SHA-256 Hash \u2502 \u2502 Cached Result \u2502\n\u2502 \u2502 \u2502 Lookup (O(1)) \u2502 \u2502 (JSONB) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n 100-300ms 1-2ms 2-5ms\n Traditional FraiseQL FraiseQL + Cache\n```\n\n### **Key Innovations**\n1. **TurboRouter**: Pre-compiles GraphQL queries into optimized SQL with hash-based lookup\n2. **JSONB Views**: PostgreSQL returns GraphQL-ready JSON, eliminating serialization overhead\n3. **Intelligent Caching**: Database-native caching with automatic invalidation on data changes\n4. **Type-Aware SQL**: Automatic PostgreSQL type casting based on GraphQL field types\n\n## \ud83d\udea6 When to Choose FraiseQL\n\n### **\u2705 Perfect For:**\n- **High-performance APIs**: Sub-10ms response time requirements\n- **Multi-tenant SaaS**: Per-tenant isolation and caching\n- **PostgreSQL-first**: Teams already using PostgreSQL extensively\n- **Enterprise applications**: ACID guarantees, no eventual consistency\n- **Cost-sensitive projects**: 70% infrastructure cost reduction\n\n### **\u274c Consider Alternatives:**\n- **Simple CRUD**: Basic applications without performance requirements\n- **Non-PostgreSQL databases**: FraiseQL is PostgreSQL-specific\n- **Microservices**: Better suited for monolithic or database-per-service architectures\n\n## \ud83d\udee0\ufe0f CLI Commands\n\n```bash\n# Project management\nfraiseql init <name> # 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 <query> # Analyze query performance\nfraiseql sql explain <query> # Show PostgreSQL execution plan\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for:\n- Development setup and testing\n- Architecture decisions and patterns\n- Code style and review process\n\n## \ud83d\udcda Learn More\n\n- **[Documentation](https://fraiseql.dev)** - Complete guides and API reference\n- **[Examples](./examples/)** - Real-world applications and patterns\n- **[Architecture](./docs/architecture/)** - Design decisions and trade-offs\n\n## \ud83d\ude4f Acknowledgments\n\nFraiseQL draws inspiration from:\n- **[Strawberry GraphQL](https://strawberry.rocks/)** - Excellent Python GraphQL library (\"Fraise\" = French for strawberry)\n- **Harry Percival's \"Architecture Patterns with Python\"** - Clean architecture and repository patterns\n- **Eric Evans' \"Domain-Driven Design\"** - Database-centric domain modeling\n- **PostgreSQL community** - For building the world's most advanced open source database\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n**Ready to build the fastest GraphQL API in Python?**\n\n```bash\npip install fraiseql && fraiseql init my-fast-api\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Production-ready GraphQL API framework for PostgreSQL with CQRS, JSONB optimization, and type-safe mutations",
"version": "0.7.21",
"project_urls": {
"Changelog": "https://github.com/fraiseql/fraiseql/blob/main/CHANGELOG.md",
"Documentation": "https://fraiseql.readthedocs.io",
"Homepage": "https://github.com/fraiseql/fraiseql",
"Issues": "https://github.com/fraiseql/fraiseql/issues",
"Repository": "https://github.com/fraiseql/fraiseql"
},
"split_keywords": [
"api",
" async",
" database",
" fastapi",
" graphql",
" jsonb",
" orm",
" postgresql"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "032f69f73155d78ed266c0697e6ec9fe961ba8ffd624d12fce63aaf39ba9dcd9",
"md5": "6371e66bcfa89b8180a678d06e1d22ab",
"sha256": "b9ab592b71ec6938db2ccc7c9a80e48bb7e541539d324b9c39b138771d8c1788"
},
"downloads": -1,
"filename": "fraiseql-0.7.21-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6371e66bcfa89b8180a678d06e1d22ab",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 431558,
"upload_time": "2025-09-14T18:04:17",
"upload_time_iso_8601": "2025-09-14T18:04:17.739358Z",
"url": "https://files.pythonhosted.org/packages/03/2f/69f73155d78ed266c0697e6ec9fe961ba8ffd624d12fce63aaf39ba9dcd9/fraiseql-0.7.21-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "094698605cf3d90f7faf5ad28a74ade3cdb538e06894285e2b3b1fe2fff2116c",
"md5": "d79aa41f8944f543f258a8ffec9030c0",
"sha256": "69de04ea9ab6e71a8080519a3766f19abb60494f645ec0a4b2a1c39726000400"
},
"downloads": -1,
"filename": "fraiseql-0.7.21.tar.gz",
"has_sig": false,
"md5_digest": "d79aa41f8944f543f258a8ffec9030c0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 324579,
"upload_time": "2025-09-14T18:04:19",
"upload_time_iso_8601": "2025-09-14T18:04:19.926405Z",
"url": "https://files.pythonhosted.org/packages/09/46/98605cf3d90f7faf5ad28a74ade3cdb538e06894285e2b3b1fe2fff2116c/fraiseql-0.7.21.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 18:04:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fraiseql",
"github_project": "fraiseql",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fraiseql"
}
