Using GraphSchema.io

Using GraphSchema.io

GraphSchema.io hosts a GraphQL endpoint at https://graphschema.io/api/graphql.

Once you're a customer and have API keys, you use that GraphQL API to manage your infrastructure.

To deploy a Dgraph instance you need to:

• Call the addDgraphInstance(...) operation
• Wait the minute or so it takes GraphSchema.io to spin up your infrastructure
• Call the getDgraphInstance(...) operation to get the address and certificates of your new Dgraph instance
• Connect to the instance using its secured grpc address

Environments

GraphSchema.io splits your infrastructure into environments. That might typically be development, testing and production environments, but could be environments per project, or however you wish.

You can deploy multiple instances per environment.

As a customer, you provision your environments and set limits on your spend per environment. For example, you might provision a cheap environment that only allows basic instances for your development environment, an environment that allows lots of medium level instances for an automated and user testing environment, and the best possible for production.

In this alpha test, you're playing the role of a customer who's just starting out with GraphSchema.io, so you've provisioned one of the cheapest possible environments, that allows you to spin up at most two concurrent, basic-spec Dgraph instances. You've called this environment "Test". You can spin up and tearn down as many instances as you like, but just two running at once.

The GraphQL API

For the purposes of the alpha, you can use the API to find out about your environment and create Dgraph instances. That's these 5 GraphQL operations.

type Query {
    getEnvironment(id: ID!): Environment!
    queryEnvironment(nameSearchTerms: [String!]): [Environment!]!

    getDgraphInstance(id: ID!): DgraphInstance!
}

type Mutation {
    addDgraphInstance(inputData: DgraphInstanceInput!): DgraphInstance!
    deleteDgraphInstance(inputData: ID!): String
}

For the alpha, I've limited the GraphQL API to just these 5 operations, so you can't manage your environments, change your customer data, generate new API Keys, host GraphSchema instances, etc. (let me know if that doesn't work for you and I can leak you some extra capabilities)

How to Deploy a Dgraph Instance

You create a Dgraph instance in an environment, so you'll need to know the ID of your "Test" environment.

Find the Right Environment

For example, you can find your "Test" environment with the GraphQL query.

query queryEnvironments {
  queryEnvironment {
    id
    createdAt
    name
  }
}

To run that, you'd typically make a HTTP POST to the GraphQL endpoint. In a deployment pipeline, that might be from a script or in-code, but you can also use GraphQL interactively using a client like insomnia. In the post request, you'll need to set the authorization header with the customer credentials you were supplied with.

The environments query will return a typical GraphQL json response like

{
  "data": {
    "queryEnvironment": [
      {
        "id": "0x7",
        "createdAt": "2019-04-10T22:26:40.6818937Z",
        "name": "Test"
      }
    ]
  },
  "errors": []
}

Create a Dgraph Instance

Adding a Dgraph instance is just a matter of running the addDgraphInstance mutation. The result is the Id the Dgraph instance will have once it's created. For example:

mutation addDgraphInstance($dgInput: DgraphInstanceInput!) {
  addDgraphInstance(inputData: $dgInput) {
    id
  }
}

You'll need to supply a GraphQL input variable linking to the environment where you want to create the instance and giving the specifications of the Dgraph.

{
  "dgInput": {
    "replicas": 1,
    "shards": 1,
    "storageGB": 3,
    "env": {
      "id": "0x7"
    }
  }
}

Because this is an alpha, and your playing the role of a customer who bought an environment in which you can only provision basic instances, you can't replicate or shard your data or request machine specs. In the full version, you can spin up Dgraph instances with higher spec machines, shard your database and replicate those shards across multiple machines.

(Note that the operations currently present an Id that maps directly to a Dgraph UID in the backend database. That's just for my testing and tracking, and will disapear soon. After that, you'll only see an Id that GraphSchema.io mints for you. That'll be something like the dgraphId currently presented, e.g: "dgraphId": "ab075ee5".

It takes a maximum of about 2 minutes for the instance to spin up.

Find the Connection Details

Once the instance has been deployed, you can grab it's connection details and certificates using the getDgraphInstance query. For example, if the add mutation told you the Dgraph will have Id "0x93", then you can get its details with:

query getDgraphInstance {
  getDgraphInstance(id: "0x93") {
    dgraphId
    address
    certificates {
      caCert
      clientCert
      clientKey
    }
  }
}

Currently, while the instance is spinning up you won't get a response. You know it's up when getDgraphInstance returns all the details. Soon you'll get a response indicating "pending" or "deploying" while the instance being created. For a second or two after it's first up, you can still get a response of "Status(StatusCode=Unknown, Detail=\"Please retry again, server is not ready to accept requests\")" from Dgraph. That just means all the infrastructure is deployed, but Dgraph alpha and zero haven't completely sorted themselves out, which only takes a few seconds.

Connect to your Dgraph Instance

Your Dgraph instance has an address and tls certificates, so you connect straight to it over grpc as you normally would with a Dgraph client library.

For example, with the Dgraph go client, that would be something like:

peerCert, err := tls.LoadX509KeyPair(clientCert, clientKey)
if err != nil { ... }

caCertPool := x509.NewCertPool()
caCertPool.AppendCertsFromPEM(caCert)

tls := credentials.NewTLS(&tls.Config{
	Certificates: []tls.Certificate{peerCert},
	RootCAs:      caCertPool,
})

conn, err := grpc.Dial(address, grpc.WithTransportCredentials(tls))
if err != nil { ... }
defer conn.Close()

dc := api.NewDgraphClient(conn)
dg := dgo.NewDgraphClient(dc)

In the C# client, it would be:

var client = DgraphDotNet.Clients.NewDgraphClient();

var tls = new SslCredentials(caCert, new KeyCertificatePair(clientCert, clientKey));

client.Connect(address, tls);

How to Destroy a Dgraph Instance

Run the deleteDgraphInstance mutation with the id of the instance you want to destroy.

mutation deleteDgraphInstance($instance: ID!) {
  deleteDgraphInstance(inputData: $instance)
}

That's it; after that, it's gone.