Playground Project¶

The repository ships a small, fully runnable Django project at examples/playground/ that exercises every major django-graphex feature end-to-end: queries with all three paginators, filtering (including a custom @filter_field), N+1-safe nested lists, the full query-optimization surface, a typed GenericForeignKey union, directives, CRUD mutations with permissions, descriptor-API hand-written mutations, file uploads on both paths (base64 in the JSON body and a multipart part), the projection security boundary on all three axes, the relation scoping hatch in both directions, query depth/cost limits, and native subscriptions over WebSocket and SSE.

Quick start¶

You need uv and Python 3.12+.

git clone https://github.com/eamigo86/django-graphex.git
cd django-graphex/examples/playground

make install     # uv sync — installs the local library (editable) + daphne
make migrate     # generate + apply migrations (SQLite)
make seed        # load demo data (see below)
make run         # daphne ASGI server (HTTP + WebSocket) on 127.0.0.1:8000

Open GraphiQL at http://127.0.0.1:8000/graphql/. The seed creates the superuser demo / demo12345.

All the Makefile targets:

Resetting the playground¶

make reset is the recovery path when generated migrations no longer match the local SQLite database. It deletes db.sqlite3 and only migration files matching blog/migrations/0*.py, preserves blog/migrations/__init__.py, removes migration bytecode, then regenerates, migrates and seeds.

make reset
make test  # pytest runs with --no-migrations

The --no-migrations test option is deliberate: playground tests exercise the current models and must not depend on whatever generated migration happened to exist in a developer checkout.

WebSocket origin policy¶

The shipped ALLOWED_HOSTS is exactly 127.0.0.1, localhost and testserver. AllowedHostsOriginValidator applies that list to WebSocket handshakes, so a browser origin such as evil.example is rejected while the documented localhost and Django test-client origins connect.

If you expose the playground through another development hostname, add that exact host. Do not replace the list with "*": the socket uses session cookies, so an allow-all Origin policy would enable cross-site WebSocket requests.

What the seed creates¶

python manage.py seed (idempotent — it clears the demo tables first) loads:

• 15 authors x 12 posts each (180 posts), statuses cycling DRAFT / PUBLISHED / ARCHIVED, each post in one of the categories Tech / Life / News and tagged with one of django / graphql / python. Each body names its own tag ("Body of post 9 by author 13. Topic: django.") so the custom @filter_field has something to find — posts(filter: { search: "django" }) answers totalCount: 20 rather than an empty page that reads like a broken example
• 3 comments per post (540 comments)
• 12 private notes owned by the demo user
• 2 accounts + 2 invoices + 4 attachments — the attachments alternate between Account and Invoice targets so the typed GenericForeignKey union query returns both member types
• The superuser demo / demo12345 (also linked to the first author)

The counts are deliberate: 12 posts per author is more than the page size of 10, so nested posts lists span real multiple pages and the DB-side window-pagination path (ROW_NUMBER() OVER (PARTITION BY ...)) is genuinely exercised — try results(offset: 10) on a nested list. Scale the dataset without editing code:

uv run python manage.py seed --authors 25 --posts 15   # explicit counts
uv run python manage.py seed --scale 2                 # doubles authors + posts

Endpoints¶

Authenticating (private fields)¶

Auth is Django session-based. Private fields (me, myNotes, the note mutations, noteSubscription) require a logged-in user:

1. Open http://127.0.0.1:8000/admin/ and log in as demo / demo12345.
2. Return to GraphiQL — it shares the session cookie.

Log out of /admin to test the anonymous (public) behaviour again.

Schema tour¶

Everything lives in blog/schema.py (with settings in config/settings.py). What each part demonstrates:

Starter queries¶

Paste these into GraphiQL at /graphql/ right after make seed — they all work anonymously.

{
  posts(filter: { status: { exact: PUBLISHED } }) {
    totalCount
    results(limit: 5, ordering: "-id") {
      id
      title
      status
      author { name }
      tags { totalCount results { name } }
      comments {
        totalCount
        results(first: 2) { authorName text }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
  authors {
    totalCount
    results(page: 1) { name }
  }
  comments {
    totalCount
    results(first: 3) { text }
    pageInfo { hasNextPage endCursor }
  }
}

{
  posts(filter: { search: "author 3" }) {
    totalCount
    results(limit: 5) { id title }
  }
  authors {
    results(page: 1) {
      name
      postCount
      posts(filter: { title: { icontains: "Post 1" } }) {
        totalCount
        results(limit: 3, ordering: "-id") {
          title
          status
          category { name }
        }
      }
    }
  }
}

{
  attachments {
    totalCount
    results {
      caption
      target {
        __typename
        ... on AccountType { label balance }
        ... on InvoiceType { number amount }
      }
    }
  }
}

{
  posts {
    results(limit: 3) {
      title @uppercase
      slug: title @slugify
      teaser: body @truncate(length: 40)
    }
  }
}

The projection boundary, live¶

AuthorType projects bio away. The rule says a hidden column is not readable, not orderable and not filterable (the canonical statement) — here are all three axes, anonymously, with the answers the playground returns. It sets ALLOW_INTROSPECTION = True, so the Did you mean …? tails below are present; flip that flag off and the tails are stripped while the messages themselves stay.

The same rule is told on two columns where it matters more than on a bio:

The to-ONE hatch closes the ordering axis on the key behind it:

Uploading a file¶

documentCreate is a DjangoModelMutation over a model with a FileField, so a multipart part named after the field is merged into the payload with no extra configuration. GraphiQL cannot send multipart, so this one is a curl demo — run it against make run:

curl -s http://127.0.0.1:8000/graphql/ \
  -H 'X-Requested-With: XMLHttpRequest' \
  -F 'query=mutation { documentCreate(newDocument: { name: "Notes" }) { ok document { id name attachedFile } } }' \
  -F 'attachedFile=@notes.txt'

{"data":{"documentCreate":{"ok":true,"document":{"id":"1","name":"Notes","attachedFile":"documents/notes.txt"}}}}

Three variations worth running, because each one teaches a rule:

Two settings that ship on, and are invisible until they bite¶

config/settings.py deliberately does not set either of these — both ship enabled, and pinning a key to its own default only hides that you depend on it. The file names and explains them in comments instead, so a reader copying it meets both walls at their desk:

Try subscriptions live¶

The playground serves the v2 native subscription engine behind both standards-based transports: graphql-transport-ws on /ws/graphql/ and SSE (graphql-sse / text/event-stream) on /graphql/stream. The easiest way to watch them work is the built-in browser client:

1. Open http://127.0.0.1:8000/graphql/client/. WS mode is pre-selected and already points at /ws/graphql/; press Connect.

2. Press the run (▶) button. The editor is already holding a runnable document — the client ships yourSubscription(action: ALL_ACTIONS) { id } and its introspection renames the placeholder to the first field this schema's subscription root advertises, which here is postSubscription. Widen the selection set if you want more than the id:

   subscription {
     postSubscription(action: ALL_ACTIONS) {
       id
       title
       status
     }
   }
   

   The rename needs introspection, and this playground sets ALLOW_INTROSPECTION = True so it happens. On a project that leaves the flag off, the document still says yourSubscription and pressing ▶ answers Cannot query field 'yourSubscription' on type 'Subscription' until you type your own field name.

3. Trigger a change from GraphiQL in another tab (any existing author id works — grab one with { authors { results(page: 1) { id name } } }):

   mutation {
     postCreate(newPost: { title: "Live update", author: 1 }) {
       ok
       post { id title }
     }
   }
   

   The client streams the next event with the new post instantly. Both playground subscriptions set payload_mode = "full", so the whole serialized instance is deliverable — not just the id.

To try the SSE transport instead, switch the client's toggle to SSE and set the SSE endpoint to http://127.0.0.1:8000/graphql/stream (the playground mounts the SSE view on that route) before connecting.

More things to try:

• Per-subscriber filters — subscribe with commentSubscription(action: ALL_ACTIONS, filter: { post: { exact: 1 } }) { id text } and only that post's comments are delivered.
• Private subscription — log in at /admin/ first, then subscribe to noteSubscription(action: ALL_ACTIONS) { id title } from the same browser session. It is gated by AuthenticatedFieldsMiddleware, and subscription_scope server-forces "only my notes" — another user's note changes never reach you.

Run the test suite¶

The playground ships genuine end-to-end tests that drive the same consumer, SSE view and schema the server runs — a WS round-trip (subscribe → ORM Post.objects.create() → next frame received) and the equivalent SSE round-trip, the multipart upload in all four spellings, the projection boundary on every axis it can reach, both arms of the relation hatch, and the two settings that ship on:

make test          # runs the complete playground suite

Several of them assert the verbatim answer strings this page and the project's own README.md quote, so a message that changes turns the suite red instead of leaving the documentation quietly wrong.

Where to go next¶

• Sample Application — the illustrative tutorial companion
• Query Recipes and Mutation Recipes
• Subscriptions — the full transport and engine guide
• Query Optimization — what the optimizer does on every playground query