GraphQL with Django

A GraphQL endpoint is one ordinary Django URL. The request goes through the whole middleware stack first, so sessions, authentication and CSRF protection have already run when the GraphQL view sees it; the view then parses the document, validates it against the schema and executes it, calling one resolver per selected field. Strawberry-Django’s resolvers turn the root fields into QuerySets and the nested fields into attribute access on model instances — which is exactly where an unoptimized schema issues one SQL query per object.

Two consequences follow. First, everything Django already gives a view — request.user, the session, the CSRF check, middleware such as LoginRequiredMiddleware — applies to the GraphQL view as well, and nothing needs to be reinvented in resolvers. Second, a GraphQL response is normally HTTP 200 even when a field failed: errors are reported in the errors key or, with Strawberry-Django’s error handling, as typed payloads (see Mutations). Monitoring that only looks at status codes will miss them.

Source: Strawberry: Django integration and Django middleware

Three Python projects can serve GraphQL from Django. They all run on graphql-core, so the wire format and the GraphiQL experience are the same; they differ in how you declare the schema and how much of the ORM they understand.

The rest of this page uses Strawberry-Django: it is the integration that Strawberry’s own documentation recommends for models, it declares support for Django 5.2 and 6.0 (6.0 since 0.68.0, 2025-12-03), and its optimizer solves the N+1 problem without hand-written prefetching. Graphene-Django in brief shows the same API in Graphene-Django for teams maintaining one.

Source: Strawberry-Django documentation, strawberry-graphql-django on PyPI and graphene-django on PyPI

Install the package into the project’s virtual environment; it pulls in strawberry-graphql and graphql-core.

Add strawberry_django to INSTALLED_APPS — it provides the GraphiQL template and the export_schema management command — and, optionally, tune the integration with the STRAWBERRY_DJANGO setting:

The two description switches are off by default because existing models often have docstrings written for developers, not API consumers; turn them on only if your help_text and docstrings are fit to publish. Both pagination keys default to 100. Other keys set the default argument name of the CRUD mutations (MUTATIONS_DEFAULT_ARGUMENT_NAME, "data"), whether mutations handle Django errors by default (MUTATIONS_DEFAULT_HANDLE_ERRORS, False) and the name of the primary-key argument of single-object fields (DEFAULT_PK_FIELD_NAME, "pk").

Source: Strawberry-Django: Quick Start and Strawberry-Django: Settings

The examples use three models in a catalog app: an author writes many books, and a reader (the user model) reviews a book with a rating from 1 to 5, enforced by a check constraint.

Source: Models and CheckConstraint

@strawberry_django.type(Model) turns a class into a GraphQL object type backed by that model. Fields annotated with strawberry.auto take their GraphQL type from the model field (CharField becomes String!, DateField becomes Date!, a nullable column becomes a nullable type), and relations are annotated with the related GraphQL type: a ForeignKey with the type itself, a reverse foreign key or many-to-many with a list[…​]. Only the attributes you declare are exposed — there is no "all fields" switch, which keeps a new password_hash column from leaking into the API by accident.

BookFilter and BookOrder are defined just above these types (see Queries: lists, single objects, filters, ordering and pagination). The reader foreign key is deliberately left out of ReviewType: a public API has no business listing which user wrote what. The export_schema command prints the SDL that these classes produce, which is worth committing and diffing in code review:

The descriptions come from the model docstring and help_text because of the two settings above, and AuthorType.books gained filters, ordering and pagination arguments because BookType declares them: a nested list is filterable exactly like a root list. The model docstring is also copied onto input types built from the same model (BookFilter is described as "A book in the shelf."), one more reason to keep docstrings user-facing when the switch is on.

strawberry_django.input(Model) and strawberry_django.partial(Model) build input types the same way: input keeps the model’s required fields required, partial makes every auto field optional, which is what an update needs.

Source: Strawberry-Django: Defining types, Strawberry-Django: Fields and Strawberry-Django: Export schema

On the root Query type, strawberry_django.field() does the resolving for you: a list[BookType] field returns Book.objects.all() (as a lazy QuerySet that the filters, ordering, pagination and optimizer then refine), and a single BookType field gains a required pk: ID! argument and returns one row.

A filter type is declared with @strawberry_django.filter_type(Model); with lookups=True every field gets an input of Django lookups (exact, iContains, gte, inList, isNull …​), and a relation can nest the related model’s filter. Each filter input also gets AND, OR, NOT and DISTINCT fields. An ordering type is declared with @strawberry_django.order_type(Model); clients pass a list of one-field objects, so the order of the criteria is preserved. pagination=True adds an OffsetPaginationInput (offset, limit) argument, capped by PAGINATION_MAX_LIMIT.

All three become ORM calls — filter(publishedgte=…​, authorname__icontains=…​), order_by("-published") and a slice — so the database does the work, not Python:

The cookie jar and $CSRF come from the GraphiQL page, see CSRF with GraphQL. A single-object field with a non-existent primary key raises Book.DoesNotExist, which surfaces as "errors": [{"message": "Book matching query does not exist.", …​}] with "data": null, because the field is non-null.

Filters only narrow what the type’s QuerySet already allows. To hide rows from everybody (unpublished books, other users' drafts), override the get_queryset class method on the type: it receives the default QuerySet and info (and so the current user) and returns a narrower QuerySet. Guarding against regressions with FETCH_RAISE (Django 6.1) shows one.

Source: Strawberry-Django: Queries, Strawberry-Django: Filtering, Strawberry-Django: Ordering and Strawberry-Django: Pagination

Strawberry-Django offers two ways to write a mutation. For plain create/update/delete of one model, the generated mutations.create, mutations.update and mutations.delete take an input type and do the save() (running full_clean() first) for you. For anything with business logic, decorate a method with @strawberry_django.mutation, which differs from Strawberry’s own @strawberry.mutation in three ways: a synchronous resolver is wrapped in sync_to_async when the schema runs under ASGI, so ORM calls are safe; it integrates with the permission extensions; and with handle_django_errors=True it catches ValidationError, PermissionDenied and ObjectDoesNotExist and returns them as data instead of a top-level error.

With handle_django_errors=True the return type becomes a union of the declared type and OperationInfo, so the exported schema reads addReview(bookId: ID!, rating: Int!, body: String! = ""): AddReviewPayload! with union AddReviewPayload = ReviewType | OperationInfo. Clients select both members with inline fragments. The reader is taken from the session (get_current_user(info) returns info.context.request.user), never from an argument, so a client cannot post a review in somebody else’s name. full_clean() runs the model’s validators and, since Django 4.1, its constraints, so the check constraint above comes back as a VALIDATION message instead of an IntegrityError:

A field-level validation error (a ValidationError keyed by field name) fills field; give the constraint a violation_error_message (and violation_error_code) if clients should show something friendlier. The generated CRUD mutations take their input in an argument called data (createAuthor(data: {name: "…​"})); mutations.update looks the row up by the primary key in the partial input (id here), or by another unique field passed as key_attr. Never expose a generated mutation without a permission extension: it can write every field that the input type declares.

GraphQL mutations must not be sent with GET; Strawberry’s views refuse them (mutations are not allowed when using GET, HTTP 400), so the usual "state changes need POST and CSRF" rule holds without extra code.

Source: Strawberry-Django: Mutations, Strawberry: Mutations and Validating objects

Authorization belongs to the server, not to the client’s choice of fields; the theory is in Authorization. Strawberry-Django maps it onto Django’s own permission system with field extensions from strawberry_django.permissions:

When a check fails, the extension does not simply raise. If the field can return OperationInfo (a mutation with handle_django_errors=True), it returns a PERMISSION message; otherwise an optional field resolves to null, a list to [] and a connection to an empty connection; only a non-null single value raises a PermissionDenied error. Pass fail_silently=False to raise instead of returning an empty value, and message="…​" to change the text. The exported schema documents the checks as directives (@isAuthenticated, @hasPerm(…​)), so clients can see them. For example, an authenticated reader without catalog.add_author gets:

The same extensions work on query fields, e.g. drafts: list[BookType] = strawberry_django.field(extensions=[IsStaff()]). Who the user is comes from Django’s AuthenticationMiddleware; for login and logout over GraphQL, strawberry_django.auth.login(), logout() and current_user() provide ready-made fields that call django.contrib.auth.login/logout and therefore rotate the session key and need the CSRF token like any other POST. Token-based clients (mobile apps, other services) typically authenticate in middleware instead and never touch the session; see Authentication and Permissions & Authorization for the Django side.

Source: Strawberry-Django: Permissions, Strawberry-Django: Authentication and Django: Permissions and Authorization

The schema object ties the root types and the schema extensions together; the view serves it on a URL.

strawberry.django.views has two views. AsyncGraphQLView is an async Django view: under ASGI (Uvicorn, Daphne, Granian, Hypercorn) it runs on the event loop, supports async resolvers and is the only one that can use DataLoaders. GraphQLView is synchronous for WSGI deployments. Both accept the same main options:

Source: Strawberry-Django: Serving the API

Why nested resolvers multiply queries, and the general batch-and-cache cure, are explained in Performance & the N+1 problem; the Django side of the same problem (lazy relations, select_related, prefetch_related) is in Query Optimization & Fetch Modes. In a Django schema the two meet: each nested field is resolved by attribute access on a model instance, so book.author and book.reviews.all() each run a query per book unless the root QuerySet loaded them in advance. Here is the query { books { title author { name } reviews { rating } } } against two books, run once on a schema built without the optimizer and once on the real one:

Without the optimizer the count is 1 + 2N (21 queries for ten books, 201 for a hundred); with it, it is two, whatever the number of books, and every query selects only the requested columns.

Source: Strawberry-Django: Query Optimizer and assertNumQueries()

Strawberry-Django is written so that the same schema runs under both views. Its own resolvers (strawberry_django.field(), the CRUD mutations, @strawberry_django.mutation) detect an async context and run ORM work through sync_to_async, so a plain def resolver that touches the ORM is safe under AsyncGraphQLView. Plain @strawberry.field resolvers get no such wrapping: under the async view, a synchronous ORM call there raises SynchronousOnlyOperation, so either make the resolver async def and use the async ORM (aget, acount, async for), or use @strawberry_django.field instead. Since 0.92.0 (2026-10-01), list fields hand graphql-core an unevaluated QuerySet that it iterates with async for in async execution.

Choosing between them follows the deployment, not the schema: run AsyncGraphQLView under an ASGI server if you want DataLoaders, async resolvers or subscriptions (which additionally need Channels, see Channels & WebSockets); run GraphQLView under WSGI otherwise. Django’s async story in general — what is truly async in the ORM and what still runs in a thread — is on Async Support.

Source: Strawberry: Django integration, strawberry-django 0.92.0 release notes and Asynchronous support

Graphene-Django predates Strawberry and still runs many production schemas. Types subclass DjangoObjectType and name their model and exposed fields in an inner Meta; resolvers are resolve_<field> methods; the view is a synchronous GraphQLView that takes the schema from the GRAPHENE setting. Its 3.2.3 release (2025-03-13) is the latest on 2026-10-03 and its classifiers stop at Django 4.2; it installed and passed its test under Django 6.1.1 here, in a separate virtual environment, because Graphene 3.4.3 requires graphql-core below 3.3 while current Strawberry requires 3.3.

Always set fields (or exclude): without either, DjangoObjectType exposes every model field and warns that this is deprecated. Graphene-Django has no query optimizer, so the select_related("author") above is mandatory — and it is also wrong for a query that does not select author, which is the trade-off the optimizer removes. As with Strawberry, the view is not CSRF-exempt; set graphiql from DEBUG in production.

The Graphene test case posts to GRAPHQL_URL and offers assertResponseNoErrors:

When migrating a Graphene schema to Strawberry-Django, export both schemas as SDL and diff them so that clients see no change. The GraphQL section’s Python: Getting Started page puts Graphene in the wider Python landscape.

Source: Graphene-Django: Installation, Graphene-Django: Queries & ObjectTypes, Graphene-Django: Mutations and Graphene-Django: Testing tools

Strawberry-Django ships two test clients built on Django’s: strawberry_django.test.client.TestClient (wrapping django.test.Client) and AsyncTestClient (wrapping AsyncClient). They take the endpoint path, post the document and variables as JSON, assert by default that the response has no errors (assert_no_errors=False turns that off for negative tests), return a Response with data, errors and extensions, and offer a login(user) context manager that logs a user into the client’s session. Because they go through the URL, the middleware and the view, they test the real wiring — including permissions and the custom context. Django’s test client does not enforce CSRF checks unless created with enforce_csrf_checks=True, so CSRF behaviour is better checked with curl as in CSRF with GraphQL.

The most valuable GraphQL test is a query-count test: assertNumQueries around a list query with several rows fails as soon as a schema change brings back N+1.

A few details are worth copying. setUpTestData creates the rows once per class; five books make the difference between 2 and 1 + 5 + 5 queries unmistakable. The DataLoader test uses the synchronous client on purpose: the async view runs through async_to_sync, and assertNumQueries itself cannot be entered inside an async def test (it raises SynchronousOnlyOperation), so query counting stays in synchronous tests while AsyncTestClient covers the async path. The permission test grants catalog.add_author between two requests inside the same login() block; each request loads the user afresh, so the second request sees the new permission. For pure schema logic without HTTP, schema.execute_sync() (or await schema.execute()) runs a document directly, as the optimizer tests do. With pytest, the same clients work in tests that request pytest-django’s db fixture.

Source: Strawberry-Django: Unit Testing, Strawberry: Testing and Django: Testing tools

A query nested deeper than six levels is rejected before execution with "'anonymous' exceeds maximum operation depth of 6". Pass extensions as classes or factories: since Strawberry 0.316.0 (2026-05-19) passing an instance such as QueryDepthLimiter(max_depth=6) directly is deprecated, because the one object would be shared by concurrent requests (the extension’s own documentation page still shows the instance form).

Source: Strawberry: QueryDepthLimiter and Strawberry-Django: Pagination (PAGINATION_MAX_LIMIT)

None of the four books consulted for this section (see the section bibliography) teaches GraphQL: they target Django 1.11 to 2.1, and _Practical Django 2 and Channels 2 mentions GraphQL only in passing, as the newer alternative to REST that single-page applications consume. What they do teach that carries over is the ORM side — lazy relations, select_related() and prefetch_related() — and that advice is still correct; in a GraphQL schema the optimizer applies it per request from the selection set instead of you writing it per view. Material from the same years on GraphQL with Django is outdated in specific ways:

The Strawberry-Django rows come from its GitHub release notes, the Strawberry row from its changelog and the Django rows from the release notes.