diff --git a/content/_index.md b/content/_index.md index e721d9f9..b085240b 100644 --- a/content/_index.md +++ b/content/_index.md @@ -47,7 +47,7 @@ aliases = ["/contribute"]
- + }}">

Dgraph Cloud

Run Dgraph in the Cloud. diff --git a/content/dgraphcloud/_index.md b/content/dgraphcloud/_index.md index f70e0f5a..6aa9d3f1 100644 --- a/content/dgraphcloud/_index.md +++ b/content/dgraphcloud/_index.md @@ -1,61 +1,74 @@ +++ title = "Dgraph Cloud" [menu.main] - identifier = "dgraphcloud" + identifier = "cloud" weight = 9 +++

+

- This section is about Dgraph Cloud. + Dgraph Cloud gives you the power of Dgraph database with the convenience of a fully-managed service.

- +

To learn more about Dgraph, see }}">Dgraph Database Overview.

+
-
- }}"> -

Download

+
+ }}"> +

Dgraph Cloud Quick Start

- Download the images and source files to build and install for a production-ready Dgraph cluster + Get started with a simple "to-do" list app built on Dgraph Cloud

-
- }}"> -

Using Kubernetes

+
+ }}"> +

Advanced Queries with DQL

- Running Dgraph with Kubernetes + Generate advanced queries to interact with your database using the HTTP or gRPC endpoint +

+ +
+
+
+ }}"> +

Dgraph Cloud API

+

+ Programmatically launch and manage your Cloud backups.

- - -
-
- }}"> -

Single Host Setup

+
+ }}"> +

Secure Your Endpoint

- Setting up Dgraph on a single host + Tips for securing your Dgraph Cloud backend

- }}"> -

Multi Host Setup

+ }}"> +

Migrate from Self-Managed Dgraph

- Setting up Dgraph on multiple hosts + Easily migrate your app's existing Dgraph backend to Dgraph Cloud

- +
+
+
+ }}"> +

Administer Your Backend

+

+ Programmatically set and update your schema, import or export your data, and switch or clone your Dgraph Cloud backend +

+ +
@@ -64,3 +77,9 @@ title = "Dgraph Cloud" display: none; } + +You might also be interested in: + +- [Dgraph GraphQL Schema Reference](https://dgraph.io/docs/graphql/schema/schema-overview), which lists all the types and directives supported by Dgraph +- [Dgraph GraphQL API Reference](https://dgraph.io/docs/graphql/api/api-overview), which serves as a guide to using your new `/graphql` endpoint + diff --git a/content/dgraphcloud/admin/_index.md b/content/dgraphcloud/admin/_index.md new file mode 100644 index 00000000..3acfff15 --- /dev/null +++ b/content/dgraphcloud/admin/_index.md @@ -0,0 +1,7 @@ ++++ +title = "Administering Your Backend" +weight = 15 +[menu.main] + identifier = "cloud-admin" + parent = "cloud" ++++ diff --git a/content/dgraphcloud/admin/authentication.md b/content/dgraphcloud/admin/authentication.md new file mode 100644 index 00000000..284f116b --- /dev/null +++ b/content/dgraphcloud/admin/authentication.md @@ -0,0 +1,31 @@ ++++ +title = "Authentication" +weight = 2 +[menu.main] + parent = "cloud-admin" ++++ + +Administrating your Dgraph Cloud using the `/query`, `/mutate`, `/commit`, `/admin`, `/admin/slash`, or `/alter` endpoints on Dgraph Cloud. Also, bypassing Anonymous Access restrictions on the `/graphql` endpoint requires an API key. You can generate a new API key from Dgraph Cloud by selecting the ["Settings" button](https://cloud.dgraph.io/_/settings) from the sidebar, and then clicking the **Add API Key** button. Keep your API key safe, it will not be accessible once you leave the page. + +![Dgraph Cloud: Add an API Key](/images/cloud-4.png) + +There are two types of API keys: *client* and *admin*. + +- **Client API keys** can only be used to perform query, mutation, and commit operations. +- **Admin API keys** can be used to perform both client operations and admin operations like drop data, destroy backend, and update schema. + +{{% notice "note" %}} +Either Client API keys or Admin API keys can be used to bypass [Anonymous Access](/security) restrictions. +{{% /notice %}} + +![Dgraph Cloud: Select API Key Role](/images/cloud-5.png) +
+
+All admin API requests must be authenticated by passing the API key as the 'Dg-Auth' header to every HTTP request. You can verify that your API key works by using the following HTTP example. + +``` +curl 'https:///admin' \ + -H 'Dg-Auth: ' \ + -H 'Content-Type: application/json' \ + --data-binary '{"query":"{ getGQLSchema { schema } }"}' +``` diff --git a/content/dgraphcloud/admin/clone.md b/content/dgraphcloud/admin/clone.md new file mode 100644 index 00000000..b02d0dee --- /dev/null +++ b/content/dgraphcloud/admin/clone.md @@ -0,0 +1,12 @@ ++++ +title = "Cloning Backend" +weight = 7 +[menu.main] + parent = "cloud-admin" ++++ + +Cloning a backend allows making a copy of an existing backend. The clone will be created with all the data and schema of the original backend present at the time of cloning. The clone will have its own endpoint and will be independent of the original backend once it is created. Any further changes in either backends will not reflect in the other. Currently, a clone can only be created in the same zone as that of the original backend. + +In order to clone your backend, click on the Clone Backend button under the [Settings](https://cloud.dgraph.io/_/settings) tab in the dashboard's sidebar. + +You can also perform the restore operation on an existing backend if you have an unused backend or want to reuse an existing endpoint. But note that the restore operation will drop all the existing data along with schema on the current backend and replace it with the original backend's data and schema. diff --git a/content/dgraphcloud/admin/drop-data.md b/content/dgraphcloud/admin/drop-data.md new file mode 100644 index 00000000..6f2eaac7 --- /dev/null +++ b/content/dgraphcloud/admin/drop-data.md @@ -0,0 +1,36 @@ ++++ +title = "Dropping Data from your Backend" +weight = 5 +[menu.main] + parent = "cloud-admin" ++++ + +It is possible to drop all data from your Dgraph Cloud backend, and start afresh while retaining the same endpoint. Be careful, as this operation is not reversible, and all data will be lost. It is highly recommended that you [export](/admin/import-export) your data before you drop your data. + +In order to drop all data while retaining the schema, click the Drop Data button under the [Schema](https://cloud.dgraph.io/_/schema) tab in the sidebar. + +![Drop Data](/images/drop-data.png) + +### Dropping Data Programmatically + +In order to do this, call the `dropData` mutation on `/admin/slash`. As an example, if your GraphQL endpoint is `https://frozen-mango.us-west-2.aws.cloud.dgraph.io/graphql`, then the admin endpoint for schema will be at `https://frozen-mango.us-west-2.aws.cloud.dgraph.io/admin/slash`. + +Please note that this endpoint requires [Authentication](/admin/authentication). + +Please see the following curl as an example. + +``` +curl 'https:///admin/slash' \ + -H 'X-Auth-Token: ' \ + -H 'Content-Type: application/graphql' \ + --data-binary 'mutation { dropData(allData: true) { response { code message } } }' +``` + +If you would like to drop the schema along with the data, then you can set the `allDataAndSchema` flag. + +``` +curl 'https:///admin/slash' \ + -H 'X-Auth-Token: ' \ + -H 'Content-Type: application/graphql' \ + --data-binary 'mutation { dropData(allDataAndSchema: true) { response { code message } } }' +``` diff --git a/content/dgraphcloud/admin/import-export.md b/content/dgraphcloud/admin/import-export.md new file mode 100644 index 00000000..56fea976 --- /dev/null +++ b/content/dgraphcloud/admin/import-export.md @@ -0,0 +1,156 @@ ++++ +title = "Importing and Exporting data from Dgraph Cloud" +weight = 4 +[menu.main] + parent = "cloud-admin" ++++ + +You can export your data from one Dgraph Cloud backend, and then import this data back into another Dgraph instance or Dgraph Cloud Backend. + +## Exporting Data + +You can export your data using JSON format. To do this, call the `export` mutation on `/admin/slash`. As an example, if your GraphQL endpoint is at `https://frozen-mango.us-west-2.aws.cloud.dgraph.io/graphql`, then the `/admin` endpoint for the schema is at `https://frozen-mango.us-west-2.aws.cloud.dgraph.io/admin/slash`. + +{{% notice "note" %}} +The `/admin/slash` endpoint requires [Authentication](/admin/authentication). +{{% /notice %}} + +The following is an example of a GraphQL mutation to export data to JSON. + +```graphql +mutation { + export { + response { code message } + exportId + taskId + } +} +``` +Make sure to keep your `exportId` and `taskId` safe as you will need them for getting the signed URLs in order to download your export files. These URLs will be returned in the `signedUrls` output field and **they expire after 48 hours**. + +Export will usually return 3 files: +* `g01.gql_schema.gz`: The GraphQL schema file. This file can be re-imported via the [Schema APIs](/admin/schema) +* `g01.json.gz`: the data from your instance, which can be imported via live loader +* `g01.schema.gz`: This file is the internal Dgraph schema. If you have set up your backend with a GraphQL schema, then you should be able to ignore this file. + +The following is an example of GraphQL query to check the status of the export and get the signed URLs for downloanding your export files. + +```graphql +query { + exportStatus ( + exportId:"" + taskId: "" + ){ + kind + lastUpdated + signedUrls + status + } +} +``` +## Exporting Data with Multi-Tenancy feature enabled + +{{% notice "note" %}} +With Multi-Tenancy feature enabled, for any GraphQL request you will need to provide the `accessJWT` for the specific user in the `X-Dgraph-AccessToken` header. +{{% /notice %}} + +You can trigger two types of exports: +* cluster-wide export: this is an export of the entire backend (including all namespaces). This request can be only triggered by the [*Guardian of Galaxy*](https://dgraph.io/docs/enterprise-features/multitenancy/#guardians-of-the-galaxy) users. +* namespace-specific export: this is an export of a specific namespace. This request can be triggered by the *Guardian of Galaxy* users and by the *Guardian of Namespace* users. + +### Cluster-wide Exports + +This can only be done by the *Guardian of Galaxy* users (AKA Super Admin), the steps are: + +1. Get the `accessJWT` token for the *Guardian of Galaxy* user. Send the following GraphQL mutation to the `/admin` endpoint: +```graphql +mutation login($userId: String, $password: String, $namespace: Int) { + login(userId: $userId, password: $password, namespace: $namespace) { + response { + accessJWT + refreshJWT + } + } +} +``` +Your variables should be referring to the *Guardian of Galaxy* user: +```json +{ + "userId": "groot", + "password": "password", + "namespace": 0 +} +``` +2. Once obtained the `accessJWT` token you need to pass it in `X-Dgraph-AccessToken` Header and only then you can send the following GraphQL mutation to `/admin/slash` endpoint: +```graphql +mutation { + export (namespace: -1) { + response { code message } + exportId + taskId + } +} +``` +3. Once done, you can now send the following GraqhQL mutation to get the `signedUrls` from where you can download your export files: +```graphql +query { + exportStatus ( + exportId:"" + taskId: "" + ){ + kind + lastUpdated + signedUrls + status + } +} +``` + +### Namespace-specific Exports + +Namespace-specific exports can be triggered by the *Guardian of Galaxy* users. In this case you can follow the same steps for the cluster-wide exports and replace the namespace value from `-1` to the namespace you want to export. It's important that you get the `accessJWT` token for the *Guardian of Galaxy* user and pass it in the `X-Dgraph-AccessToken` header. + +E.g. if you want to export the namespace `0x123` your GraphQL request sent to the `/admin/slash` endpoint would look like: +```graphql +mutation { + export (namespace: 123) { + response { code message } + exportId + taskId + } +} +``` +You can also trigger namespace-specific export using the *Guardian of Namespace* users, in this case there is no need to specify any namespace in the GraphQL request as these users can only export their own namespace. It's important that you get the `accessJWT` token for the *Guardian of Namespace* user and pass it in the `X-Dgraph-AccessToken` header. + +The GraphQL request sent to the `/admin/slash` endpoint would be: +```graphql +mutation { + export { + response { code message } + exportId + taskId + } +} +``` + +## Importing data with Live Loader + +It is possible to import data into a Dgraph Cloud backend using [live loader](https://dgraph.io/docs/deploy/#live-loader). In order to import data, do the following steps: + +1. First import your schema into your Dgraph Cloud backend, using either the [Schema API](/admin/schema) or via [the Schema Page](https://cloud.dgraph.io/_/schema). +2. Log into Dgraph Cloud, and find your backend's `gRPC Endpoint` on the Settings page. This will look like `frozen-mango.grpc.us-west-1.aws.cloud.dgraph.io:443` + +{{% notice "note" %}} +The gRPC endpoint URL must have the string `.grpc.` added after the domain prefix. Without this change, Live Loader will not be able to find the endpoint. +{{% /notice %}} + +3. Run the live loader as follows: + + ``` + docker run -it --rm -v /path/to/g01.json.gz:/tmp/g01.json.gz dgraph/dgraph:v21.03-slash \ + dgraph live --slash_grpc_endpoint=:443 -f /tmp/g01.json.gz -t + ``` + +{{% notice "note" %}} +Running this via Docker requires you to use an unreleased tag (either `master` or `v21.03-slash`). +{{% /notice %}} diff --git a/content/dgraphcloud/admin/monitoring.md b/content/dgraphcloud/admin/monitoring.md new file mode 100644 index 00000000..0cbdd42c --- /dev/null +++ b/content/dgraphcloud/admin/monitoring.md @@ -0,0 +1,59 @@ ++++ +title = "Monitoring with Prometheus" +weight = 8 +[menu.main] + name = "Monitoring with Prometheus" + parent = "cloud-admin" ++++ + +Dgraph Cloud provides enterprises with real-time observability and high-fidelity telemetry of their instances with [Prometheus](https://prometheus.io/). Once enabled Dgraph exposes real-time values for **Dedicated** backends at any given instant via the `/prometheus` endpoint. You can also configure Grafana for real-time visualization and analysis thus allowing for in-depth visibility into the behavior, performance and health of your instances. + +{{% notice "note" %}} +Prometheus integration is only available to users of **Dedicated Instance** types and not **Free** or **Shared Instance**. +{{% /notice %}} + +### Enable Prometheus for your instance + +To enable Prometheus with your Dgraph Cloud instance: + +1. Login to Dgraph Cloud Dashboard, select **Settings** under the **Admin** subsection and then select **Modify Backend**. Alternately, you can also enable Prometheus while launching a new backend. + +2. For your existing **Dgraph Cloud Backend**, enable the **Prometheus** option under **Additional Settings**. Review and select one of the available configurations viz. 1C (1 vCPU 4GB RAM), 2C, 4C, or 8C. + +3. Review the estimated hourly cost which should include additional charges for enabling Prometheus. Click **Launch** to submit changes. + +![Enable Prometheus](/images/monitoring/enable_prometheus.png) + +### Configure your instance endpoint with Prometheus + +1. For all dedicated backends with Prometheus enabled, a new endpoint called `/prometheus` would be available. For example, a backend at URL https://sudomain.region.cloud-provider.cloud.dgraph.io/graphql would expose metrics at URL - https://sudomain.region.cloud-provider.cloud.dgraph.io/prometheus + +2. The `/prometheus` endpoint is protected with the **Admin API key**. Upon accessing the URL for this endpoint, you will be prompted to enter the key. More information on creating an Admin API key can be found [here](https://dgraph.io/docs/cloud/admin/authentication/). + + ![Enter Admin API key](/images/monitoring/api_token.png) + +3. Once you enter the Admin API token click **Submit** to launch the **Prometheus Dashboard**. + + ![Prometheus Dashboard](/images/monitoring/prometheus_dashboard.png) + +### Integrating with Grafana + +To visualize Prometheus metrics within the **Grafana Dashboard** for Dgraph Cloud, perform the following actions: + +1. Launch the Grafana Dashboard and follow the same steps to add a **Prometheus Datasource** to Grafana as described **[here](https://prometheus.io/docs/visualization/grafana/#creating-a-prometheus-data-source)** but with the following changes: + +2. Under the section **HTTP**, for the option **URL**, enter the URL for your Prometheus endpoint (Example - https://sudomain.region.cloud-provider.cloud.dgraph.io/prometheus). For the **Access** option select **Server (default)** from the dropdown menu. + +3. Lastly, under **Auth**, within the **Custom HTTP Headers** subsection, click **Add Header** and add a new **Header** called `X-Auth-Token`. Enter your Admin API key as its **Value**. The following image shows an example data source configuration. + + ![Grafana Config](/images/monitoring/grafana_config.png) + +4. Click **Save & Test** to save and test the new Prometheus data source. + +5. Create and populate your **Grafana Dashboard**. Select the **Prometheus Data Source** that was configured earlier and select the metrics to visualize (e.g. dgraph_memory_inuse_bytes, dgraph_alpha_health_status etc). + If correctly configured the metrics can be visualized as below: + + ![Grafana Config](/images/monitoring/grafana_dashboard.png) + +Your new monitoring and observability stack for Dgraph Cloud leveraging the Prometheus and Grafana solutions should now be ready for use. The same is useful to monitor your Dgraph backend efficiently, without the overhead of installing, maintaining, and scaling your own observability stack. + diff --git a/content/dgraphcloud/admin/overview.md b/content/dgraphcloud/admin/overview.md new file mode 100644 index 00000000..619db09c --- /dev/null +++ b/content/dgraphcloud/admin/overview.md @@ -0,0 +1,25 @@ ++++ +date = "2017-03-20T22:25:17+11:00" +title = "Overview" +weight = 1 +[menu.main] + parent = "cloud-admin" + name = "Overview" + identifier = "cloud-overview" ++++ + +Here is a guide to programmatically administering your Dgraph Cloud backend. + +Wherever possible, we have maintained compatibility with the corresponding Dgraph API, +with the additional step of requiring [authentication]({{< relref "authentication" >}}) via the `X-Auth-Token` header. + +{{% notice "note" %}} +Keep in mind that free Dgraph Cloud backends will be frozen automatically after 4 hours of inactivity. +{{% /notice %}} + +Please see the following topics: + +* [Authentication]({{< relref "authentication" >}}) will guide you in creating a API token. Since all admin APIs require an auth token, this is a good place to start. +* [Schema]({{< relref "schema" >}}) describes how to programmatically query and update your GraphQL schema. +* [Import and Exporting Data]({{< relref "import-export" >}}) is a guide for exporting your data from a Dgraph Cloud backend, and how to import it into another cluster +* [Dropping Data]({{< relref "drop-data" >}}) will guide you through dropping all data from your Dgraph Cloud backend. diff --git a/content/dgraphcloud/admin/schema-modes.md b/content/dgraphcloud/admin/schema-modes.md new file mode 100644 index 00000000..083b21d0 --- /dev/null +++ b/content/dgraphcloud/admin/schema-modes.md @@ -0,0 +1,82 @@ ++++ +title = "Switch Dgraph Cloud Schema Modes" +description = "Dgraph Cloud provides a variety of schema modes that let you configure how the underlying Dgraph Cloud instance responds to schema changes or mutation requests that seek to change data stored in your backend." +weight = 6 +[menu.main] + name = "Switch Schema Modes" + parent = "cloud-admin" ++++ + +Dgraph Cloud uses the following three schema modes, which control how the +underlying Dgraph database instance is configured: + +- [Read-Only mode](#read-only-mode) (*dedicated instances only*): In this mode, no + schema changes or mutations are allowed +- [Strict mode](#strict-mode): In this mode, only mutations on predicates that + are already present in the schema are allowed +- [Flexible mode](#flexible-mode) (*dedicated instances only*): In this mode, + there are no global restrictions on schemas and mutations; this mode also + provides access to advanced Dgraph features + +Each mode is pre-configured to provide simplicity and ease-of-use. By default, +your Dgraph Cloud schema will run in [Strict mode](#strict-mode). If you want +your dedicated instance to have the same behavior as a local Dgraph instance, +change your schema to [Flexible mode](#flexible-mode). + +### Read-Only mode + +In read-only mode, all mutations and attempts to alter the Cloud schema are +blocked. You can still access your data through read-only queries. + +### Strict mode + +Strict mode is the default mode on Dgraph Cloud, and the only mode available for +free and shared instances. In this mode, Dgraph Cloud enforces a [strict schema](https://dgraph.io/docs/deploy/dgraph-administration/#restricting-mutation-operations), only allowing mutations on +predicates already present in the schema. + +You can use GraphQL and DQL (formerly *GraphQL+-*) queries and mutations in this +mode, as described in the [advanced queries](/advanced-queries/) section. +However, all queries and mutations must be valid for the applied schema. + +{{% notice "note" %}} +In **Strict** mode, before executing a mutation on a predicate that doesn’t +exist in the schema, you need add that predicate to the schema. To add a predicate, +perform an [`alter` operation](https://dgraph.io/docs/clients/raw-http/#alter-the-database) +with that predicate and its schema type (*dedicated instances only*), or +[update your schema]({{< relref "schema" >}}) to include that predicate and +its schema type. +{{% /notice %}} + +### Flexible mode + +Flexible mode is suitable for users who are already familiar with Dgraph. +It removes global restrictions on schemas and mutations, and also +provides access to advanced Dgraph features like the following: + +* Directly altering the schema with the [`alter`](https://dgraph.io/docs/clients/raw-http/#alter-the-database) HTTP and GRPC endpoints +* Support for access control lists ([ACLs](https://dgraph.io/docs/enterprise-features/access-control-lists/)) + +## Switch schema modes with the Dgraph Cloud console + +To change your schema mode on a dedicated instance, go to the [settings page](https://cloud.dgraph.io/_/settings), +click the General tab, and then select a mode from the +**Schema Mode** list box. + +## Switch schema modes with the `/admin` endpoint + +{{% notice "tip" %}} +Dgraph Labs recommends using the Dgraph Cloud [settings page](https://cloud.dgraph.io/_/settings) +to change your dedicated instance's schema mode for most scenarios, instead of +directly modifying your schema. +{{% /notice %}} + +You can change the schema mode for your dedicated instance directly in the schema +using the `updateGQLSchema` mutation on the `/admin` HTTP and GRPC endpoints. To +learn more, see [Fetch and Update Your Schema]({{< relref "schema" >}}). + +To set your schema mode, configure `UpdateOption` to use one of the following +values in your schema: + +* To use Read Only mode, set `UpdateOption` to `readonly` +* To use Strict mode, set `UpdateOption` to `graphql` +* To use Flexible mode, set `UpdateOption` to `flexible` diff --git a/content/dgraphcloud/admin/schema.md b/content/dgraphcloud/admin/schema.md new file mode 100644 index 00000000..5fc02043 --- /dev/null +++ b/content/dgraphcloud/admin/schema.md @@ -0,0 +1,38 @@ ++++ +title = "Fetching and Updating Your Schema" +weight = 3 +[menu.main] + parent = "cloud-admin" ++++ + +Your GraphQL schema can be fetched and updated using the `/admin` endpoint of your cluster. As an example, if your GraphQL endpoint is `https://frozen-mango.us-west-2.aws.cloud.dgraph.io/graphql`, then the admin endpoint for schema will be at `https://frozen-mango.us-west-2.aws.cloud.dgraph.io/admin`. + +This endpoint works in a similar way to the [/admin](https://dgraph.io/docs/graphql/admin) endpoint of Dgraph, with the additional constraint of [requiring authentication](/admin/authentication). + +### Fetching the Current Schema + +It is possible to fetch your current schema using the `getGQLSchema` query on `/admin`. Below is a sample GraphQL query which will fetch this schema. + +```graphql +{ + getGQLSchema { + schema + } +} +``` + +### Setting a New Schema + +You can save a new schema using the `updateGQLSchema` mutation on `/admin`. Below is an example GraphQL body, with a variable called `sch` which must be passed in as a [variable](https://graphql.org/graphql-js/passing-arguments/) + +```graphql +mutation($sch: String!) { + updateGQLSchema(input: { set: { schema: $sch}}) + { + gqlSchema { + schema + generatedSchema + } + } +} +``` diff --git a/content/dgraphcloud/advanced-queries.md b/content/dgraphcloud/advanced-queries.md new file mode 100644 index 00000000..f617ad8f --- /dev/null +++ b/content/dgraphcloud/advanced-queries.md @@ -0,0 +1,199 @@ ++++ +title = "Advanced Queries with DQL" +weight = 3 +[menu.main] + parent = "cloud" ++++ + +*You can now [embed DQL queries inside your GraphQL schema](https://dgraph.io/docs/graphql/custom/graphqlpm), which is recommended for most use cases. The rest of this document covers how to connect to your Dgraph Cloud backend with existing Dgraph clients.* + +In addition to GraphQL support, Dgraph Cloud also supports running advanced +queries using Dgraph Query Language (DQL) (previously named GraphQL+-). +DQL is based on GraphQL, but adds and removes features to better support graph +database operations. Advanced users can use DQL to send queries and mutations +to Dgraph Cloud's HTTP or gRPC endpoints using the Dgraph client libraries. +To learn more about the Dgraph client libraries, see the +[client library documentation](https://dgraph.io/docs/clients/). To learn more +about DQL, see [DQL Fundamentals](https://dgraph.io/docs/query-language/graphql-fundamentals/).. + +If you are getting started with Dgraph Cloud, you should probably start out by +using Dgraph's [GraphQL API](https://dgraph.io/docs/graphql/overview) instead. +Dgraph's GraphQL API lets you quickly use Dgraph Cloud before moving on to the +advanced features available using DQL. + +{{% notice "Note" %}} +Dgraph Cloud's [schema modes](/admin/schema-modes/) let +you configure whether and how schema changes are allowed. To alter your schema +using the `/alter` HTTP and GRPC endpoints, you'll need to use **Flexible Mode**. +{{% /notice %}} + +## Authentication + +The APIs documented here all require an API token for access. To learn how to +create an API token, please see [Authentication](/admin/authentication). + +### HTTP + +You can query your backend with DQL using your cluster's `/query` endpoint. As +an example, if your GraphQL endpoint is `https://frozen-mango.us-west-2.aws.cloud.dgraph.io/graphql`, +then the admin endpoint for the schema is `https://frozen-mango.us-west-2.aws.cloud.dgraph.io/query`. + +You can also access the [`/mutate`](https://dgraph.io/docs/mutations/) and +`/commit` endpoints. + +For example, let's say you have the following GraphQL schema: +```graphql +type Person { + name: String! @search(by: [fulltext]) + age: Int + country: String +} +``` + +Here is an example of a cURL command with the `/mutate` endpoint: + +``` +curl -H "Content-Type: application/rdf" -H "x-auth-token: " -X POST "/mutate?commitNow=true" -d $' +{ + set { + _:x "John" . + _:x "30" . + _:x "US" . + } +}' +``` + +Here is an example of a cURL command with the `/query` endpoint: + +``` +curl -H "Content-Type: application/dql" -H "x-auth-token: " -XPOST "/query" -d '{ + queryPerson(func: type(Person)) { + Person.name + Person.age + Person.country + } +}' +``` + +### gRPC + +Dgraph Cloud is compatible with most existing Dgraph clients. You can use the +helper methods from each library to connect to your backend, passing in a Dgraph +Cloud endpoint and an API token. + +Here is an example which uses the [pydgraph client](https://github.com/dgraph-io/pydgraph) to make gRPC requests. + +```python +import pydgraph + +client_stub = pydgraph.DgraphClientStub.from_slash_endpoint("https://frozen-mango.eu-central-1.aws.cloud.dgraph.io/graphql", "") +client = pydgraph.DgraphClient(client_stub) +``` + +Here is an example of a mutation using the `pydgraph` client: +```python +mut = { + "Person.name": "John Doe", + "Person.age": "32", + "Person.country": "US" +} + +txn = client.txn() +try: + res = txn.mutate(set_obj=mut) +finally: + txn.discard() +``` + +Here is an example of a query using the `pydgraph` client: +```python +query = """ +{ + queryPerson(func: type(Person)) { + Person.name + Person.age + Person.country + } +}""" +txn = client.txn() +try: + res = txn.query(query) + ppl = json.loads(res.json) + print(ppl) +finally: + txn.discard() +``` + +#### Connecting from Dgraph Clients + +Below are snippets to connect to your Dgraph Cloud backend from various Dgraph +clients. + +**Python** +```python +import pydgraph + +client_stub = pydgraph.DgraphClientStub.from_slash_endpoint("https://frozen-mango.eu-central-1.aws.cloud.dgraph.io/graphql", "") +client = pydgraph.DgraphClient(client_stub) +``` + +**JavaScript** +```javascript +const dgraph = require("dgraph-js"); + +const clientStub = dgraph.clientStubFromSlashGraphQLEndpoint( + "https://frozen-mango.eu-central-1.aws.cloud.dgraph.io/graphql", + "" +); +const dgraphClient = new dgraph.DgraphClient(clientStub); +``` + +**Go** +```golang +// This example uses dgo +conn, err := dgo.DialSlashEndpoint("https://frozen-mango.eu-central-1.aws.cloud.dgraph.io/graphql", "") +if err != nil { + log.Fatal(err) +} +defer conn.Close() +dgraphClient := dgo.NewDgraphClient(api.NewDgraphClient(conn)) +``` + +**Java** +```java +// This example uses dgraph4j +DgraphStub stub = DgraphClient.clientStubFromSlashEndpoint("https://frozen-mango.eu-central-1.aws.cloud.dgraph.io/graphql", ""); +DgraphClient dgraphClient = new DgraphClient(stub); +``` + +**C# / .NET** +```c# +var client = new DgraphClient(SlashChannel.Create("frozen-mango.eu-central-1.aws.cloud.dgraph.io:443", "")); +``` + +### Visualizing your Graph with Ratel + +You can use Ratel to visualize your Dgraph Cloud backend with DQL. You can host +Ratel yourself, or you can use Ratel online at [Dgraph Play](https://play.dgraph.io/?latest#connection). + +To configure Ratel: + +1. Click the Dgraph logo in the top left to bring up the connection screen (by default, it has the caption: play.dgraph.io) +2. Enter your backend's host in the Dgraph Server URL field. This is obtained by removing `/graphql` from the end of your `/graphql` endpoint URL. For example, if your `/graphql` endpoint is `https://frozen-mango.us-west-2.aws.cloud.dgraph.io/graphql`, then the host for Ratel is `https://frozen-mango.us-west-2.aws.cloud.dgraph.io` +3. Click the **Connect** button. You should see a green check mark next to the word **Connected**. +4. Click on the **Extra Settings** tab, and then enter your API token into the + **API Key** field. To create a new API token, see [Authentication](/admin/authentication). +5. Click on the **Continue** button. + +You can now run queries and mutations using Ratel, and see visualizations of +your data. + +Ratel has certain limitations; it doesn't support backups, modifying ACL or +attempting to remove nodes from the cluster. + +### Switching Schema Modes + +If you want to use DQL as your primary mode of interaction with the Dgraph Cloud +backend (instead of primarily using the GraphQL API), you can switch your +backend to flexible mode. To learn more, see +[Schema Modes](/admin/schema-modes). diff --git a/content/dgraphcloud/cloud-api/_index.md b/content/dgraphcloud/cloud-api/_index.md new file mode 100644 index 00000000..79fa9f1b --- /dev/null +++ b/content/dgraphcloud/cloud-api/_index.md @@ -0,0 +1,7 @@ ++++ +title = "Dgraph Cloud API" +weight = 15 +[menu.main] + identifier = "cloud" + parent = "cloud" ++++ diff --git a/content/dgraphcloud/cloud-api/authentication.md b/content/dgraphcloud/cloud-api/authentication.md new file mode 100644 index 00000000..96022ff4 --- /dev/null +++ b/content/dgraphcloud/cloud-api/authentication.md @@ -0,0 +1,69 @@ ++++ +title = "Authentication" +weight = 2 +[menu.main] + parent = "cloud-api" + identifier = "api-authentication" ++++ + +## Login + +Login will generate a JWT token that can be used to access other Dgraph Cloud +APIs. + +This API requires an email address and password. If you have signed up with a +social media provider, you may create a new password by selecting +`Forgot Password` on the login page. + +### Cloud Endpoint + +``` +https://cerebro.cloud.dgraph.io/graphql +``` + +### API Command + +```graphql +query Login($email: String!, $password: String!) { + login(email: $email, password: $password) { + token + } +} +``` + +**Arguments** + +- `email`: your email address +- `password`: your password + +### Example + +Below is an example request and response. The token below must be passed to all +future API calls as a bearer token in the `Authorization` header. + +{{% tabs %}} {{< tab "request" >}} +```bash +curl 'https://cerebro.cloud.dgraph.io/graphql' \ + -H 'Content-Type: application/json' \ + --data-binary '{"query":"query Login($email: String!, $password: String!) {\n login(email: $email, password: $password) { \n token\n }\n}","variables":{"email":"","password":""}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "login": { + "token": "" + } + } +} +``` + +{{% /tab %}} {{% /tabs %}} + +## Using the authentication token + +The token returned from the login API must be passed to all future API calls as +a bearer token in the `Authorization` header. diff --git a/content/dgraphcloud/cloud-api/backend.md b/content/dgraphcloud/cloud-api/backend.md new file mode 100644 index 00000000..c32148df --- /dev/null +++ b/content/dgraphcloud/cloud-api/backend.md @@ -0,0 +1,476 @@ ++++ +title = "Backend" +weight = 3 +[menu.main] + parent = "cloud-api" + identifier = "backend" ++++ + +## List Backends + +List backends that you have access to. + +{{% notice "note" %}} +This API requires authentication, please see [Authentication]({{< relref "authentication" >}}) for instructions on issuing and passing a JWT token to the API. +{{% /notice %}} + +### Cloud Endpoint + +``` +https://cerebro.cloud.dgraph.io/graphql +``` + +### API Command + +```graphql +{ + deployments { + uid + name + zone + url + owner + jwtToken + deploymentMode + deploymentType + lambdaScript + } +} +``` + +### Example + +* `` is the JWT returned from [Authentication]({{< relref "authentication" >}}). +* `` is a base64 string that will be non-empty if you have saved [Lambdas]({{< relref "lambda" >}}) on your backend + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +CEREBRO_JWT="" + +curl 'https://cerebro.cloud.dgraph.io/graphql' \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${CEREBRO_JWT}" \ + --data-binary '{"query":"{\n deployments {\n uid\n name\n zone\n url\n owner\n jwtToken\n deploymentMode\n deploymentType\n lambdaScript\n }\n}","variables":{}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "deployments": [ + { + "uid": "0xf0ffe9", + "name": "testing", + "zone": "us-east-1", + "url": "polished-violet.us-east-1.aws.cloud.dgraph.io", + "owner": "486c69b4-e09b-48f9-a28a-86314fe232cd", + "jwtToken": "", + "deploymentMode": "graphql", + "deploymentType": "free", + "lambdaScript": "" + } + ] + } +} +``` +{{% /tab %}} {{% /tabs %}} + +{{% notice "note" %}} +For any `/admin` or `/admin/slash` requests to `https://`, you **must use the `` returned above in the `X-Auth-Token` header.** The Cerebro JWT is only used in the `Authorization` header for requests to `https://cerebro.cloud.dgraph.io/graphql`. +{{% /notice %}} + +## Deploy Backend + +Launch a new backend. + +{{% notice "note" %}} +This API requires authentication, please see [Authentication]({{< relref "authentication" >}}) for instructions on issuing and passing a JWT to the API. +{{% /notice %}} + +### Cloud Endpoint + +``` +https://cerebro.cloud.dgraph.io/graphql +``` + +### API Command + +```graphql +mutation CreateDeployment($newDeployment: NewDeployment!) { + createDeployment(input: $newDeployment) { + uid + name + url + jwtToken + } +} +``` + +**Arguments** + +* `newDeployment`: parameter object for new deployment +* `newDeployment.name`: name of the deployment +* `newDeployment.zone`: region to launch +* `newDeployment.deploymentType`: type of deployment `(free|shared|dedicated)` + + +### Example + +* `` is the JWT returned from [Authentication]({{< relref "authentication" >}}). + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +CEREBRO_JWT="" + +curl 'https://cerebro.cloud.dgraph.io/graphql' \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${CEREBRO_JWT}" \ + --data-binary '{"query":"mutation CreateDeployment($deployment: NewDeployment!) {\n createDeployment(input: $deployment) {\n uid\n name\n url\n jwtToken\n }\n}","variables":{"deployment":{"name":"My New Deployment","zone":"us-east-1","deploymentType":"dedicated"}}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "createDeployment": { + "uid": "0x42", + "name": "My New Deployment", + "url": "my-new-deployment.us-east-1.aws.cloud.dgraph.io", + "jwtToken": "" + } + } +} +``` +{{% /tab %}} {{% /tabs %}} + +## Update Backend + +Update backend. + +{{% notice "note" %}} +This API requires authentication, please see [Authentication]({{< relref "authentication" >}}) for instructions on issuing and passing a JWT token to the API. +{{% /notice %}} + +### Cloud Endpoint + +``` +https://cerebro.cloud.dgraph.io/graphql +``` + +### API Command + +```graphql +mutation UpdateDeployment($updateDeploymentInput: UpdateDeploymentInput!) { + updateDeployment(input: $updateDeploymentInput) +} +``` + +**Arguments** + +* `updateDeploymentInput`: parameter object for update deployment +* `updateDeploymentInput.uid` (required): deployment `uid` + +### Example + +* `` is the JWT returned from [Authentication]({{< relref "authentication" >}}). +* `` is the UID returned from [List Backends](#list-backends). + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +CEREBRO_JWT="" + +curl 'https://cerebro.cloud.dgraph.io/graphql' \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${CEREBRO_JWT}" \ + --data-binary '{"query":"mutation UpdateDeployment($dep: UpdateDeploymentInput!) {\n updateDeployment(input: $dep)\n}","variables":{"dep":{"uid":"","name":"My Deployment!"}}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "updateDeployment": "Successfully Updated the backend" + } +} +``` +{{% /tab %}} {{% /tabs %}} + +## Destroy Backend + +Destroy (i.e., delete) a backend by id. + +{{% notice "note" %}} +This API requires authentication, please see [Authentication]({{< relref "authentication" >}}) for instructions on issuing and passing a JWT token to the API. +{{% /notice %}} + +### Cloud Endpoint + +``` +https://cerebro.cloud.dgraph.io/graphql +``` + +### API Command + +```graphql +mutation DeleteDeployment($deploymentID: String!) { + deleteDeployment(deploymentID: $deploymentID) +} +``` + +**Arguments** + +* `deploymentID` (required): deployment `uid` returned from a [List Backends](#list-backends) request + +### Example + +* `` is the JWT returned from [Authentication]({{< relref "authentication" >}}). + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +CEREBRO_JWT="" + +curl 'https://cerebro.cloud.dgraph.io/graphql' \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${CEREBRO_JWT}" \ + --data-binary '{"query":"mutation DeleteDeployment($deploymentUid: String!) {\n deleteDeployment(deploymentID: $deploymentUid)\n}","variables":{"deploymentUid":""}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +``` +{ + "data": { + "deleteDeployment": "Successfully deleted the Deployment" + } +} +``` +{{% /tab %}} {{% /tabs %}} + +## Restore Backends + +Restore into a backend by source backend ID. + +### Cloud Endpoint + +```bash +https://${DEPLOYMENT_URL}/admin/slash +``` + +### API Command + +```graphql +mutation($uid: String!, $backupFolder: String, $backupNum: Int) { + restore(uid: $uid, backupFolder: $backupFolder, backupNum: $backupNum) { + response { + code + message + restoreId + }, errors { + message + } + } +} +``` + +**Arguments** + +* `uid` (required): the deployment `uid` from List Backends +* `backupFolder` (required): TODO +* `backupNum` (required): TODO + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +DEPLOYMENT_URL="polished-violet.us-east-1.aws.cloud.dgraph.io" +DEPLOYMENT_JWT="" + +curl "https://${DEPLOYMENT_URL}/admin/slash" \ + -H 'Content-Type: application/json' \ + -H "X-Auth-Token: ${DEPLOYMENT_JWT}" \ + --data-binary '{"query":"mutation($uid: String!, $backupFolder: String, $backupNum: Int) {\n restore(uid: $uid, backupFolder: $backupFolder, backupNum: $backupNum) {\n response {\n code\n message\n restoreId\n }, errors {\n message\n }\n}\n}","variables":{"uid":"","backupFolder":"","backupNum":}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "restore": { + "errors": null, + "response": { + "code": "Success", + "message": "Restore operation started.", + "restoreId": 1 + } + } + } +} +``` +{{% /tab %}} {{% /tabs %}} + +## Restore Backend Status + +Retrieve the status of a restore operation. + +### Cloud Endpoint + +```bash +https://${DEPLOYMENT_URL}/admin/slash +``` + +### API Command + +```graphql +query($restoreId: Int!) { + restoreStatus(restoreId: $restoreId) { + response {status errors} + } +} +``` + +**Arguments** + +* `restoreId` (required): the id of the restore operation returned from [Restore Backends](#restore-backends) request + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +DEPLOYMENT_URL="polished-violet.us-east-1.aws.cloud.dgraph.io" +DEPLOYMENT_JWT="" + +curl "https://${DEPLOYMENT_URL}/admin/slash" \ + -H 'Content-Type: application/json' \ + -H "X-Auth-Token: ${DEPLOYMENT_JWT}" \ + --data-binary '{"query":"query($restoreId: Int!) {\n restoreStatus(restoreId: $restoreId) {\n response {status errors}\n}\n}","variables":{"restoreId":1}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "restoreStatus": { + "response": { + "errors": [], + "status": "OK" + } + } + } +} +``` +{{% /tab %}} {{% /tabs %}} + +## Drop + +Drop (i.e., delete) all data in your backend. + +### Cloud Endpoint + +```bash +https://${DEPLOYMENT_URL}/admin/slash +``` + +### API Command + +#### Drop Data + +```graphql +mutation { + dropData(allData: true) { + response { code message } + } +} +``` + +#### Drop Schema + +```graphql +mutation { + dropData(allDataAndSchema: true) { + response { code message } + } +} +``` + +#### Drop Types + +```graphql +mutation($types: [String!]) { + dropData(types: $types) { + response { code message } + } +} +``` + +**Arguments** + +* `types`: string array containing type Names + +#### Drop Fields + +```graphql +mutation($fields: [String!]) { + dropData(fields: $fields) { + response { code message } + } +} +``` + +**Arguments** + +* `fields`: string array containing field Names + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +DEPLOYMENT_URL="polished-violet.us-east-1.aws.cloud.dgraph.io" +DEPLOYMENT_JWT="" + +curl "https://${DEPLOYMENT_URL}/admin/slash" \ + -H 'Content-Type: application/json' \ + -H "X-Auth-Token: ${DEPLOYMENT_JWT}" \ + --data-binary '{"query":"mutation {\n dropData(allDataAndSchema: true) {\n response { code message }\n}\n}","variables":{}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "dropData": { + "response": { + "code": "Success", + "message": "Done" + } + } + } +} +``` +{{% /tab %}} {{% /tabs %}} diff --git a/content/dgraphcloud/cloud-api/backup.md b/content/dgraphcloud/cloud-api/backup.md new file mode 100644 index 00000000..cf985692 --- /dev/null +++ b/content/dgraphcloud/cloud-api/backup.md @@ -0,0 +1,178 @@ ++++ +title = "Backup" +weight = 3 +[menu.main] + parent = "cloud-api" + identifier = "backup" ++++ + +{{% notice "note" %}} +Backup feature is only available for Dedicated Instances. This feature is not available for the Free and Shared Instances. +{{% /notice %}} + +## Periodic Backups + +Periodic Backups are created at a given schedule that by default is: +- Full Backup every week +- Incremental Backups every 4 hours + +You can trigger the Backup on-demand directelly from your Dgraph Cloud Dashboard, simply go to Admin>Setting>Backups and click on "Create Backup" button on the top left. + +In case you would like to change your default Backup schedule please contact us and we will be happy to set you up. + +## List Backups + +List all backups of the current backend. + +### Cloud Endpoint + +```bash +https://${DEPLOYMENT_URL}/admin/slash +``` + +### API Command + +```graphql +query { + listBackups { + response { + type + backupNum + folder + timestamp + }, errors { + message + } + } +} +``` + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +DEPLOYMENT_URL="polished-violet.us-east-1.aws.cloud.dgraph.io" +DEPLOYMENT_JWT="" + +curl "https://${DEPLOYMENT_URL}/admin/slash" \ + -H 'Content-Type: application/json' \ + -H "X-Auth-Token: ${DEPLOYMENT_JWT}" \ + --data-binary '{"query":"{\n listBackups {\n response {\n type\n backupNum\n folder\n timestamp\n }, errors {\n message\n }\n} \n}","variables":{}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "listBackups": { + "errors": [], + "response": [ + [ + { + "backupNum": 1, + "folder": "2021-15", + "timestamp": "2021-04-15T18:00:58+0000", + "type": "full" + }, + { + "backupNum": 2, + "folder": "2021-15", + "timestamp": "2021-04-15T18:04:29+0000", + "type": "incremental" + } + ] + ] + } + } +} +``` +{{% /tab %}} {{% /tabs %}} + +## Export Data + +Export data from your backend. + +### Cloud Endpoint + +```bash +https://${DEPLOYMENT_URL}/admin/slash +``` + +### API Command + +```graphql +mutation { + export { + signedUrls + } +} +``` + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +DEPLOYMENT_URL="polished-violet.us-east-1.aws.cloud.dgraph.io" +DEPLOYMENT_JWT="" + +curl "https://${DEPLOYMENT_URL}/admin/slash" \ + -H 'Content-Type: application/json' \ + -H "X-Auth-Token: ${DEPLOYMENT_JWT}" \ + --data-binary '{"query":"mutation {\n export {\n signedUrls\n }\n }","variables":{}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "export": { + "signedUrls": [ + "", + "", + "" + ] + } + } +} +``` +{{% /tab %}} {{% /tabs %}} + +## Import Data + +Import your data back using Dgraph [Live Loader]({{< relref "import-export.md#importing-data-with-live-loader" >}}) (requires Docker). + +### Shell Command + +Live loader command (via Docker): + +```sh +docker run -it --rm -v /tmp/file:/tmp/g01.json.gz dgraph/dgraph:v21.03-slash \ + dgraph live --slash_grpc_endpoint=${DEPLOYMENT_URL} -f /tmp/g01.json.gz -t ${DEPLOYMENT_JWT} +``` + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +DEPLOYMENT_URL="lively-dream.grpc.us-east-1.aws.cloud.dgraph.io" +DEPLOYMENT_JWT="" + +docker run -it --rm -v /users/dgraph/downloads:/tmp dgraph/dgraph:v21.03-slash \ + dgraph live --slash_grpc_endpoint=${DEPLOYMENT_URL}:443 -f /tmp/1million.rdf.gz -t ${DEPLOYMENT_JWT} +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +``` +{{% /tab %}} {{% /tabs %}} diff --git a/content/dgraphcloud/cloud-api/lambda.md b/content/dgraphcloud/cloud-api/lambda.md new file mode 100644 index 00000000..e5f961e2 --- /dev/null +++ b/content/dgraphcloud/cloud-api/lambda.md @@ -0,0 +1,224 @@ ++++ +title = "Lambda" +weight = 3 +[menu.main] + parent = "cloud-api" + identifier = "lambda" ++++ + +# Introduction + +For Shared and Free backends, a Dgraph lambda script is uniquely identified by a deployment id associated with the backend. You can identify your backend and the associated deployment id by using the [List Backends API](/cloud-api/backend#list-backends). In case of a Dedicated, and multi-tenant backend, an additional key, the tenant id is also required to uniquely identify a lambda script. This tenant id key is ignored when used in the context of Shared and Free backends. + +As a first step, you will need to identify your backend. + +## List Deployment and Get Lambda Script +Please use the [List Backends API](/cloud-api/backend#list-backends) to identify your backend, as well as get the lambda script deployed. In order to list the backends, you will need to pass a Bearer token as an `Authorization` header. This token is generated by logging in via the [Login query](/cloud-api/authentication#authentication) first. + +### Cloud Endpoint + +``` +https://cerebro.cloud.dgraph.io/graphql +``` +### API Command + +```graphql +query{ + deployments { + uid + name + zone + subdomain + url + tenantID + lambdaScript + } +} +``` + +**Arguments** + +None + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +CEREBRO_JWT="" + +curl "https://cerebro.cloud.dgraph.io/graphql" \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${CEREBRO_JWT}" \ + --data-binary '{"query":"query{\n deployments {\n uid\n name\n zone\n subdomain\n url\n tenantID\n lambdaScript\n }\n}","variables":{}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "deployments": [ + { + "uid": "0x6238", + "name": "OrderJourney", + "zone": "us-west-2", + "subdomain": "vacuous-wash", + "url": "vacuous-wash.us-west-2.aws.cloud.dgraph.io", + "tenantID": 107, + "lambdaScript": "Ly8gWW91IGNhbiB0eXBlL3Bhc3RlIHlvdXIgc2NyaXB0IGhlcmUKY29uc3QgTmFtZVJlc29sdmVyID0gKHtwYXJlbnQ6IHtuYW1lfX0pID0+IGBNeSBuYW1lIGlzICR7bmFtZX0uYAoKc2VsZi5hZGRHcmFwaFFMUmVzb2x2ZXJzKHsKICAgICJQZXJzb24ubmFtZSI6IE5hbWVSZXNvbHZlcgp9KQ==" + } + ] + } +} +``` +{{% /tab %}} {{% /tabs %}} + +The `uid` field in the response of the query is to be used as the deployment id. In the above example, the deployment id for the backend with name "OrderJourney" is "0x6238". The field `lambdaScript` contains the lambda script in the form of a Base64 encoded string. + +#### Decode the Base64 encoded `lambdaScript` +In order to decode the Base64 encoded string into the actual lambda code, please use the command as shown below. + +```bash +$ echo "Ly8gWW91IGNhbiB0eXBlL3Bhc3RlIHlvdXIgc2NyaXB0IGhlcmUKY29uc3QgTmFtZVJlc29sdmVyID0gKHtwYXJlbnQ6IHtuYW1lfX0pID0+IGBNeSBuYW1lIGlzICR7bmFtZX0uYAoKc2VsZi5hZGRHcmFwaFFMUmVzb2x2ZXJzKHsKICAgICJQZXJzb24ubmFtZSI6IE5hbWVSZXNvbHZlcgp9KQ==" | base64 -d +``` + +**Output** + +```js +// You can type/paste your script here +const NameResolver = ({parent: {name}}) => `My name is ${name}.` + +self.addGraphQLResolvers({ + "Person.name": NameResolver +}) +``` + +## Lambda Logs + +You can fetch the logs for your lambda by using the `getLambdaLogs` query. + +### Cloud Endpoint + +``` +https://cerebro.cloud.dgraph.io/graphql +``` + +### API Command + +```graphql +query GetLambdaLogs($lambdaLogsInput: LambdaLogsInput!) { + getLambdaLogs(input: $lambdaLogsInput) +} +``` + +**Arguments** + +* `lambdaLogsInput`: a LambdaLogsInput object +* `lambdaLogsInput.deploymentID`: the deployment UID returned from [List Backends](/cloud-api/backend#list-backends) +* `lambdaLogsInput.tenantID`: In case of a multi-tenant, and dedicated backend, you will need to pass the tenant Id as well +* `lambdaLogsInput.start`: start time +* `lambdaLogsInput.end`: end time + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +CEREBRO_JWT="" + +curl "https://cerebro.cloud.dgraph.io/graphql" \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${CEREBRO_JWT}" \ + --data-binary '{"query":"query GetLambdaLogs($input: LambdaLogsInput!) {\n getLambdaLogs(input: $input)\n}","variables":{"input":{"deploymentID":"0xf0ffe9"}}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "getLambdaLogs": [ + "2021-04-16 19:03:54.009209524 +0000 UTC Server Listening on port 8686!", + "2021-04-16 19:03:54.202216548 +0000 UTC Server Listening on port 8686!", + "2021-04-16 19:03:54.51171317 +0000 UTC Server Listening on port 8686!", + "2021-04-16 19:03:54.707496343 +0000 UTC Server Listening on port 8686!" + ] + } +} +``` +{{% /tab %}} {{% /tabs %}} + +## Update or Delete Lambda + +You can update or delete your lambda by using the `updateLambda` mutation. You will need to pass a deployment id to uniquely identify your lambda. In case your backend is multi-tenant, you will need to pass the tenant Id as well. + +In order to update your lambda, you would need to convert your lamdba script into a Base64 endcoded format and send it as the `lambdaScript` argument. +In order to delete your lambda, you can simply send in an empty string in the `lambdaScript` argument. + +### Cloud Endpoint + +``` +https://cerebro.cloud.dgraph.io/graphql +``` + +### API Command + +```graphql +mutation updateLambda($input: UpdateLambdaInput!){ + updateLambda(input: $input) +} +``` + +**Arguments** + +* `updateLambdaInput`: an UpdateLambdaInput object +* `updateLambdaInput.deploymentID`: the deployment UID returned from [List Backends](/cloud-api/backend#list-backends) +* `updateLambdaInput.tenantID`: the tenant ID in case your backend is a dedicated, and multi-tenant backend. In case you have any other type of backend, you can leave it as the default `0` value +* `updateLambdaInput.lambdaScript`: the base64-encoded Javascript string containing your [Lambda Resolver](https://dgraph.io/docs/graphql/lambda/overview/) + +### Example + +1) Create your [Lambda Resolver](https://dgraph.io/docs/graphql/lambda/overview/) script + +```js +//your lambda resolver +``` + +2) Base64 encode your script + +```bash +$ echo "//your lambda resolver" | base64 + +Ly95b3VyIGxhbWJkYSByZXNvbHZlcgo= +``` + +3) Send in a cURL request + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +CEREBRO_JWT="" + +curl "https://cerebro.cloud.dgraph.io/graphql" \ + -H 'Content-Type: application/json' \ + -H "Authorization: Bearer ${CEREBRO_JWT}" \ + --data-binary '{"query":"mutation updateLambda($input: UpdateLambdaInput!){\n updateLambda(input: $input)\n}","variables":{"input":{"deploymentID":"0x6238","tenantID":0,"lambdaScript":"Ly95b3VyIGxhbWJkYSByZXNvbHZlcgo="}}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "updateLambda": "Successfully added the lambda function" + } +} +``` +{{% /tab %}} {{% /tabs %}} diff --git a/content/dgraphcloud/cloud-api/overview.md b/content/dgraphcloud/cloud-api/overview.md new file mode 100644 index 00000000..c168b71c --- /dev/null +++ b/content/dgraphcloud/cloud-api/overview.md @@ -0,0 +1,44 @@ ++++ +date = "2017-03-20T22:25:17+11:00" +title = "Overview" +weight = 1 +[menu.main] + parent = "cloud-api" + identifier = "Overview" ++++ + +Dgraph Cloud now includes an API so you can programmatically launch and manage your Cloud backups. + +The majority of these APIs use `https://cerebro.cloud.dgraph.io/graphql` as the primary endpoint, and will require you to log in with a username and password. Please see [Authentication]({{< relref "authentication.md" >}}) for instructions on generating a JWT token. + +### Commands + +Please see the following topics: + +* [Authentication]({{< relref "authentication.md" >}}) describes how to authenticate with the Dgraph Cloud API. +* [Backend]({{< relref "backend.md" >}}) lists commands related to backend. +* [Backup]({{< relref "backup.md" >}}) lists commands related to backup. +* [Lambda]({{< relref "lambda.md" >}}) lists commands related to Lambda. +* [Schema]({{< relref "schema.md" >}}) lists commands related to schema. + +## Understanding Headers used across the APIs + +Dgraph Cloud has two layers of security: Dgraph Cloud Authentication and Dgraph Access Control Lists Authentication. The following section introduces the usage of the headers involved in the authentication process. These include the `Dg-Auth`, `X-Auth-Token`, `Authorization`, and `X-Dgraph-AccessToken` headers. + +### Dgraph Cloud Authentication +The `Dg-Auth` or `X-Auth-Token` headers are for Dgraph Cloud’s API key authentication (where you pass in any API key you would generate from the ["API Keys" tab](https://cloud.dgraph.io/_/settings?tab=api-keys) on the Settings page). The API key passed can be one of two kinds: Admin API key or Client API key. The tokens generated from the admin API grant access to the `/admin` or `/admin/slash` endpoints to perform schema alterations and similar operations. The tokens generated via the Client API key provides access to the `/graphql` endpoint to run GraphQL queries and mutations. + +Dgraph Cloud also offers the Dgraph Cloud API, hosted at [this endpoint](https://cerebro.cloud.dgraph.io/graphql), that helps to automate tasks such as deployment of a lambda. In order to use this API, users need to pass an `Authorization` header. In order to generate this header, the user must first [Authenticate]({{< relref "authentication" >}}) and generate a token. The token is then set in `Authorization` header as a Bearer token (e.g. `Bearer {token}`). + +{{% notice "note" %}} +The `Dg-Auth`, `X-Auth-Token` and the `Authorization` headers are relevant to all types of backends, including Free, Shared, and Dedicated Backends. +{{% /notice %}} + +### Dgraph Access Control Lists Authentication +The `X-Dgraph-AccessToken` header is used for accessing backends using Dgraph’s Access Control Lists or the Multitenancy feature. This lets you pass in an access JWT generated via a login mutation for a Dgraph user from the access control list permissions and/or log into a specific namespace with multi-tenancy. The Login mutation relevant for ACL is documented [here](https://dgraph.io/docs/enterprise-features/access-control-lists/#logging-in). + +If you’re using ACLs or multitenancy, then you’ll need to set the `X-Dgraph-AccessToken` with a JWT token to access your backend. + +{{% notice "note" %}} +The `X-Dgraph-AccessToken` header is relevant only for the Dedicated backends. Users with Free or Shared backends can ignore this header. +{{% /notice %}} diff --git a/content/dgraphcloud/cloud-api/schema.md b/content/dgraphcloud/cloud-api/schema.md new file mode 100644 index 00000000..a79aa8ee --- /dev/null +++ b/content/dgraphcloud/cloud-api/schema.md @@ -0,0 +1,150 @@ ++++ +title = "Schema" +weight = 2 +[menu.main] + parent = "cloud-api" + identifier = "schema" ++++ + +## Get Schema + +Fetch the schema from your backend. + +### Cloud Endpoint + +```bash +https://${DEPLOYMENT_URL}/admin +``` + +### API Command + +```graphql +{ + getGQLSchema { + schema + generatedSchema + } +} +``` + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +DEPLOYMENT_URL="polished-violet.us-east-1.aws.cloud.dgraph.io" +DEPLOYMENT_JWT="" + +curl "https://${DEPLOYMENT_URL}/admin" \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: ${DEPLOYMENT_JWT}" \ + --data-binary '{"query":"{\n getGQLSchema {\n schema\n generatedSchema\n }\n}","variables":{}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "getGQLSchema": { + "schema": "type Person { name: String! }", + "generatedSchema": "" + } + }, + "extensions": { + "tracing": { + "version": 1, + "startTime": "2021-04-15T19:58:33.412544782Z", + "endTime": "2021-04-15T19:58:33.412851891Z", + "duration": 307129, + "execution": { + "resolvers": [ + { + "path": ["getGQLSchema"], + "parentType": "Query", + "fieldName": "getGQLSchema", + "returnType": "GQLSchema", + "startOffset": 115909, + "duration": 159961, + "dgraph": [ + { + "label": "query", + "startOffset": 118110, + "duration": 53165 + } + ] + } + ] + } + } + } +} +``` +{{% /tab %}} {{% /tabs %}} + +## Update Schema + +Update the schema in your backend. + +### Cloud Endpoint + +```bash +https://${DEPLOYMENT_URL}/admin +``` + +### API Command + +```graphql +mutation($schema: String!) { + updateGQLSchema(input: { set: { schema: $schema } }) { + gqlSchema { + schema + } + } +} +``` + +**Arguments** + +- `schema`: your desired schema string in GraphQL format + +### Example + +{{% tabs %}} {{< tab "request" >}} +```bash +#!/usr/bin/env bash + +DEPLOYMENT_URL="polished-violet.us-east-1.aws.cloud.dgraph.io" +DEPLOYMENT_JWT="" + +curl "https://${DEPLOYMENT_URL}/admin" \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: ${DEPLOYMENT_JWT}" \ + --data-binary '{"query":"mutation($sch: String!) {\n updateGQLSchema(input: { set: { schema: $sch } })\n {\n gqlSchema {\n schema\n }\n }\n}","variables":{"sch": "type Person { name: String! }"}}' \ + --compressed +``` +{{< /tab >}} + +{{% tab "response" %}} +```json +{ + "data": { + "updateGQLSchema": { + "gqlSchema": { + "schema": "type Person { name: String! }" + } + } + }, + "extensions": { + "tracing": { + "version": 1, + "startTime": "2021-04-15T19:53:16.283198298Z", + "endTime": "2021-04-15T19:53:16.286478152Z", + "duration": 3279886 + } + } +} +``` +{{% /tab %}} {{% /tabs %}} diff --git a/content/dgraphcloud/cloud-multitenancy.md b/content/dgraphcloud/cloud-multitenancy.md new file mode 100644 index 00000000..ccd64678 --- /dev/null +++ b/content/dgraphcloud/cloud-multitenancy.md @@ -0,0 +1,63 @@ ++++ +title = "Multi-tenancy in Dgraph Cloud" +weight = 6 +[menu.main] + identifier = "cloud-multitenancy" + parent = "cloud" ++++ + +Multi-Tenancy in Dgraph cloud is a dedicated cluster feature. It is not supported in free/shared clusters. Multi-tenancy is built upon Access Control Lists (ACL), and enables multiple tenants to share a Dgraph cluster using unique namespaces. The tenants are logically separated, and their data lies in the same p directory. Each namespace has a group [guardian(admin)](https://dgraph.io/docs/enterprise-features/multitenancy/#guardians-of-the-galaxy), which has root access to that namespace. [Read more about Multi-Tenancy in Dgraph](https://dgraph.io/docs/enterprise-features/multitenancy/) + +### Enabling Multi-Tenancy in Dgraph Cloud +In order to enable multi-tenancy you need to do the following - + +1. **Enable ACL** + - If you are launching a dedicated cluster for the first time, you need to click on the checkbox for ACLs under `Additional Settings`. + - For existing dedicated cluster, you need to go to Settings>Modify Backend and click on the checkbox for ACLs under `Additional Settings`. Note - This restarts your backend hence causing some downtime. + ![ACL](/images/multitenancy/acl.png) + +2. **Create namespaces** + - Go to `Namespaces` page under `Admin` section on the sidebar to the left. + - Click on `Create New` button, enter the description of the namespace and click `Create`. + - You can view the created namespaces on the `Namespaces` page. + - Please note that Tenant 0 cannot be deleted. + ![namespacepage](/images/multitenancy/namespacepage.png) + +3. **Toggle namespaces** + - Now you should be able to see a select box next to selected backend select box on the navbar. + - You can switch between namespaces with the selection. + - Also, each namespace has its own Schema, ACLs & Lambdas. Also has its own view of Dgraph Studio, API Explorer, DQL Page. + - After switching namespaces, you can update view/update the namespace's schema and query/mutate as well. + ![namespaces](/images/multitenancy/namespaces.png) + +### Accessing namespaces via client +Namespaces are protected via ACLs. You need to create a user with username & password in the namespace. This can be done using `ACLs` page under `Admin` section on the sidebar to the left. + +**Example - we want to give all read access to a user for namespace** + +1. First, you should create an ACL group and select all predicates that you want to provision read access. + ![group](/images/multitenancy/group.png) +2. Next, create a user with access to the created group. While creating the user, you will be asked to provide with a username & password. Keep it handy. + ![user](/images/multitenancy/user.png) +3. You can go to the APIe Explorer and user the login mutation to fetch the API access token. Click on admin radio button at the top to query the admin endpoint. Use the mutation shown below to get the access token. + (Note - NamespaceID can be found on the namespace page) + ``` + mutation MyMutation { + login(namespace: 1, password: "password", userId: "userID") { + response { + accessJWT + refreshJWT + } + } + } + + ``` + + +4. You have the access token which you need to pass it in `X-Dgraph-AccessToken` header. +5. On client side you will need to use the above mutation programatically to generate the access token for your namespace. +6. If you are using a [dgraph client](https://dgraph.io/docs/clients/) you need to set the username & password and the client handles fetching the token & refresh logic for you. +Note - Most of the dgraph clients will have a special method to login to a specific namespace. + + + diff --git a/content/dgraphcloud/cloud-quick-start.md b/content/dgraphcloud/cloud-quick-start.md new file mode 100644 index 00000000..3184ba0a --- /dev/null +++ b/content/dgraphcloud/cloud-quick-start.md @@ -0,0 +1,271 @@ ++++ +title = "Dgraph Cloud Quick Start" +weight = 2 +[menu.main] + parent = "cloud" ++++ + +## Introduction + +Welcome to [Dgraph Cloud](https://dgraph.io/cloud), the world’s most advanced, hosted GraphQL backend. By now, you should have created your first deployment, and you're looking for a quick-start guide to test it out. Don't worry, in this document we got you covered. + +In this guide, we will create a database for a small app from the ground up using Dgraph Cloud. The easy steps you will learn in this tutorial are fundamental to using Dgraph Cloud, and mastering them will give you a better understanding of the powerful features available. + +### About the "to-do" App + +As our example app for this guide, we'll build a simple **"to-do" list** that supports adding and completing tasks for multiple users. +With the help of this small app, in this article you'll learn to: + +* [Create a Dgraph Cloud schema](#the-schema) +* [Apply GraphQL mutations and populate data](#graphql-mutations) +* [Add Authorization tokens](#authorization) +* [Test the app with a simple React UI](#testing-it-out-with-a-simple-ui) + +## The Schema + +The schema for our "to-do" app has only two types: `Tasks` and `Users`. The schema itself is pretty simple: it's a standard GraphQL schema, with a few additional directives \(such as `@search`\) which are specific to Dgraph Cloud. + +Let's define the Dgraph Cloud schema for our app: + +```graphql +type Task { + id: ID! + title: String! @search(by: [fulltext]) + completed: Boolean! @search + user: User! +} + +type User { + username: String! @id @search(by: [hash]) + name: String @search(by: [exact]) + tasks: [Task] @hasInverse(field: user) +} +``` + +The `Task` type has four fields: `id`, `title`, `completed` , and `user`. The `title` field has the `@search` directive on it, which tells Dgraph Cloud that this field can be used in full-text search queries. + +The `User` type has three fields: `username` (the email address of the user), `name`, and `tasks`. +The `username` field has the `@id` declaration, so this field is a unique identifier for objects of this type. +The `tasks` field associates each user with any number of `Task` objects. + +Let's paste the code into the [Schema tab](https://cloud.dgraph.io/_/schema) of Dgraph Cloud and click **Update Schema**: + +![Schema](/images/cloud/schema.png) + +Now we have a fully functional GraphQL API that allows us to create, query, and modify records of these two types. That's all; there's nothing else to do. It's there, serving GraphQL, ready to be used. + +## GraphQL mutations + +If you head over to the [API Explorer tab](https://cloud.dgraph.io/_/explorer), you'll see the **Docs** tab \(_Documentation Explorer_\), which tells you the queries and mutations that your new database supports. + +![Doc Explorer](/images/cloud/docexplorer.png) + +Next, let's go ahead and populate some data into our fresh database. + +### Populating the database + +Let's create a bunch of tasks, for a few of our users: + +```graphql +mutation AddTasks { + addTask(input: [ + {title: "Create a database", completed: false, user: {username: "your-email@example.com"}}, + {title: "Write A Schema", completed: false, user: {username: "your-email@example.com"}}, + {title: "Put Data In", completed: false, user: {username: "your-email@example.com"}}, + {title: "Complete Tasks with UI", completed: false, user: {username: "your-email@example.com"}}, + {title: "Profit!", completed: false, user: {username: "your-email@example.com"}}, + + {title: "Walking", completed: false, user: {username: "frodo@dgraph.io"}}, + {title: "More Walking", completed: false, user: {username: "frodo@dgraph.io"}}, + {title: "Discard Jewelery", completed: false, user: {username: "frodo@dgraph.io"}}, + + {title: "Meet Dad", completed: false, user: {username: "skywalker@dgraph.io"}}, + {title: "Dismantle Empire", completed: false, user: {username: "skywalker@dgraph.io"}} + ]) { + numUids + task { + title + user { + username + } + } + } +} +``` + +To populate the database, just head over the [API Explorer tab](https://cloud.dgraph.io/_/explorer), paste the code into the text area, and click on the **Execute Query** button: + +![API Explorer](/images/cloud/apiexplorer.png) + +### Querying the database + +Now that we have populated the database, let's query back the users and their tasks: + +```graphql +{ + queryUser { + username, + tasks { + title + } + } +} +``` + +As in the previous step, to execute the query, paste the code into the API Explorer, and hit the **Execute Query** button. + +The query's results are shown below. If you look carefully, you'll see that Dgraph figured out that users are unique \(by the `username`\), and it has returned a single record for each user. + +```graphql +{ + "data": { + "queryUser": [ + { + "username": "skywalker@dgraph.io", + "tasks": [ + { + "title": "Dismantle Empire" + }, + { + "title": "Meet Dad" + } + ] + }, + { + "username": "your-email@example.com", + "tasks": [ + { + "title": "Write A Schema" + }, + { + "title": "Profit!" + }, + { + "title": "Create a database" + }, + { + "title": "Put Data In" + }, + { + "title": "Complete Tasks with UI" + } + ] + }, + { + "username": "frodo@dgraph.io", + "tasks": [ + { + "title": "More Walking" + }, + { + "title": "Discard Jewelery" + }, + { + "title": "Walking" + } + ] + } + ] + }, + "extensions": { + "touched_uids": 40, + "tracing": { + "version": 1, + "startTime": "2020-08-15T12:59:14.577795285Z", + "endTime": "2020-08-15T12:59:14.580373297Z", + "duration": 2578026, + "execution": { + "resolvers": [ + { + "path": [ + "queryUser" + ], + "parentType": "Query", + "fieldName": "queryUser", + "returnType": "[User]", + "startOffset": 79480, + "duration": 2422504, + "dgraph": [ + { + "label": "query", + "startOffset": 125039, + "duration": 2291416 + } + ] + } + ] + } + }, + "queryCost": 1 + } +} +``` + +## Authorization + +Now that we have a working schema, let's update the original code and add some access authorization. We'll update the schema +so that users can only read tasks that they own (for example, this change would prevent Frodo from reading Luke's tasks). + +```graphql +type Task @auth( + query: { rule: """ + query($USER: String!) { + queryTask { + user(filter: { username: { eq: $USER } }) { + __typename + } + } + }"""}), { + id: ID! + title: String! @search(by: [fulltext]) + completed: Boolean! @search + user: User! +} + +type User { + username: String! @id @search(by: [hash]) + name: String @search(by: [exact]) + tasks: [Task] @hasInverse(field: user) +} + +# Dgraph.Authorization {"Header":"X-Auth-Token","Namespace":"https://dgraph.io/jwt/claims","Algo":"RS256","Audience":["Q1nC2kLsN6KQTX1UPdiBS6AhXRx9KwKl"],"VerificationKey":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAp/qw/KXH23bpOuhXzsDp\ndo9bGNqjd/OkH2LkCT0PKFx5i/lmvFXdd04fhJD0Z0K3pUe7xHcRn1pIbZWlhwOR\n7siaCh9L729OQjnrxU/aPOKwsD19YmLWwTeVpE7vhDejhnRaJ7Pz8GImX/z/Xo50\nPFSYdX28Fb3kssfo+cMBz2+7h1prKeLZyDk30ItK9MMj9S5y+UKHDwfLV/ZHSd8m\nVVEYRXUNNzLsxD2XaEC5ym2gCjEP1QTgago0iw3Bm2rNAMBePgo4OMgYjH9wOOuS\nVnyvHhZdwiZAd1XtJSehORzpErgDuV2ym3mw1G9mrDXDzX9vr5l5CuBc3BjnvcFC\nFwIDAQAB\n-----END PUBLIC KEY-----"} +``` + +Dgraph Cloud allows you to pass JSON Web Tokens (JWTs) with custom claims as a header, and will apply rules to control who can query or modify the data in your database. The `@auth` directive controls how these rules \(filters generated from the JWT token\) are applied. + +In our schema, we specify that one can only query tasks if the tasks' user has a `username` that matches `$USER`, a field in the JWT token. + +The Authorization magic comment specifies the header where the JWT comes from, the domain, and the key that signed it. In this example, the key is tied to our dev Auth0 account. More information on how this works is available in [this article](https://dgraph.io/docs/graphql/authorization/authorization-overview). + +To verify these access changes, let's try querying back the tasks: + +```graphql +{ + queryTask { + title + } +} +``` + +We should be getting an empty result this time, since we no longer have access to the tasks. + +## Testing it out with a simple UI + +To test our work, we've built the app's frontend with [React](https://reactjs.org/), so you can use it to close the tasks off. + +Let's head over to our sample React app, deployed at [https://relaxed-brahmagupta-f8020f.netlify.app/](https://relaxed-brahmagupta-f8020f.netlify.app/). When running the React app, remember to use the GraphQL Endpoint shown in your Dgraph Cloud [Dashboard](https://cloud.dgraph.io/_/dashboard). + +You can try creating an account with your email, or log in with the following user/password credentials: + +* `frodo@dgraph.io` / `password` +* `skywalker@dgraph.io` / `password` \(like the first Death Star, Luke wasn't big on security\) + +Once you have logged in, you should see something like: + +![React](/images/cloud/todos.png) + +Congratulations! You have completed the Dgraph Cloud quick-start guide, and you are ready to use the world’s most advanced, hosted GraphQL backend in your applications. + +## Next Steps + +To learn more about the Dgraph Cloud managed service, see [Administering your Backend](/admin/) and [Advanced Queries](/advanced-queries/). diff --git a/content/dgraphcloud/introduction.md b/content/dgraphcloud/introduction.md new file mode 100644 index 00000000..3227eccb --- /dev/null +++ b/content/dgraphcloud/introduction.md @@ -0,0 +1,88 @@ ++++ +title = "Dgraph Cloud Overview" +weight = 1 +[menu.main] + parent = "cloud" ++++ + +Dgraph Cloud, powered by Dgraph database, is a fully-managed GraphQL database +service that lets you focus on building apps, not managing infrastructure. Dgraph +Cloud is built from the ground up to support GraphQL, and uses a graph database +structure down to its lowest layers. So, it integrates seamlessly with your +existing ecosystem of GraphQL tools. + +Dgraph Cloud gives you the power of Dgraph database in a hosted environment, +providing the flexibility and performance of a horizontally-scalable and +distributed GraphQL database with a graph backend. With Dgraph Cloud, you +don’t need to configure and manage VMs, servers, firewalls, and HTTP endpoints +to power your modern apps and websites. + +Dgraph Cloud is available in several pricing tiers: + +* **Free**: This tier is suitable for hobbyist use and evaluation, but has significant bandwidth limitations. +* **Shared Instances** (formerly *Slash GraphQL*): Backends in this tier run on a shared server cluster to provide a graph database service at a low price. +* **Dedicated Instances**: Backends in this tier run on dedicated server clusters to meet the heavy workloads and other needs of enterprise customers. This tier also provides high availability and the option to run Dgraph in your own virtual private cloud (VPC) or bring your own Kubernetes (BYOK) environment. + +To learn more about pricing for each tier, see the [Dgraph Pricing Page](https://dgraph.io/pricing). +To learn more about Dgraph database, see [Dgraph Database Overview]{{< relref "dgraph-overview.md">}}). + +{{% notice "tip" %}} +You can check which Dgraph database release version is running on your Dgraph Cloud backend in [Dgraph Cloud Settings](https://cloud.dgraph.io/_/settings). +{{% /notice %}} + +## Key features + +| Feature | Notes | +| :------------- | :------------- | +| Production-ready | Dgraph Cloud is great for small app developers but is also built to meet the needs of your business as it grows with built-in authorization, encryption at rest, TLS, incremental backups, and more. | +| Scale and expand your app without rebuilding your backend | Dgraph Cloud stores and distributes data to optimize the execution of GraphQL traversals, joins, and retrievals. Dgraph natively parses and executes GraphQL, achieving great performance and the ability to scale horizontally up to terabytes of data. | +| A high-performance, graph-first database | Dgraph Cloud runs Dgraph database, which is built to support the needs of modern apps with lightning-fast queries at any depth. | +| Custom logic | Use JavaScript to add programmatic custom logic on the backend, adding power to your apps without sacrificing client-side performance. | +| Power your app with native GraphQL support | Dgraph is built for graph data, so you don’t need to configure and maintain a cumbersome GraphQL layer over a traditional relational database. | +| Evolve your schema without downtime | When it comes time to deploy a new schema, you can do that in seconds, not hours. | +| GraphQL-based authorization and management | GraphQL is used throughout Dgraph Cloud, so you don’t need to use another tool or learn another syntax to handle user authorization or database administration tasks such as schema changes and data exports. | +| Work with the Open Source ecosystem | Because Dgraph is open-source, your app relies on a codebase that you can contribute to, not an opaque “black box”. | + +## Architecture + +Dgraph Cloud runs Dgraph database in a fully-managed service, so you don't need +to manage servers or VM. Dgraph Cloud provides a truly distributed database that shards and +replicates data across cluster nodes, providing a scalable and production-ready +database solution for your app. + +Behind the scenes, Dgraph Cloud instances run as as clusters of Dgraph Zero and +Dgraph Alpha server nodes. + +* Dgraph Zero nodes control the cluster. This includes storing information + about the cluster and moving data between Dgraph Alpha nodes to re-balance + based on transactional workloads. +* Dgraph Alpha nodes serve data to clients, and also provide administrator + endpoints. + +To learn more about the Dgraph clusters that power Dgraph Cloud, see +[Understanding Dgraph Cluster]({{< relref "cluster-setup.md#understanding-dgraph-cluster" >}}). + +## Next steps + +To learn more about how Dgraph Cloud makes it easier to develop apps, create a +trial account and [try Dgraph Cloud](https://cloud.dgraph.io) for yourself. + +## Recommended Reading + +Please see the following topics to learn more about how to use Dgraph Cloud: + +- The [Quick Start]({{< relref "cloud-quick-start" >}}) will help you get started with a Dgraph Cloud Schema, starting with a multi tenant to-do app +- [Administering your Backend]({{< relref "admin/_index.md" >}}) covers topics such as how to programmatically set your schema, and import or export your data + - [Authentication]({{< relref "admin/authentication" >}}) will guide you in creating a API token. Since all admin APIs require an auth token, this is a good place to start. + - [Schema]({{< relref "admin/schema" >}}) describes how to programmatically query and update your GraphQL schema. + - [Import and Exporting Data]({{< relref "admin/import-export" >}}) is a guide for exporting your data from a Dgraph Cloud backend, and how to import it into another cluster + - [Dropping Data]({{< relref "admin/drop-data" >}}) will guide you through dropping all data from your Dgraph Cloud backend. + - [Switching Schema Modes]({{< relref "admin/schema-modes" >}}) will guide you through changing Dgraph Cloud schema mode. +- [Dgraph Cloud API]({{< relref "cloud-api/overview" >}}) Dgraph Cloud now includes a API so you can programmatically manage your backends +- [Schema]({{< relref "cloud-api/schema" >}}) lists commands related to schema. +- [Advanced Queries With DQL]({{< relref "advanced-queries" >}}) covers interacting with your database using the gRPC endpoint. + +You might also be interested in: + +- [Dgraph GraphQL Schema Reference]({{< relref "graphql/schema" >}}), which lists all the types and directives supported by Dgraph +- [Dgraph GraphQL API Reference]({{< relref "graphql/api" >}}), which serves as a guide to using your new `/graphql` endpoint diff --git a/content/dgraphcloud/migrating-from-hosted-dgraph.md b/content/dgraphcloud/migrating-from-hosted-dgraph.md new file mode 100644 index 00000000..cd4504c9 --- /dev/null +++ b/content/dgraphcloud/migrating-from-hosted-dgraph.md @@ -0,0 +1,15 @@ ++++ +title = "Migrating from Self-Managed Dgraph" +weight = 7 +[menu.main] + parent = "cloud" ++++ + +Dgraph Cloud is compatible with the majority of Dgraph features, so you can easily +migrate your existing Dgraph-powered app over to Dgraph Cloud. + +### To migrate data from self-managed Dgraph to Dgraph Cloud + +1. Create a new backend. You can do this using the Dgraph Cloud interface. +2. (optional) Switch your backend to [flexible mode](/admin/schema-modes#flexible-mode). +3. Connect to your backend with your favorite client. To learn more, see [Connecting from Dgraph Clients](/advanced-queries#connecting-from-dgraph-clients). diff --git a/content/dgraphcloud/provision-backend.md b/content/dgraphcloud/provision-backend.md index 9c40bf0c..a828ce45 100644 --- a/content/dgraphcloud/provision-backend.md +++ b/content/dgraphcloud/provision-backend.md @@ -4,7 +4,7 @@ date = "2023-02-14T22:25:17+11:00" title = "Provision a backend" weight = 1 [menu.main] - parent = "dgraphcloud" + parent = "cloud" +++ ### Before you begin diff --git a/content/dgraphcloud/security.md b/content/dgraphcloud/security.md new file mode 100644 index 00000000..0bbf15a2 --- /dev/null +++ b/content/dgraphcloud/security.md @@ -0,0 +1,133 @@ ++++ +title = "Securing Your GraphQL endpoint" +weight = 6 +[menu.main] + parent = "cloud" ++++ + +Here are a few tips for securing your Dgraph Cloud Backend + +### Allowing Anonymous Access to your GraphQL Endpoint + +To help secure your GraphQL API, Dgraph Cloud allows you to choose which GraphQL operations are available to end clients. + +You can visit the [access tab on the schema page](https://cloud.dgraph.io/_/schema) and choose the operations that you want to allow/deny for anonymous users. + +With Anonymous Access turned off, all GraphQL operations are restricted unless the client provides a valid [API Key](/admin/authentication). With Anonymous Access turned on (Default configuration), you will have a button to "Edit Permissions" + +In Edit Permissions, you will find options to turn on/off Anonymous Access to Lambda functions, custom Queries, and custom Mutations. For every Type defined in your GraphQL schema, Edit Permissions will show check boxes to enable Anonymous Access to Read and Write. Checking Read will allow the anonymous end clients to access the `get` and `query` query operations. Checking Write will allow anonymous end clients to access the `add`, `update`, and `delete` mutation operations. + +By default all operations are accessible to anonymous clients. However, this behavior will change in the near future. When this behavior is changed, it will apply only to newly created backends. Existing backends will remain unaffected by this future change. + +Anonymous Access works as an access control security one level above the [GraphQL `@auth` Directive](https://dgraph.io/docs/graphql/authorization/directive/). When you block anonymous access to your backend, the GraphQL requests from the client will not go through to the Dgraph database. When Anonymous Access is blocked, the GraphQL Auth Rules are not evaluated against the database. + +Anonymous Access granted on level types only applies to the parent type operations and is not meant to be a way to secure all data of that type. It is still possible to read/write data of a Type that has been set with no read/write permissions if other types are granted read/write access to anonymous clients. + +Consider the following Schema: + +```graphql +type User { + id: ID + name: String! + posts: [Post] @hasInverse(field: "author") +} +type Post { + id: ID + title: String! + author: User +} +``` + +If the Anonymous Access was granted Read and Write for Post but not granted Read and Write for User, it would be possible still to perform the following operations: + +```graphql +mutation addPost { + addPost(input: [{ + title: "New Post Title" @search(by: [hash]) + author: { name: "New User Name" } # creates a new User node. + }]) { + numUids + } +} +mutation removeAuthor { + updatePost(input: { + filter: { title: { eq: "New Post Title" } } + remove: { author: null } # does not delete the User node itself, just the linked reference. + }) { + numUids + } +} +mutation addAuthor { + updatePost(input: { + filter: { title: { eq: "New Post Title" } } + set: { author: { name: "Another New User Name" } } # creates a new User node. + }) { + numUids + } +} +query queryPost { + queryPost { + id + title + author { # reads the User node. + id + name + } + } +} +``` + +The Client and Admin API Keys that you generate on the [settings page](https://cloud.dgraph.io/_/settings) will have full access to all the GraphQL operations. To use an API key to authenticate a client, pass the API key in the `DG-Auth` header while sending your requests to the `/graphql` endpoint of your backend. + +Example passing headers using Apollo Client in React: + +```Javascript +import { ApolloClient, createHttpLink, InMemoryCache } from '@apollo/client'; +import { setContext } from '@apollo/client/link/context'; + +const httpLink = createHttpLink({ + uri: '/graphql', +}); + +const authLink = setContext((_, { headers }) => { + // get the authentication token from local storage if it exists + const token = localStorage.getItem('token'); // JWT token + // get the API key from local storage if it exists + const key = localStorage.getItem('key'); // API key + // return the headers to the context so httpLink can read them + return { + headers: { + ...headers, + : token ?? undefined, + 'DG-Auth': key ?? undefined, + } + } +}); + +const client = new ApolloClient({ + link: authLink.concat(httpLink), + cache: new InMemoryCache() +}); +``` + +### Writing Auth Rules + +Once a client has been granted access to an operation with either Anonymous Access granted or as an authenticated client using an API Key, the GraphQL query or mutation is then unrestricted by default. In order to further restrict access, please see the [the @auth directive](https://dgraph.io/docs/graphql/authorization/directive/). + +### Restricting CORS + +Restricting the origins that your Dgraph Cloud responds to is an important step in preventing XSS exploits. By default, we allow requesting code from any origin access to your Dgraph Cloud resources (`Access-Control-Allow-Origin: *`), but by explicitly specifying the permitted origins this default behavior can be overridden. + +To allow an origin, add the line `# Dgraph.Allow-Origin` at the end of your GraphQL schema either with a [schema update](https://dgraph.io/docs/graphql/admin/#using-updategqlschema-to-add-or-modify-a-schema) or via the Cloud console's [Schema](https://cloud.dgraph.io/_/schema) page. For example, the following will restrict all origins except the ones specified. + +``` +# Dgraph.Allow-Origin "https://example.com" +# Dgraph.Allow-Origin "https://www.example.com" +``` + +On adding your first origin, we automatically add `https://cloud.dgraph.io` as well, so that the API explorer continues to work. + +{{% notice "note" %}} +CORS restrictions are not a replacement for writing auth rules, as it is possible for malicious actors to bypass these restrictions. +Also, note that CORS restrictions only apply to browsers, so you should never use CORS as a way to secure your system (CORS can only protect user data). +{{% /notice %}}