First steps with Graphcool’s graphql command line tools
Graphcool released it’s graphql command line tools two days ago, so I thought it would be nice to see how well they work, especially with our Neo4j GraphQL backend. And here’s the good news — pretty well.
You can see the quick demo below, that the article explains in detail.
So installing is easy, it’s just npm install -g graphql-cli, which makes a graphql command available. The tools make use of graphql-config a consistent way of of storing endpoints and related configuration information in YAML or JSON, which is specified here.
Here is a quick overview of the commands available:
Example GraphQL Backend
As example for my tests of graphql-cli, I use my Game of Thrones GraphQL backend.
(If you just want to test it out, you can also just run npm install -g neo4j-graphql-cli && neo4j-graphql to spin up the default movie database backend.)
After spinning up my Game of Thrones instance I find this connection information on my Neo4j Sandbox UI:
GraphQL-CLI Setup
So I can just run graphql init, which then nicely asks me for these things:
Authentication Headers !?!
All good so far. But when I try to run graphql ping I get this error message, which means that (of course) my authentication header is missing.
Unfortunately at 3am in the morning I didn’t think about looking through the graphql-config spec, so I delved into the code of graphql-cli and then graphql-config, looking for a place to add header information.
I found the code that treated the “endpoints” entries, either as URL if they are a string, or as “EndpointExtension” object otherwise, which then can also contain other information, like headers.
So I changed the entry manually into a JSON object and added my auth header information.
Now let’s try that ping again:
GraphQL-CLI Plugins
Before we go into schema operations which are quite text-heavy, let’s look at the plugin capabilities, for instance there is a graphql-voyager plugin, which you can install with npm install -g graphql-cli-voyager
After the quite huge install you can run graphql voyager, which then runs a local voyager server against your endpoint and renders your schema visually.
This plugin capability looks quite nice, so I look forward adding the capabilities of our own neo4j-graphql-cli as a plugin to this, especially
- spinning up and accessing the Neo4j based GraphQL backends,
- updating schema definitions,
- running graphql and cypher queries.
GraphQL-CLI Schema Fetching
Now we can also use the get-schema command, to test retrieving our schema.
If we run this a second time, the tool tells us there were no changes to the schema, nice.
That schema file is quite verbose, compared to the original that we pushed to the endpoint.
Which is mostly due to the auto-generated parameters for each field for ordering and pagination as well as the query-type per type and C(R)UD mutations that were also generated automatically by our extension. Plus a bunch of documentation comments.
I cut out more than 90% of the following, only leaving the Region type, the full file is here.
GraphQL-CLI Schema Diff
But it seems I made a mistake when writing the original schema, by forgetting to set the Region.name as mandatory field, so that it can be used as "id" by the auto-generated mutations.
So let’s fix that in my original schema, by changing type Region { name: String! ... } and updating the schema in my backend:
And now let’s look at the diff which a graphql diff <endpoint> provides to my local schema file, I could also run graphql diff <endpoint1> <endpoint2> to compare two running endpoints.
The diff is inverse for us, but I clearly see the results of my single change, we see the new addRegionHouses, deleteRegionHouses, addHouseRegion and deleteHouseRegion mutations, as well as the changes for the mutations for the Region type itself.
Now we can fetch the new schema and then our diff will be empty again.
Conclusion
This was my quick overview of the really nice graphql-clitool from Graphcool, well done. I didn’t go into the graphql playground command as we already cover that with our Neo4j backed GraphQL backend.
It would be great if graphql-cli would always use the explicit EndpointExtension config format and not the URL-string one, and also asked for additional information like auth headers during graphql init.
In retrospect I also realized if I had added a subscriptions URL, then the format would have been already different.
