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 --group test — local library (editable) + daphne + test tools
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.

Not production-ready¶

The playground settings are a development fixture. manage.py check --deploy reports seven warnings on them: DEBUG = True, a short hard-coded SECRET_KEY, no HSTS, no SSL redirect, insecure session and CSRF cookies, and no clickjacking middleware. Copy the patterns (the DJANGO_GRAPHEX block, the schema wiring), not the file, into a real project and set those deliberately.

WebSocket origin policy¶

The shipped ALLOWED_HOSTS is exactly 127.0.0.1, localhost and testserver; the last one exists only because Django's test client and Channels' test communicator use that host, so drop it from a copy that is not run by this test suite. 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 — when logged in — 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. Logged out, PostType.get_queryset shows only the 4 published posts per author, which fit on one page. 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 and comment writes, noteSubscription) and the private mutations postUpdate, postDelete and documentUpdate require a logged-in user. Exactly these writes are deliberately open to anonymous callers, so you can compare a gated write with an ungated one:

The destructive or modifying siblings are mounted under PrivateMutation (private_mutation= on DjangoGraphQLSchema), so an anonymous call answers Authentication required.. To log in:

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. An account made with registerUser is not staff and cannot log in anywhere here: the admin login accepts staff only and the playground ships no other login view.

The ids in the examples (id: 1, author: 1) assume a fresh database from make reset; re-running make seed on existing rows creates new ids, so look one up first.

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(first: 2) { hasNextPage endCursor }
      }
    }
  }
  authors {
    totalCount
    results(page: 1) { name }
  }
  comments {
    totalCount
    results(first: 3) { text }
    pageInfo(first: 3) { 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 schema-derived Did you mean …? hints may appear. Flip that flag off and the hints are stripped while the rejection and any trailing Found detail remain. Input-field wording varies by graphql-core generation.

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"}}}}

The file column is an allow-list (.txt, .pdf, .png, .jpg, .jpeg, .gif), applied by both upload paths: an .html or .svg upload answers ok: false. While DEBUG is on, uploaded files are served as downloads (Content-Disposition: attachment, nosniff, Content-Security-Policy: sandbox); in production serve user uploads from a separate domain or CDN, never from the application's own origin.

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

BigInt and Decimal over the wire¶

Both scalars travel as strings, so a value past 2**53 or a money amount never passes through a JSON float. Log in first (the BigInt post is a seeded draft) and run:

{ postsFlat(ordering: "-viewCount", limit: 1) { id viewCount } }

It answers "9007199254740993". The Decimal side needs no login:

{ attachments { results { target { ... on AccountType { balance } } } } }

answers balance: "1200.50" for the first account. A test pins both documents against the project README.md.

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, status: PUBLISHED }) {
       ok
       post { id title }
     }
   }
   

   The client streams the next event with the new post instantly. The explicit published status is required for an anonymous subscriber; omitting it creates a draft that this stream intentionally hides. 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 with both spellings of the part name, 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