graphene-django/README.md

Graphene-Django

A Django integration for Graphene.

💬 Join the community on Slack

Documentation

Visit the documentation to get started!

Quickstart

For installing graphene, just run this command in your shell

pip install "graphene-django>=2.0"

Settings

INSTALLED_APPS = (
    # ...
    'django.contrib.staticfiles', # Required for GraphiQL
    'graphene_django',
)

GRAPHENE = {
    'SCHEMA': 'app.schema.schema' # Where your Graphene schema lives
}

Urls

We need to set up a GraphQL endpoint in our Django app, so we can serve the queries.

from django.urls import path
from graphene_django.views import GraphQLView

urlpatterns = [
    # ...
    path('graphql', GraphQLView.as_view(graphiql=True)),
]

Subscription Support

The graphene-django project does not currently support GraphQL subscriptions out of the box. However, there are several community-driven modules for adding subscription support, and the GraphiQL interface provided by graphene-django supports subscriptions over websockets.

To implement websocket-based support for GraphQL subscriptions, you'll need to:

1. Install and configure django-channels.
2. Install and configure^{1, 2} a third-party module for adding subscription support over websockets. A few options include:
   • graphql-python/graphql-ws
   • datavance/django-channels-graphql-ws
   • jaydenwindle/graphene-subscriptions
3. Ensure that your application (or at least your GraphQL endpoint) is being served via an ASGI protocol server like daphne (built in to django-channels), uvicorn, or hypercorn.

¹ Note: By default, the GraphiQL interface that comes with graphene-django assumes that you are handling subscriptions at the same path as any other operation (i.e., you configured both urls.py and routing.py to handle GraphQL operations at the same path, like /graphql).

If these URLs differ, GraphiQL will try to run your subscription over HTTP, which will produce an error. If you need to use a different URL for handling websocket connections, you can configure SUBSCRIPTION_PATH in your settings.py:

GRAPHENE = {
    # ...
    "SUBSCRIPTION_PATH": "/ws/graphql"  # The path you configured in `routing.py`, including a leading slash.
}

Once your application is properly configured to handle subscriptions, you can use the GraphiQL interface to test subscriptions like any other operation.

Examples

Here is a simple Django model:

from django.db import models

class UserModel(models.Model):
    name = models.CharField(max_length=100)
    last_name = models.CharField(max_length=100)

To create a GraphQL schema for it you simply have to write the following:

from graphene_django import DjangoObjectType
import graphene

class User(DjangoObjectType):
    class Meta:
        model = UserModel

class Query(graphene.ObjectType):
    users = graphene.List(User)

    def resolve_users(self, info):
        return UserModel.objects.all()

schema = graphene.Schema(query=Query)

Then you can query the schema:

query = '''
    query {
      users {
        name,
        lastName
      }
    }
'''
result = schema.execute(query)

To learn more check out the following examples:

• Schema with Filtering: Cookbook example
• Relay Schema: Starwars Relay example

Contributing

See CONTRIBUTING.md

Release Notes

• See Releases page on github