We’re overhauling Dgraph’s docs to make them clearer and more approachable. If
you notice any issues during this transition or have suggestions, please
let us know.
- Running Dgraph on your on-premises infrastructure (virtual or bare-metal physical servers)
- Running Dgraph on your cloud infrastructure (AWS, Google Cloud and Azure)
Overview
A Dgraph cluster consists of the following:- Dgraph Alpha database server nodes: The Dgraph Alpha server nodes in your
deployment host and serve data. These nodes also host an
/admin
HTTP and gRPC endpoint that can be used for data and node administration tasks such as backup, export, draining, and shutdown. - Dgraph Zero management server nodes: The Dgraph Zero nodes in your deployment control the nodes in your Dgraph cluster. Dgraph Zero automatically moves data between different Dgraph Alpha instances based on the volume of data served by each Alpha instance.
- IP White-listing (use the
--security
superflag’swhitelist
option on Dgraph Alpha to whitelist IP addresses other than localhost). - Poor-man’s auth, if Dgraph Alpha is started with the
--security
superflag’stoken
option, then you should pass the token as anX-Dgraph-AuthToken
header while making the HTTP request. - Guardian-only access, if Access Control Lists (ACL) is enabled. In this case
you should pass the ACL-JWT of a Guardian user using the
X-Dgraph-AccessToken
header while making the HTTP request.
/admin
path. The
current list of admin endpoints includes the following:
/admin
/admin/config/cache_mb
/admin/draining
/admin/shutdown
/admin/schema
/admin/schema/validate
/alter
/login
/login
: This endpoint logs-in an ACL user, and provides them with a JWT. Only IP Whitelisting and Poor-man’s auth checks are performed for this endpoint./admin
: This endpoint provides GraphQL queries/mutations corresponding to the HTTP admin endpoints. All of the queries/mutations on/admin
have all three layers of authentication, except forlogin (mutation)
, which has the same behavior as the HTTP/login
endpoint.
Whitelisting admin operations
By default, admin operations can only be initiated from the machine on which the Dgraph Alpha runs. You can use the--security
superflag’s whitelist
option to specify a
comma-separated whitelist of IP addresses, IP ranges, CIDR ranges, or hostnames
for hosts from which admin operations can be initiated.
IP Address
localhost
only).
IP Range
172.17.0.0
and
172.20.0.0
along with the server which has IP address as 192.168.1.1
.
CIDR Range
172.17.0.0/16
, 172.18.0.0/15
, 172.20.0.0/32
, or 192.168.1.1/32
(the same
range as the IP Range example).
You can set whitelist IP to 0.0.0.0/0
to whitelist all IP addresses.
Hostname
admin-bastion
and
host.docker.internal
.
Restrict mutation operations
By default, you can perform mutation operations for any predicate. If the predicate in mutation doesn’t exist in the schema, the predicate gets added to the schema with an appropriate Dgraph Type. You can use--limit "mutations=disallow"
to disable all mutations, which is
set to allow
by default.
--limit "mutations=strict
. This mode allows
mutations only on predicates already in the schema. Before performing a mutation
on a predicate that doesn’t exist in the schema, you need to perform an alter
operation with that predicate and its schema type.
Secure alter operations
Clients can use alter operations to apply schema updates and drop particular or all predicates from the database. By default, all clients are allowed to perform alter operations. You can configure Dgraph to only allow alter operations when the client provides a specific token. You can use this “Simple ACL” token to prevent clients from making unintended or accidental schema updates or predicate drops. You can specify the auth token with the--security
superflag’s token
option
for each Dgraph Alpha in the cluster. Clients must include the same auth token
to make alter requests.
To fully secure alter operations in the cluster, the authentication token must
be set for every Alpha node.
Export database
As anAdministrator
you might want to export data from Dgraph to:
- backup your data
- migrate your data from one instance to another
- share your data
Shut down database
A clean exit of a single Dgraph node is initiated by running the following GraphQL mutation on /admin endpoint.This won’t work if called from outside the server where Dgraph is running. You
can specify a list or range of whitelisted IP addresses from which shutdown or
other admin operations can be initiated using the
--security
superflag’s
whitelist
option on dgraph alpha
.Delete database
To drop all data, you could send aDropAll
request via /alter
endpoint.
Alternatively, you could:
- Shutdown Dgraph and wait for all writes to complete,
- Delete (maybe do an export first) the
p
andw
directories, then - Restart Dgraph.
Upgrade database
Doing periodic exports is always a good idea. This is particularly useful if you wish to upgrade Dgraph or reconfigure the sharding of a cluster. The following are the right steps to safely export and restart.- Start an export
- Ensure it’s successful
- Shutdown Dgraph and wait for all writes to complete
- Start a new Dgraph cluster using new data directories (this can be done by
passing empty directories to the options
-p
and-w
for Alphas and-w
for Zeros) - Reload the data via Bulk Loader
- Verify the correctness of the new Dgraph cluster. If all looks good, you can delete the old directories (export serves as an insurance)
--mutations disallow
when you restart the Alpha nodes. This ensures the cluster is in read-only mode.
At this point your app can still read from the old cluster and you can perform
steps 4 and 5. When the new cluster (that uses the upgraded version of Dgraph)
is up and running, you can point your app to it, and shutdown the old cluster.