Skip to content

Commit d17d285

Browse files
matthewmcneelymatthewmcneely
committed
Add connection string content
1 parent bde23d6 commit d17d285

File tree

3 files changed

+159
-33
lines changed

3 files changed

+159
-33
lines changed

‎dgraph/sdks/go.mdx

Lines changed: 77 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -28,45 +28,92 @@ More details on the supported versions can be found at
2828

2929
## Create the client
3030

31-
To create a client, dial a connection to Dgraph's external gRPC port (typically
32-
`9080`). The following code snippet shows just one connection. You can connect
33-
to multiple Dgraph Alphas to distribute the workload evenly.
31+
### Connection Strings
3432

35-
```go
36-
func newClient() *dgo.Dgraph {
37-
// Dial a gRPC connection. The address to dial to can be configured when
38-
// setting up the dgraph cluster.
39-
d, err := grpc.Dial("localhost:9080", grpc.WithInsecure())
40-
if err != nil {
41-
log.Fatal(err)
42-
}
33+
The dgo package supports connecting to a Dgraph cluster using connection
34+
strings. Dgraph connections strings take the form
35+
`dgraph://{username:password@}host:port?args`.
4336

44-
return dgo.NewDgraphClient(
45-
api.NewDgraphClient(d),
46-
)
47-
}
37+
`username` and `password` are optional. If username is provided, a password must
38+
also be present. If supplied, these credentials are used to log into a Dgraph
39+
cluster through the ACL mechanism.
40+
41+
Valid connection string args:
42+
43+
| Arg | Value | Description |
44+
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
45+
| apikey | \<key\> | a Dgraph Cloud API Key |
46+
| bearertoken | \<token\> | an access token |
47+
| 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. |
48+
49+
Some example connection strings:
50+
51+
| Value | Explanation |
52+
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
53+
| dgraph://localhost:9080 | Connect to localhost, no ACL, no TLS |
54+
| dgraph://sally:[email protected]:443?sslmode=verify-ca | Connect to remote server, use ACL and require TLS and a valid certificate from a CA |
55+
| dgraph://foo-bar.grpc.us-west-2.aws.cloud.dgraph.io:443?sslmode=verify-ca&apikey=\<your-api-connection-key\> | Connect to a Dgraph Cloud cluster |
56+
| dgraph://foo-bar.grpc.hypermode.com?sslmode=verify-ca&bearertoken=\<some access token\> | Connect to a Dgraph cluster protected by a secure gateway |
57+
58+
Using the `Open` function with a connection string:
59+
60+
```go
61+
// open a connection to an ACL-enabled, non-TLS cluster and login as groot
62+
client, err := dgo.Open("dgraph://groot:password@localhost:8090")
63+
// Check error
64+
defer client.Close()
65+
// Use the client
4866
```
4967

50-
The client can be configured to use gRPC compression:
68+
### Advanced client creation
69+
70+
For more control, you can create a client using the `NewClient` or the
71+
`NewRoundRobinClient` function.
5172

5273
```go
53-
func newClient() *dgo.Dgraph {
54-
// Dial a gRPC connection. The address to dial to can be configured when
55-
// setting up the dgraph cluster.
56-
dialOpts := append([]grpc.DialOption{},
57-
grpc.WithInsecure(),
58-
grpc.WithDefaultCallOptions(grpc.UseCompressor(gzip.Name)))
59-
d, err := grpc.Dial("localhost:9080", dialOpts...)
74+
// endpoints for three alpha nodes
75+
endpoints := []string{"localhost:9180", "localhost:9182", "localhost:9183"}
76+
77+
client, err := dgo.NewRoundRobinClient(endpoints,
78+
// add Dgraph ACL credentials
79+
dgo.WithACLCreds("groot", "password"),
80+
// add insecure transport credentials
81+
dgo.WithGrpcOption(grpc.WithTransportCredentials(insecure.NewCredentials())),
82+
// add retry policy
83+
dgo.WithGrpcOption(grpc.WithDefaultServiceConfig(`{
84+
"methodConfig": [{
85+
"retryPolicy": {
86+
"MaxAttempts": 4
87+
}
88+
}]
89+
}`)),
90+
)
91+
// Check error
92+
defer client.Close()
93+
// Use the client
94+
```
6095

61-
if err != nil {
62-
log.Fatal(err)
63-
}
96+
### Connecting To Dgraph Cloud
6497

65-
return dgo.NewDgraphClient(
66-
api.NewDgraphClient(d),
67-
)
68-
}
98+
You can use either `Open` or `NewClient` to connect to Dgraph Cloud.
99+
100+
Using `Open` with a connection string:
69101

102+
```go
103+
client, err := dgo.Open("dgraph://foo-bar.grpc.cloud.dgraph.io:443?sslmode=verify-ca&apikey=AValidKeYFromDgrAPHCloud=")
104+
// Check error
105+
defer client.Close()
106+
```
107+
108+
Using `NewClient`:
109+
110+
```go
111+
client, err := dgo.NewClient("foo-bar.grpc.cloud.dgraph.io:443",
112+
dgo.WithDgraphAPIKey("AValidKeYFromDgrAPHCloud="),
113+
dgo.WithSystemCertPool(),
114+
)
115+
// Check error
116+
defer client.Close()
70117
```
71118

72119
### Multi-tenancy

‎dgraph/sdks/overview.mdx

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,39 @@ client library exists for your language, that's a simpler option.
3636
semi-random initial predicate distribution.
3737
</Tip>
3838

39+
### Connection Strings
40+
41+
Most clients support opening communications to Dgraph clusters using connection
42+
strings. Dgraph connections strings take the form
43+
`dgraph://{username:password@}host:port?args`.
44+
45+
`username` and `password` are optional. If username is provided, a password must
46+
also be present. If supplied, these credentials are used to log into a Dgraph
47+
cluster through the ACL mechanism.
48+
49+
Valid connection string args:
50+
51+
| Arg | Value | Description |
52+
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
53+
| apikey | \<key\> | a Dgraph Cloud API Key |
54+
| bearertoken | \<token\> | an access token |
55+
| 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. |
56+
57+
Note that using `sslmode=require` disables certificate validation and
58+
significantly reduces the security of TLS. This mode should only be used in
59+
non-production (e.g., testing or development) environments.
60+
61+
Some example connection strings:
62+
63+
| Value | Explanation |
64+
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
65+
| dgraph://localhost:9080 | Connect to localhost, no ACL, no TLS |
66+
| dgraph://sally:[email protected]:443?sslmode=verify-ca | Connect to remote server, use ACL and require TLS and a valid certificate from a CA |
67+
| dgraph://foo-bar.grpc.us-west-2.aws.cloud.dgraph.io:443?sslmode=verify-ca&apikey=\<your-api-connection-key\> | Connect to a Dgraph Cloud cluster |
68+
| dgraph://foo-bar.grpc.hypermode.com?sslmode=verify-ca&bearertoken=\<some access token\> | Connect to a Dgraph cluster protected by a secure gateway |
69+
70+
See the various Dgraph client libraries for details on using connection strings.
71+
3972
### Transactions
4073

4174
Dgraph clients perform mutations and queries using transactions. A transaction

‎dgraph/sdks/python.mdx

Lines changed: 49 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,18 +35,64 @@ More details on the supported versions can be found at
3535
### Creating a client
3636

3737
You can initialize a `DgraphClient` object by passing it a list of
38-
`DgraphClientStub` clients as arguments. Connecting to multiple Dgraph servers
39-
in the same cluster allows for better distribution of workload.
38+
`DgraphClientStub` clients as variadic arguments. Connecting to multiple Dgraph
39+
servers in the same cluster allows for better distribution of workload.
4040

4141
The following code snippet shows just one connection.
4242

43-
```python
43+
```python3
4444
import pydgraph
4545

4646
client_stub = pydgraph.DgraphClientStub('localhost:9080')
4747
client = pydgraph.DgraphClient(client_stub)
4848
```
4949

50+
### Using Dgraph Connection Strings
51+
52+
The pydgraph package supports connecting to a Dgraph cluster using connection
53+
strings. Dgraph connections strings take the form
54+
`dgraph://{username:password@}host:port?args`.
55+
56+
`username` and `password` are optional. If username is provided, a password must
57+
also be present. If supplied, these credentials are used to log into a Dgraph
58+
cluster through the ACL mechanism.
59+
60+
Valid connection string args:
61+
62+
| Arg | Value | Description |
63+
| ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
64+
| apikey | \<key\> | a Dgraph Cloud API Key |
65+
| bearertoken | \<token\> | an access token |
66+
| 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. |
67+
68+
Note the `sslmode=require` pair is not supported and will throw an Exception if
69+
used. Python gRPC does not support traffic over TLS that does not fully verify
70+
the certificate and domain. Developers should use the existing stub/client
71+
initialization steps for self-signed certs as demonstrated in tls_example.py
72+
sample script in the
73+
[pydgraph repository](https://github.com/hypermodeinc/pydgraph).
74+
75+
Some example connection strings:
76+
77+
| Value | Explanation |
78+
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
79+
| dgraph://localhost:9080 | Connect to localhost, no ACL, no TLS |
80+
| dgraph://sally:[email protected]:443?sslmode=verify-ca | Connect to remote server, use ACL and require TLS and a valid certificate from a CA |
81+
| dgraph://foo-bar.grpc.us-west-2.aws.cloud.dgraph.io:443?sslmode=verify-ca&apikey=\<your-api-connection-key\> | Connect to a Dgraph Cloud cluster |
82+
| dgraph://foo-bar.grpc.hypermode.com:443?sslmode=verify-ca&bearertoken=\<some access token\> | Connect to a Dgraph cluster protected by a secure gateway |
83+
84+
Using the `Open` function with a connection string:
85+
86+
```go
87+
// open a connection to an ACL-enabled, non-TLS cluster and login as groot
88+
client = pydgraph.open("dgraph://groot:password@localhost:8090")
89+
90+
// Use the client
91+
...
92+
93+
client.close()
94+
```
95+
5096
### Multi-tenancy
5197

5298
In [multi-tenancy](/dgraph/enterprise/multitenancy) environments, PyDgraph

0 commit comments

Comments
 (0)