Running GraphSchema

This example shows how to get a running GraphQL API with GraphSchema.

The example schema is here. The instructions below get you to clone the example repository if you wish.

How to run GraphSchema

There are three steps to get from a GraphQL schema file to a running API.

1. Start the Dgraph database.
2. Initialize the database by installing the schema into it (GraphSchema's init-dgraph --schema-file AuthorPosts.graphql ... command).
3. Start GraphSchema's GraphQL API (GraphSchema's api-run ... command).

For this walkthrough it's easiest if you clone the example.

git clone https://github.com/MichaelJCompton/GraphSchemaTools
cd GraphSchemaTools/GraphSchema.Examples/AuthorPosts/

Start Dgraph

If you're new to Dgraph, you should check the Dgraph getting started docs. (current version of GraphSchema was tested against Dgraph v1.0.13)

You can run Dgraph locally on the same machine as GraphSchema, remotely, using docker, or using kubernetes. All GraphSchema needs is to be able to contact Dgraph.

It's best to start with a new Dgraph database.

For running up locally, I often use a script like this. With that, I can run ./dgraph.sh start, ./dgraph.sh stop and ./dgraph.sh clean as needed to easily start and stop Dgraph and clean up. There's a kubernetes example (on the way - FIXME).

If you have dgraph installed (e.g curl https://get.dgraph.io -sSf | bash) and you've cloned the example repository, then you can run

../scripts/dgraph.sh start

to start Dgraph.

Initialise the database

To run a GraphSchema command either use the helper script, or run GraphSchema directly using docker run mjcomp/graphschema ....

Both ./graphschema.sh and docker run mjcomp/graphschema show the help menu.

To initialise the example database using the helper script:

./graphschema.sh init-dgraph --schema-file AuthorPosts.graphql --dgraph-alpha "<alpha-addr>:<alpha-grpc-port>"  --force --verbose

or, directly with docker (you'll need to mount the input file into the container):

docker run --mount type=bind,source=<AuthorPosts-folder>,destination=/data,readonly mjcomp/graphschema init-dgraph --schema-file /data/AuthorPosts.graphql --dgraph-alpha "<alpha-addr>:<alpha-grpc-port>"  --force --verbose

Substitute in the values for where your Dgraph is running.

The dgraph.sh start script uses Dgraph's defaults, so if you've used that, then Dgraph is running on localhost at port 9080. Because GraphSchema is running in a container, you can't use localhost directly, so you either need your ip (you can try this tip on Linux), or, on a mac, you can use host.docker.internal, e.g:

./graphschema.sh init-dgraph --schema-file AuthorPosts.graphql --dgraph-alpha "host.docker.internal:9080" --force --verbose

Run the GraphSchema GraphQL API

Now that the database is ready, you can run GraphSchema from anywhere that can contact the database and run as many instances as you like.

The helper script will bring up the GraphQL API on its default port of 10550.

./graphschema.sh api-run --dgraph-alpha "<alpha-addr>:<alpha-grpc-port>"

Or, in docker:

docker run -p 10550:10550 mjcomp/graphschema api-run --dgraph-alpha "<alpha-addr>:<alpha-grpc-port>"

I'm on a Mac, so I use

./graphschema.sh api-run --dgraph-alpha "host.docker.internal:9080"

Running queries and mutations

Once the API is up and running, the rest is just GraphQL.

GraphSchema serves a GraphQL API at api/graphql. If you've used the helper script, that'll be at http://localhost:10550/api/graphql.

Check out the Example Mutations and Queries.