Strawberry GraphQL Django Integration

0.82.1 · active · verified Sat Apr 11

Strawberry GraphQL Django integration provides powerful tools to build GraphQL APIs with Django. It automatically generates GraphQL types, queries, mutations, and resolvers from your Django models with full type safety. The library is actively maintained, currently at version 0.82.1, and supports Django 4.2-6.0 and Python 3.10-3.14, with regular updates.

Warnings

breaking Django's CSRF protection is now enabled by default for Strawberry Django views (since v0.243.0). Previously, views were implicitly exempted.
Fix: Clients now need to send CSRF tokens. To restore previous behavior, explicitly wrap your `GraphQLView.as_view()` with Django's `@csrf_exempt` decorator: `path("graphql/", csrf_exempt(GraphQLView.as_view(schema=schema)))`.
breaking Multipart file uploads are disabled by default (since v0.243.0) due to security implications.
Fix: To enable, set `multipart_uploads_enabled=True` when configuring your `GraphQLView.as_view()` and implement appropriate security measures.
deprecated The `strawberry-django-plus` library is deprecated. All its additional features have been merged into the official `strawberry-graphql-django` library.
Fix: Migrate your `strawberry-django-plus` implementation to `strawberry-graphql-django` to ensure continued support and development. Consult the `strawberry-django-plus` migration guide.
gotcha Directly accessing Django ORM from asynchronous resolvers within `AsyncGraphQLView` will raise `django.core.exceptions.SynchronousOnlyOperation`.
Fix: Wrap synchronous Django ORM calls within `sync_to_async` (from `asgiref.sync`) when inside an async resolver.
breaking For Relay integration, the generated GraphQL type for the `id` field changed from `GlobalID` to `ID` (since v0.268.0). The Python runtime behavior for `relay.GlobalID` remains unchanged.
Fix: Update frontend clients expecting `GlobalID`. If you need to revert to the `GlobalID` schema type, pass `config=StrawberryConfig(relay_use_legacy_global_id=True)` to `strawberry.Schema`.
gotcha Type checkers (e.g., MyPy, PyLance) might show errors when using `strawberry.auto` and returning a Django model instance where a GraphQL type is expected.
Fix: Use `typing.cast` to explicitly tell the type checker that the Django model instance is compatible with the expected GraphQL type, e.g., `return cast(GraphQLType, django_model_instance)`.
gotcha When using `django-polymorphic`, ensure every model subclass has a corresponding GraphQL type, or filter unwanted subtypes in `get_queryset` to avoid 'Abstract type ... must resolve to an Object type at runtime' errors.
Fix: Define GraphQL types for all relevant polymorphic model subclasses or implement a `get_queryset` method on your GraphQL interface type to filter results appropriately.

Install

pip install strawberry-graphql-django Install core library
pip install strawberry-graphql-django[polymorphic] Install with polymorphic support (optional)

Imports

@strawberry_django.type
```
import strawberry_django
@strawberry_django.type(...)
```
Use strawberry_django.type for Django model integration, not base strawberry.type.
strawberry_django.field
```
from strawberry_django import field
```
Use strawberry_django.field for Django model fields to leverage its features like N+1 query optimization.
AsyncGraphQLView
```
from strawberry.django.views import AsyncGraphQLView
```
Use AsyncGraphQLView for async Django views; GraphQLView is also available for sync.
DjangoOptimizerExtension
```
from strawberry_django.optimizer import DjangoOptimizerExtension
```
This extension is crucial for N+1 query problem prevention and query optimization.

Quickstart

This quickstart demonstrates how to define Django models, create corresponding Strawberry GraphQL types using `strawberry_django.type` and `auto`, and then expose them via a GraphQL `Query` field. It also shows the integration of `DjangoOptimizerExtension` for performance and how to set up the Django URLconf to serve the GraphQL API. The example defines simple Fruit and Color models with a foreign key relationship.

import strawberry
import strawberry_django
from django.db import models
from strawberry.django.views import AsyncGraphQLView
from strawberry_django.optimizer import DjangoOptimizerExtension

# models.py (excerpt)
class Color(models.Model):
    name = models.CharField(max_length=20)

    def __str__(self):
        return self.name

class Fruit(models.Model):
    name = models.CharField(max_length=20)
    color = models.ForeignKey(Color, on_delete=models.CASCADE, related_name="fruits")

    def __str__(self):
        return self.name

# types.py (excerpt, often in app.types.py)
@strawberry_django.type(Color)
class ColorType:
    id: strawberry.ID
    name: str
    fruits: list['FruitType'] # Forward reference

@strawberry_django.type(Fruit)
class FruitType:
    id: strawberry.ID
    name: str
    color: ColorType

# schema.py (excerpt, often in project.schema.py)
@strawberry.type
class Query:
    @strawberry_django.field
    def fruits(self) -> list[FruitType]:
        return Fruit.objects.all()

    @strawberry_django.field
    def colors(self) -> list[ColorType]:
        return Color.objects.all()

schema = strawberry.Schema(
    query=Query,
    extensions=[
        DjangoOptimizerExtension, # Recommended for N+1 query optimization
    ]
)

# urls.py (excerpt)
# from django.urls import path
# from myproject.schema import schema # Assuming schema defined in myproject/schema.py
# from strawberry.django.views import AsyncGraphQLView
#
# urlpatterns = [
#     path("graphql/", AsyncGraphQLView.as_view(schema=schema)),
# ]

# To run this example, you'd typically set up a Django project:
# 1. Create a Django project and app.
# 2. Add 'strawberry.django' and your app to INSTALLED_APPS in settings.py.
# 3. Define models (Color, Fruit) in your app's models.py.
# 4. Define types (ColorType, FruitType) in your app's types.py.
# 5. Define Query and Schema in your project's schema.py.
# 6. Add the GraphQL endpoint to your project's urls.py.

view raw JSON →