Dgraph is an open-source, scalable, distributed, highly available and fast graph database, designed from the ground up to be run in production.
Dgraph cluster consists of different nodes (Zero, Alpha & Ratel), and each node serves a different purpose.
- Dgraph Zero controls the Dgraph cluster, assigns servers to a group, and re-balances data between server groups.
- Dgraph Alpha hosts predicates and indexes. Predicates are either the properties associated with a node or the relationship between two nodes. Indexes are the tokenizers that can be associated with the predicates to enable filtering using appropriate functions.
- Ratel serves the UI to run queries, mutations & altering schema.
Dgraph can be setup on Linux, Windows, Mac, Docker and Kubernetes. I decided to go with Docker on Ubuntu.
#1. Install Docker on Ubuntu
The first thing that you need to do is install Docker Engine on Ubuntu. You can check out the official link or you can follow the below steps. I have installed Docker Engine on Ubuntu 20.04.
Update the apt package index and install packages to allow apt to use a repository over HTTPS:
$ sudo apt-get update $ sudo apt-get install \ apt-transport-https \ ca-certificates \ curl \ gnupg-agent \ software-properties-common
Add Docker’s official GPG key:
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
Set up a stable repository :
$ sudo add-apt-repository \ "deb [arch=amd64] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) \ stable"
Install Docker Engine :
$ sudo apt-get update $ sudo apt-get install docker-ce docker-ce-cli containerd.io
You can verify if Docker Engine is installed successfully by running the hello-world image.
$ sudo docker run hello-world
It will show something like below.
$ sudo docker run hello-world Unable to find image 'hello-world:latest' locally latest: Pulling from library/hello-world 0e03bdcc26d7: Pull complete Digest: sha256:1a523af650137b8accdaed439c17d684df61ee4d74feac151b5b337bd29e7eec Status: Downloaded newer image for hello-world:latest Hello from Docker! This message shows that your installation appears to be working correctly.
#2. Install Dgraph
Now that Docker is installed on your local Ubuntu, you can install Dgraph using Docker Compose.
Download the docker-compose.yml using the below command.
$ wget https://github.com/dgraph-io/dgraph/raw/master/contrib/config/docker/docker-compose.yml \
Before running the docker-compose command, make sure sure to add a list of whitelisted IPs for dgraph so that you can create the schema later on. This is because by default only the localhost IP (127.0.0.1) will be whitelisted. When you run Dgraph on Docker, the containers are assigned IPs of their own which needs to be whitelisted.
Below is how docker-compose.yml will look like.
$ cat docker-compose.yml # This Docker Compose file can be used to quickly bootup Dgraph Zero # and Alpha in different Docker containers. # It mounts /tmp/data on the host machine to /dgraph within the # container. You can change /tmp/data to a more appropriate location. # Run `docker-compose up` to start Dgraph. version: "3.2" services: zero: image: dgraph/dgraph:latest volumes: - /tmp/data:/dgraph ports: - 5080:5080 - 6080:6080 restart: on-failure command: dgraph zero --my=zero:5080 alpha: image: dgraph/dgraph:latest volumes: - /tmp/data:/dgraph ports: - 8080:8080 - 9080:9080 restart: on-failure command: dgraph alpha --my=alpha:7080 --zero=zero:5080 --whitelist 172.17.0.0:172.30.0.0,192.168.1.1 ratel: image: dgraph/dgraph:latest ports: - 8000:8000 command: dgraph-ratel
Next, run the docker-compose command.
$ sudo docker-compose up
If docker-compose is not installed, you can install it using the below command.
$ sudo apt install docker-compose
Once Dgraph is installed on Docker, you can verify both the image and the container. There will be 1 image and 3 containers running for Dgraph.
To check the image, use the below command.
$ sudo docker images -a REPOSITORY TAG IMAGE ID CREATED SIZE dgraph/dgraph latest 3e21ad276d7f 7 weeks ago 165MB
To check for running containers, use the below command.
$ sudo docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES e399d56120b7 dgraph/dgraph:latest "dgraph-ratel" About an hour ago Up About an hour 8080/tcp, 0.0.0.0:8000->8000/tcp, 9080/tcp dgraph_ratel_1 5a0d35289561 dgraph/dgraph:latest "dgraph alpha --my=a…" About an hour ago Up About an hour 0.0.0.0:8080->8080/tcp, 0.0.0.0:9080->9080/tcp dgraph_alpha_1 a872aa520c69 dgraph/dgraph:latest "dgraph zero --my=ze…" About an hour ago Up About an hour 0.0.0.0:5080->5080/tcp, 8080/tcp, 0.0.0.0:6080->6080/tcp, 9080/tcp dgraph_zero_1
Now that all the containers are running, you can open the Ratel UI – http://localhost:8000/. Ratel basically provides an UI to run queries/mutations on your GraphQL server.
#3. Docker Container Network
Each docker container running will have it’s own dedicated IP. To check for networks in Docker, use the below command.
$ sudo docker network ls NETWORK ID NAME DRIVER SCOPE e642b5a606fa bridge bridge local 99801d7deafd dgraph_default bridge local 671e48a6e0cf host host local c353d6efbe76 none null local
Now if you have to inspect a particular network, you need to use the Network ID in the below command. This will give you the IPs assigned to each of the Dgraph containers.
$ sudo docker network inspect 99801d7deafd [ { "Name": "dgraph_default", "Id": "99801d7deafdea427c5cf27c720cc1eda89a4721ce1a5cb7c421b1fea7610ef9", "Created": "2020-12-10T23:06:02.33267497+05:30", "Scope": "local", "Driver": "bridge", "EnableIPv6": false, "IPAM": { "Driver": "default", "Options": null, "Config": [ { "Subnet": "172.21.0.0/16", "Gateway": "172.21.0.1" } ] }, "Internal": false, "Attachable": true, "Ingress": false, "ConfigFrom": { "Network": "" }, "ConfigOnly": false, "Containers": { "5a0d352895613574f2e0a7d5d6e45597c9fd365a5e702377658b5c77e400c212": { "Name": "dgraph_alpha_1", "EndpointID": "51f68897df1f559657fd5c123656304d949766d57f8d449f331ef581f3617db9", "MacAddress": "02:42:ac:15:00:03", "IPv4Address": "172.21.0.3/16", "IPv6Address": "" }, "a872aa520c69f4b4c99160bde6c471c86550bb8731ff557d0f888898869d33f2": { "Name": "dgraph_zero_1", "EndpointID": "36de03da968ec24c767c86d8ce02573d602a90cded92db3eb0ca6cba5358db79", "MacAddress": "02:42:ac:15:00:04", "IPv4Address": "172.21.0.4/16", "IPv6Address": "" }, "e399d56120b7300d2bce3f414bc4e484f90e247c5b690a6439cf853eadca6f33": { "Name": "dgraph_ratel_1", "EndpointID": "a588f021a1d71dc9cfe03c5d952e4852f37749ce7075fd82167b51b5561e5e4e", "MacAddress": "02:42:ac:15:00:02", "IPv4Address": "172.21.0.2/16", "IPv6Address": "" } }, "Options": {}, "Labels": { "com.docker.compose.network": "default", "com.docker.compose.project": "dgraph", "com.docker.compose.version": "1.25.0" } } ]
#4. Adding schema to GraphQL
The Dgraph Quick Start Guide has a no. of examples with which you can get started. You can just use the below schema. Put the contents in a schema.graphql file and run the below command.
type Product { productID: ID! name: String @search(by: [term]) reviews: [Review] @hasInverse(field: about) } type Customer { username: String! @id @search(by: [hash, regexp]) reviews: [Review] @hasInverse(field: by) } type Review { id: ID! about: Product! by: Customer! comment: String @search(by: [fulltext]) rating: Int @search }
If the schema gets updated, you will get a success response.
$ curl -X POST localhost:8080/admin/schema --data-binary '@schema.graphql' {"data":{"code":"Success","message":"Done"}}
You can check the schema from the Ratel UI as well.
#5. Test the GraphQL endpoint
Now that your schema is updated, you can test the endpoint of the GraphQL which will be available at http://localhost:8080/graphql
To test the endpoint, you can install GraphQL Playground or GraphiQL or Insomnia or Altair. I went ahead with Insomnia.
On Ubuntu, you can either install it using snap or download the .deb package.
For snap, run the below command.
$ sudo snap install insomnia
To install from .deb package, run the below command. Filename would vary depending on the current version.
$ sudo dpkg -i Insomnia.Core-2020.5.2.deb
Once Insomnia is installed, you can use the API and run queries/mutations.
Conclusion
Overall, Dgraph provides one of the easiest ways to create a GraphQL server. Together with Docker and Kubernetes, Dgraph can be scaled effectively.
If you’re looking to using Dgraph for your enterprise, you can check out Slash Enterprise which works with AWS and Azure, or your own cloud.