From d17d2854ea187895445882fb39faeacd6da4e954 Mon Sep 17 00:00:00 2001 From: Matthew McNeely Date: Thu, 3 Apr 2025 12:37:33 -0400 Subject: [PATCH] Add connection string content --- dgraph/sdks/go.mdx | 107 ++++++++++++++++++++++++++++----------- dgraph/sdks/overview.mdx | 33 ++++++++++++ dgraph/sdks/python.mdx | 52 +++++++++++++++++-- 3 files changed, 159 insertions(+), 33 deletions(-) diff --git a/dgraph/sdks/go.mdx b/dgraph/sdks/go.mdx index 378ce63..f5428ae 100644 --- a/dgraph/sdks/go.mdx +++ b/dgraph/sdks/go.mdx @@ -28,45 +28,92 @@ More details on the supported versions can be found at ## Create the client -To create a client, dial a connection to Dgraph's external gRPC port (typically -`9080`). The following code snippet shows just one connection. You can connect -to multiple Dgraph Alphas to distribute the workload evenly. +### Connection Strings -```go -func newClient() *dgo.Dgraph { - // Dial a gRPC connection. The address to dial to can be configured when - // setting up the dgraph cluster. - d, err := grpc.Dial("localhost:9080", grpc.WithInsecure()) - if err != nil { - log.Fatal(err) - } +The dgo package supports connecting to a Dgraph cluster using connection +strings. Dgraph connections strings take the form +`dgraph://{username:password@}host:port?args`. - return dgo.NewDgraphClient( - api.NewDgraphClient(d), - ) -} +`username` and `password` are optional. If username is provided, a password must +also be present. If supplied, these credentials are used to log into a Dgraph +cluster through the ACL mechanism. + +Valid connection string args: + +| Arg | Value | Description | +| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| apikey | \ | a Dgraph Cloud API Key | +| bearertoken | \ | an access token | +| sslmode | disable \| require \| verify-ca | TLS option, the default is `disable`. If `verify-ca` is set, the TLS certificate configured in the Dgraph cluster must be from a valid certificate authority. | + +Some example connection strings: + +| Value | Explanation | +| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | +| dgraph://localhost:9080 | Connect to localhost, no ACL, no TLS | +| dgraph://sally:supersecret@dg.example.com:443?sslmode=verify-ca | Connect to remote server, use ACL and require TLS and a valid certificate from a CA | +| dgraph://foo-bar.grpc.us-west-2.aws.cloud.dgraph.io:443?sslmode=verify-ca&apikey=\ | Connect to a Dgraph Cloud cluster | +| dgraph://foo-bar.grpc.hypermode.com?sslmode=verify-ca&bearertoken=\ | Connect to a Dgraph cluster protected by a secure gateway | + +Using the `Open` function with a connection string: + +```go +// open a connection to an ACL-enabled, non-TLS cluster and login as groot +client, err := dgo.Open("dgraph://groot:password@localhost:8090") +// Check error +defer client.Close() +// Use the client ``` -The client can be configured to use gRPC compression: +### Advanced client creation + +For more control, you can create a client using the `NewClient` or the +`NewRoundRobinClient` function. ```go -func newClient() *dgo.Dgraph { - // Dial a gRPC connection. The address to dial to can be configured when - // setting up the dgraph cluster. - dialOpts := append([]grpc.DialOption{}, - grpc.WithInsecure(), - grpc.WithDefaultCallOptions(grpc.UseCompressor(gzip.Name))) - d, err := grpc.Dial("localhost:9080", dialOpts...) +// endpoints for three alpha nodes +endpoints := []string{"localhost:9180", "localhost:9182", "localhost:9183"} + +client, err := dgo.NewRoundRobinClient(endpoints, + // add Dgraph ACL credentials + dgo.WithACLCreds("groot", "password"), + // add insecure transport credentials + dgo.WithGrpcOption(grpc.WithTransportCredentials(insecure.NewCredentials())), + // add retry policy + dgo.WithGrpcOption(grpc.WithDefaultServiceConfig(`{ + "methodConfig": [{ + "retryPolicy": { + "MaxAttempts": 4 + } + }] + }`)), +) +// Check error +defer client.Close() +// Use the client +``` - if err != nil { - log.Fatal(err) - } +### Connecting To Dgraph Cloud - return dgo.NewDgraphClient( - api.NewDgraphClient(d), - ) -} +You can use either `Open` or `NewClient` to connect to Dgraph Cloud. + +Using `Open` with a connection string: +```go +client, err := dgo.Open("dgraph://foo-bar.grpc.cloud.dgraph.io:443?sslmode=verify-ca&apikey=AValidKeYFromDgrAPHCloud=") +// Check error +defer client.Close() +``` + +Using `NewClient`: + +```go +client, err := dgo.NewClient("foo-bar.grpc.cloud.dgraph.io:443", + dgo.WithDgraphAPIKey("AValidKeYFromDgrAPHCloud="), + dgo.WithSystemCertPool(), +) +// Check error +defer client.Close() ``` ### Multi-tenancy diff --git a/dgraph/sdks/overview.mdx b/dgraph/sdks/overview.mdx index 1b6c73e..cf73ef5 100644 --- a/dgraph/sdks/overview.mdx +++ b/dgraph/sdks/overview.mdx @@ -36,6 +36,39 @@ client library exists for your language, that's a simpler option. semi-random initial predicate distribution. +### Connection Strings + +Most clients support opening communications to Dgraph clusters using connection +strings. Dgraph connections strings take the form +`dgraph://{username:password@}host:port?args`. + +`username` and `password` are optional. If username is provided, a password must +also be present. If supplied, these credentials are used to log into a Dgraph +cluster through the ACL mechanism. + +Valid connection string args: + +| Arg | Value | Description | +| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| apikey | \ | a Dgraph Cloud API Key | +| bearertoken | \ | an access token | +| sslmode | disable \| require \| verify-ca | TLS option, the default is `disable`. If `verify-ca` is set, the TLS certificate configured in the Dgraph cluster must be from a valid certificate authority. | + +Note that using `sslmode=require` disables certificate validation and +significantly reduces the security of TLS. This mode should only be used in +non-production (e.g., testing or development) environments. + +Some example connection strings: + +| Value | Explanation | +| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | +| dgraph://localhost:9080 | Connect to localhost, no ACL, no TLS | +| dgraph://sally:supersecret@dg.example.com:443?sslmode=verify-ca | Connect to remote server, use ACL and require TLS and a valid certificate from a CA | +| dgraph://foo-bar.grpc.us-west-2.aws.cloud.dgraph.io:443?sslmode=verify-ca&apikey=\ | Connect to a Dgraph Cloud cluster | +| dgraph://foo-bar.grpc.hypermode.com?sslmode=verify-ca&bearertoken=\ | Connect to a Dgraph cluster protected by a secure gateway | + +See the various Dgraph client libraries for details on using connection strings. + ### Transactions Dgraph clients perform mutations and queries using transactions. A transaction diff --git a/dgraph/sdks/python.mdx b/dgraph/sdks/python.mdx index a77a61b..e2a8db8 100644 --- a/dgraph/sdks/python.mdx +++ b/dgraph/sdks/python.mdx @@ -35,18 +35,64 @@ More details on the supported versions can be found at ### Creating a client You can initialize a `DgraphClient` object by passing it a list of -`DgraphClientStub` clients as arguments. Connecting to multiple Dgraph servers -in the same cluster allows for better distribution of workload. +`DgraphClientStub` clients as variadic arguments. Connecting to multiple Dgraph +servers in the same cluster allows for better distribution of workload. The following code snippet shows just one connection. -```python +```python3 import pydgraph client_stub = pydgraph.DgraphClientStub('localhost:9080') client = pydgraph.DgraphClient(client_stub) ``` +### Using Dgraph Connection Strings + +The pydgraph package supports connecting to a Dgraph cluster using connection +strings. Dgraph connections strings take the form +`dgraph://{username:password@}host:port?args`. + +`username` and `password` are optional. If username is provided, a password must +also be present. If supplied, these credentials are used to log into a Dgraph +cluster through the ACL mechanism. + +Valid connection string args: + +| Arg | Value | Description | +| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| apikey | \ | a Dgraph Cloud API Key | +| bearertoken | \ | an access token | +| sslmode | disable \| require \| verify-ca | TLS option, the default is `disable`. If `verify-ca` is set, the TLS certificate configured in the Dgraph cluster must be from a valid certificate authority. | + +Note the `sslmode=require` pair is not supported and will throw an Exception if +used. Python gRPC does not support traffic over TLS that does not fully verify +the certificate and domain. Developers should use the existing stub/client +initialization steps for self-signed certs as demonstrated in tls_example.py +sample script in the +[pydgraph repository](https://github.com/hypermodeinc/pydgraph). + +Some example connection strings: + +| Value | Explanation | +| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | +| dgraph://localhost:9080 | Connect to localhost, no ACL, no TLS | +| dgraph://sally:supersecret@dg.example.com:443?sslmode=verify-ca | Connect to remote server, use ACL and require TLS and a valid certificate from a CA | +| dgraph://foo-bar.grpc.us-west-2.aws.cloud.dgraph.io:443?sslmode=verify-ca&apikey=\ | Connect to a Dgraph Cloud cluster | +| dgraph://foo-bar.grpc.hypermode.com:443?sslmode=verify-ca&bearertoken=\ | Connect to a Dgraph cluster protected by a secure gateway | + +Using the `Open` function with a connection string: + +```go +// open a connection to an ACL-enabled, non-TLS cluster and login as groot +client = pydgraph.open("dgraph://groot:password@localhost:8090") + +// Use the client +... + +client.close() +``` + ### Multi-tenancy In [multi-tenancy](/dgraph/enterprise/multitenancy) environments, PyDgraph