Graphene Django Integration

3.2.3 · active · verified Sat Apr 11

Graphene Django provides an integration layer to build powerful GraphQL APIs on top of Django models and applications. It allows automatically mapping Django models to GraphQL types, handling connections, mutations, and more. Current version is 3.2.3, with new releases occurring frequently, often monthly or bi-monthly, supporting recent Django and Graphene versions.

Warnings

breaking Graphene Django v3 introduced significant breaking changes from v2. Key changes include moving `Node` to `graphene_django.types.Node` and changes in how `DjangoFilterConnectionField` defaults are handled. Ensure your code is updated to use v3 import paths and configurations.
Fix: Review the official Graphene Django v3 upgrade guide for a comprehensive list of changes. Update import paths (e.g., `from graphene_django.types import Node`) and adapt custom filters/resolvers.
gotcha When using `DjangoConnectionField` for Relay connections, the underlying Django model's `Meta` options (e.g., `ordering` or `get_latest_by`) or the `DjangoObjectType`'s `Meta.order_by` must explicitly define a default ordering. Failing to do so can result in errors, especially with newer Django versions (5.x and above) where this check became more strict.
Fix: Add `class Meta: ordering = ['your_field']` to your Django model or `DjangoObjectType` to specify a default order for connections.
gotcha To use `DjangoFilterConnectionField` for filtering connections, you must explicitly install the `django-filter` package in addition to `graphene-django`. This is not an automatic dependency.
Fix: Run `pip install django-filter` and add `'django_filters'` to your `INSTALLED_APPS` in `settings.py` to enable filtering capabilities with `DjangoFilterConnectionField`.
gotcha Handling Django model `choices` fields as Graphene `Enum` types can be complex, particularly when dealing with different Django versions or specific ORM behaviors. The automatic conversion might not always align with expectations, and custom handling might be required.
Fix: Review the `Graphene-Django` documentation on `choices` fields. For specific issues, consider defining your `Enum` explicitly in Graphene and mapping it manually, or utilizing the `GRAPHENE_DJANGO` setting `convert_choices_to_enums` for global control.

Install

pip install graphene-django Install Graphene Django
pip install graphene-django django-filter Install with Django Filter for advanced filtering

Imports

DjangoObjectType
```
from graphene_django.types import DjangoObjectType
```
Old import path from Graphene 2.x and earlier versions.

DjangoConnectionField

from graphene_django.fields import DjangoConnectionField

DjangoFilterConnectionField
```
from graphene_django.fields import DjangoFilterConnectionField
```
Requires 'django-filter' package to be installed for this to work.

GraphQLView

from graphene_django.views import GraphQLView

Node
```
from graphene_django.types import Node
```
In Graphene Django v3+, use the `graphene_django.types.Node` for Relay integration, not `graphene.relay.Node`.

graphene.Schema

import graphene
schema = graphene.Schema(...)

Quickstart

This example shows how to expose a Django model through a GraphQL API using `graphene-django`. It defines a simple `Category` model, creates a `DjangoObjectType` for it, and exposes `all_categories` via a `DjangoConnectionField` for Relay-compliant pagination. It also demonstrates how to fetch a single category by ID. Remember to configure your Django `urls.py` with `GraphQLView` and add `graphene_django` to your `INSTALLED_APPS`.

import graphene
from graphene_django.types import DjangoObjectType
from graphene_django.fields import DjangoConnectionField
from django.db import models

# 1. Define a Django Model (e.g., in myapp/models.py)
class Category(models.Model):
    name = models.CharField(max_length=100)

    class Meta:
        # Essential for Relay Connection in Django 5+ to ensure consistent ordering
        ordering = ['name'] 

    def __str__(self):
        return self.name

# 2. Define a Graphene DjangoObjectType (e.g., in myapp/schema.py)
class CategoryType(DjangoObjectType):
    class Meta:
        model = Category
        # Explicitly list fields for clarity/control, or use '__all__'
        fields = ('id', 'name') 

# 3. Define a Query (e.g., in myapp/schema.py)
class Query(graphene.ObjectType):
    all_categories = DjangoConnectionField(CategoryType)

    # Optionally, resolve a single category by ID
    category = graphene.Field(CategoryType, id=graphene.ID())

    def resolve_category(root, info, id):
        try:
            return Category.objects.get(pk=id)
        except Category.DoesNotExist:
            return None

# 4. Create the Graphene Schema (e.g., in myapp/schema.py)
schema = graphene.Schema(query=Query)

# 5. Integrate into Django URLs (e.g., in project/urls.py)
# from django.urls import path
# from graphene_django.views import GraphQLView
# from myapp.schema import schema # Assuming myapp/schema.py
# urlpatterns = [
#     path('graphql/', GraphQLView.as_view(graphiql=True, schema=schema)),
# ]

# Remember to add 'graphene_django' to INSTALLED_APPS in your Django settings.py

view raw JSON →