GraphQL Subscriptions for Real-Time Data: Implementation Patterns and Pitfalls

GraphQL subscriptions look beautiful in documentation. Define a subscription type, write a resolver that publishes events, and the client receives real-time updates with the same type safety as queries and mutations. The syntax is elegant. The developer experience is clean.

Then you deploy to production. And you discover: connection management is hard, scaling WebSockets across multiple server instances is non-trivial, and the operational complexity dwarfs the implementation effort. Here is what I learned building real-time features with GraphQL subscriptions.

How Subscriptions Work

GraphQL subscriptions use a persistent connection (typically WebSocket) between client and server. The flow: client sends a subscription operation over the WebSocket, the server registers the subscription, when relevant data changes, the server pushes an update to the client through the same connection, and the client receives typed data matching the subscription selection set.

Compared to REST polling: subscriptions are more efficient (no repeated requests), lower latency (instant push vs polling interval), and more elegant (same GraphQL type system for queries and real-time updates).

The Implementation (Simplified)

Server side: define a subscription type in your schema. Implement a resolver that returns an AsyncIterator. When data changes, publish to a pub/sub channel. The subscription resolver filters and delivers relevant events to subscribed clients.

Client side: use a subscription-capable client (Apollo Client, urql, or graphql-ws directly). Establish a WebSocket connection. Send the subscription document. Handle incoming data the same way you handle query results.

Libraries that handle the protocol: graphql-ws (modern, recommended), subscriptions-transport-ws (legacy, deprecated), and framework-specific implementations (Apollo Server, Yoga).

Pitfall 1: Connection Management

WebSocket connections are stateful. Unlike HTTP requests (stateless, short-lived), WebSocket connections persist for the user's entire session. This means:

Memory usage scales with connected users: each connection consumes server memory. 10,000 concurrent users = 10,000 persistent connections. Each holding subscription state, user context, and connection buffers.

Reconnection handling: connections drop (network changes, server restarts, mobile backgrounding). The client must detect disconnection, reconnect, and re-establish subscriptions. During disconnection, events are missed — you need a strategy for catching up.

Authentication lifecycle: the initial connection carries auth context (usually a token). But tokens expire. Refreshing auth on a persistent connection is more complex than refreshing on a per-request basis.

Pitfall 2: Scaling Across Multiple Servers

One server instance: straightforward. The server maintains all connections in memory, publishes events, and delivers them directly.

Multiple server instances (load-balanced): events published on Server A must reach clients connected to Server B. You need external pub/sub: Redis Pub/Sub is the most common solution. Server A publishes "tool updated" to Redis. All servers subscribe to Redis and forward events to their connected clients.

This adds: infrastructure complexity (Redis cluster required), latency (event → Redis → other servers → clients), and operational concerns (Redis connection management, message ordering, delivery guarantees).

Pitfall 3: Over-Subscription

Clients can subscribe to more events than they need. If your subscription sends all tool updates and the client only displays one tool: you are wasting bandwidth and server resources processing events the client discards.

Solutions: parameterized subscriptions (subscribe to updates for a specific tool ID), server-side filtering (only publish events matching the client's filter criteria), and client-side deduplication (ignore events that do not affect displayed data).

Pitfall 4: Backpressure

If the server produces events faster than a slow client can consume them: events queue up. Memory grows. Eventually the connection or server crashes.

Solutions: drop events when the client's queue exceeds a threshold (newest events only), batch events (combine multiple updates into one delivery), and disconnect slow clients with a warning.

When to Use Subscriptions

Use subscriptions for: collaborative features (multiple users editing simultaneously), live dashboards (metrics changing in real-time), chat and messaging (new messages appear instantly), and notifications (alerts pushed to connected users).

Do NOT use subscriptions for: infrequent updates (a tool added once per day does not need real-time push — polling every 5 minutes is fine), data that is not time-sensitive (user profile, settings — fetch on demand), or extremely high-frequency data (stock tickers with 100 updates/second — use dedicated streaming protocols).

Alternatives to Consider

Server-Sent Events (SSE): simpler than WebSockets. Unidirectional (server → client only). Works over HTTP/2. No connection upgrade needed. Better supported through proxies and load balancers. Ideal for: notification streams, live feeds, and dashboard updates where the client does not send data back.

Long polling: simple, works everywhere, no persistent connection. Less efficient but: zero infrastructure complexity, works through any proxy/firewall, and handles disconnection gracefully (just reconnect and poll again).

Real-time databases (Supabase Realtime, Firebase): handle the real-time infrastructure for you. If your data is in Supabase: their Realtime feature provides subscriptions without building WebSocket infrastructure.

Our Decision at AIDToolStack

We evaluated GraphQL subscriptions for real-time tool updates (new tools appearing, rating changes). Our conclusion: the operational complexity of WebSocket infrastructure was not justified for our update frequency (a few new tools per day).

Instead: we use SWR (stale-while-revalidate) with periodic revalidation. The page serves immediately from cache, then background-refreshes data. Users see updates within 30-60 seconds. Good enough for our use case, dramatically simpler to operate.

If we built collaborative features (multiple users editing collections simultaneously): we would invest in WebSocket infrastructure. The real-time requirement would justify the complexity.

If You Proceed: Architecture Recommendations

Use graphql-ws (not subscriptions-transport-ws): the modern protocol with better connection lifecycle handling.

External pub/sub from day one: even with a single server, use Redis. When you scale to multiple instances (and you will), the infrastructure is already in place.

Implement connection limits: prevent resource exhaustion from too many subscriptions per client.

Health checks and automatic reconnection: connections will drop. The client library should reconnect seamlessly, and the server should clean up stale connections.

Monitor connection counts: track active connections, subscription counts, and event delivery rates. These are your scaling indicators.

The Honest Assessment

GraphQL subscriptions are elegant in theory and complex in practice. For applications that genuinely need real-time push (collaborative editing, live chat, multiplayer): the investment is worthwhile because the alternative (polling) provides inferior user experience.

For applications where "near real-time" (30-second delays) is acceptable: simpler approaches (SWR revalidation, SSE, long polling) provide 90% of the benefit at 10% of the operational cost.