{"id":4030,"library":"graphene-django","title":"Graphene Django Integration","description":"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.","status":"active","version":"3.2.3","language":"en","source_language":"en","source_url":"https://github.com/graphql-python/graphene-django","tags":["graphql","django","orm","api"],"install":[{"cmd":"pip install graphene-django","lang":"bash","label":"Install Graphene Django"},{"cmd":"pip install graphene-django django-filter","lang":"bash","label":"Install with Django Filter for advanced filtering"}],"dependencies":[{"reason":"Core GraphQL framework dependency.","package":"graphene"},{"reason":"Required for integration with Django projects.","package":"Django"},{"reason":"Optional, required for DjangoFilterConnectionField to enable filtering on connections.","package":"django-filter","optional":true}],"imports":[{"note":"Old import path from Graphene 2.x and earlier versions.","wrong":"from graphene.contrib.django.types import DjangoObjectType","symbol":"DjangoObjectType","correct":"from graphene_django.types import DjangoObjectType"},{"symbol":"DjangoConnectionField","correct":"from graphene_django.fields import DjangoConnectionField"},{"note":"Requires 'django-filter' package to be installed for this to work.","symbol":"DjangoFilterConnectionField","correct":"from graphene_django.fields import DjangoFilterConnectionField"},{"symbol":"GraphQLView","correct":"from graphene_django.views import GraphQLView"},{"note":"In Graphene Django v3+, use the `graphene_django.types.Node` for Relay integration, not `graphene.relay.Node`.","wrong":"from graphene.relay import Node","symbol":"Node","correct":"from graphene_django.types import Node"},{"symbol":"graphene.Schema","correct":"import graphene\nschema = graphene.Schema(...)"}],"quickstart":{"code":"import graphene\nfrom graphene_django.types import DjangoObjectType\nfrom graphene_django.fields import DjangoConnectionField\nfrom django.db import models\n\n# 1. Define a Django Model (e.g., in myapp/models.py)\nclass Category(models.Model):\n    name = models.CharField(max_length=100)\n\n    class Meta:\n        # Essential for Relay Connection in Django 5+ to ensure consistent ordering\n        ordering = ['name'] \n\n    def __str__(self):\n        return self.name\n\n# 2. Define a Graphene DjangoObjectType (e.g., in myapp/schema.py)\nclass CategoryType(DjangoObjectType):\n    class Meta:\n        model = Category\n        # Explicitly list fields for clarity/control, or use '__all__'\n        fields = ('id', 'name') \n\n# 3. Define a Query (e.g., in myapp/schema.py)\nclass Query(graphene.ObjectType):\n    all_categories = DjangoConnectionField(CategoryType)\n\n    # Optionally, resolve a single category by ID\n    category = graphene.Field(CategoryType, id=graphene.ID())\n\n    def resolve_category(root, info, id):\n        try:\n            return Category.objects.get(pk=id)\n        except Category.DoesNotExist:\n            return None\n\n# 4. Create the Graphene Schema (e.g., in myapp/schema.py)\nschema = graphene.Schema(query=Query)\n\n# 5. Integrate into Django URLs (e.g., in project/urls.py)\n# from django.urls import path\n# from graphene_django.views import GraphQLView\n# from myapp.schema import schema # Assuming myapp/schema.py\n# urlpatterns = [\n#     path('graphql/', GraphQLView.as_view(graphiql=True, schema=schema)),\n# ]\n\n# Remember to add 'graphene_django' to INSTALLED_APPS in your Django settings.py","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Add `class Meta: ordering = ['your_field']` to your Django model or `DjangoObjectType` to specify a default order for connections.","message":"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.","severity":"gotcha","affected_versions":">=3.2.1, Django >= 5.0"},{"fix":"Run `pip install django-filter` and add `'django_filters'` to your `INSTALLED_APPS` in `settings.py` to enable filtering capabilities with `DjangoFilterConnectionField`.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}