Getting started with subscriptions

This guide shows how to start using subscription capabilities on a GraphQL server.

If you use Apollo Studio, make sure to select the graphql-ws implementation in the connection settings.

Enable subscription capabilities

Before using subscriptions on a GraphQL server, you must enable them by passing the subscriptions feature to Neo4jGraphQL:

new Neo4jGraphQL({
    typeDefs,
    driver,
    features: {
        subscriptions: true
    },
});

Install dependencies

Then, the next step is to install the following dependencies:

npm i --save ws graphql-ws neo4j-driver @neo4j/graphql express @apollo/server body-parser cors

Set up an @apollo/server server

Add the following code to your index.js file to implement a simple @apollo/server server with subscriptions (for more options, see Apollo’s documentation):

import { ApolloServer } from "@apollo/server";
import { expressMiddleware } from "@apollo/server/express4";
import { ApolloServerPluginDrainHttpServer } from "@apollo/server/plugin/drainHttpServer";
import bodyParser from 'body-parser';
import cors from "cors";
import { createServer } from "http";
import neo4j from 'neo4j-driver';
import { Neo4jGraphQL } from '@neo4j/graphql';
import { WebSocketServer } from "ws";
import { useServer } from "graphql-ws/lib/use/ws";
import express from 'express';

const typeDefs = `
    type Movie {
        title: String
    }

    type Actor {
        name: String
    }
`;

const driver = neo4j.driver("bolt://localhost:7687", neo4j.auth.basic("neo4j", "password"));

const neoSchema = new Neo4jGraphQL({
    typeDefs,
    driver,
    features: {
        subscriptions: true
    },
});

async function main() {
    // Apollo server setup with WebSockets
    const app = express();
    const httpServer = createServer(app);
    const wsServer = new WebSocketServer({
        server: httpServer,
        path: "/graphql",
    });

    // Neo4j schema
    const schema = await neoSchema.getSchema();

    const serverCleanup = useServer(
        {
            schema,
            context: (ctx) => {
                return ctx;
            },
        },
        wsServer
    );

    const server = new ApolloServer({
        schema,
        plugins: [
            ApolloServerPluginDrainHttpServer({
                httpServer
            }),
            {
                async serverWillStart() {
                    return Promise.resolve({
                        async drainServer() {
                            await serverCleanup.dispose();
                        },
                    });
                },
            },
        ],
    });
    await server.start();

    app.use(
        "/graphql",
        cors(),
        bodyParser.json(),
        expressMiddleware(server, {
            context: async ({ req }) => ({ req }),
        })
    );

    const PORT = 4000;
    httpServer.listen(PORT, () => {
        console.log(`Server is now running on http://localhost:${PORT}/graphql`);
    });
}

main();

This setup uses the default subscriptions mechanism suitable only for development, testing, and single instance servers. If you need to scale horizontally for a production-ready application, see Horizontal scaling.

GraphQL subscriptions

With the previous server running, the available subscriptions are set for Movie and Actor. You can subscribe to new movies created with the following statement:

graphql
subscription {
    movieCreated(where: { title: "The Matrix" }) {
        createdMovie {
            title
        }
    }
}

With that, any new movie created with the matching title will trigger a subscription. You can try this with the following query:

mutation {
    createMovies(input: [{ title: "The Matrix" }]) {
        movies {
            title
        }
    }
}

Further reading

Keep reading this section on Subscriptions for more information and advanced examples.