Add examples for Client.With*() methods (#353)

fixes #288

Co-authored-by: Scott Trinh <scott@scotttrinh.com>

Author: fmoor

.golangci.yml

@@ -263,10 +263,15 @@ issues:
 
   # Excluding configuration per-path, per-linter, per-text and per-source
   exclude-rules:
-    # Exclude doc links
-    - linters:
+    # Don't complain about doc link urls that are more then 80 characters
+    - source: "^// \\[.*\\]: http"
+      linters:
         - lll
-      source: "^// \\[.*\\]: http"
+
+    # Don't complain about using our own deprecated gelcfg.Options.Database.
+    - source: "\\.Database[ ,)]"
+      linters:
+        - staticcheck
 
   # Independently from option `exclude` we use default exclude patterns,
   # it can be disabled by this option. To list all

client.go

@@ -20,17 +20,26 @@ import (
 	"context"
 
 	"github.com/geldata/gel-go/gelcfg"
+	"github.com/geldata/gel-go/gelerr"
 	"github.com/geldata/gel-go/geltypes"
 	gel "github.com/geldata/gel-go/internal/client"
 )
 
 // CreateClient returns a new client. The client connects lazily. Call
-// Client.EnsureConnected() to force a connection.
+// [Client.EnsureConnected] to force a connection.
+//
+// Instead of providing connection details directly, we recommend connecting
+// using projects locally, and environment variables for remote instances,
+// providing an empty [gelcfg.Options] struct here.
+// [Read more] about the recommended ways to configure client connections.
+//
+// [Read more]: https://docs.geldata.com/reference/clients/connection
 func CreateClient(opts gelcfg.Options) (*Client, error) { // nolint:gocritic,lll
 	return CreateClientDSN("", opts)
 }
 
-// CreateClientDSN returns a new client. See also CreateClient.
+// CreateClientDSN returns a new Client. We recommend using [CreateClient] for
+// most use cases.
 //
 // dsn is either an instance name or a [DSN].
 //
@@ -51,7 +60,11 @@ type Client struct {
 	pool *gel.Pool
 }
 
-// EnsureConnected forces the client to connect if it hasn't already.
+// EnsureConnected forces the client to connect if it hasn't already. This can
+// be used to ensure that your program will fail early in the case that the
+// [configured connection parameters] are not correct.
+//
+// [configured connection parameters]: https://docs.geldata.com/reference/clients/connection
 func (c *Client) EnsureConnected(ctx context.Context) error {
 	return c.pool.EnsureConnected(ctx)
 }
@@ -62,11 +75,7 @@ func (c *Client) EnsureConnected(ctx context.Context) error {
 func (c *Client) Close() error { return c.pool.Close() }
 
 // Execute an EdgeQL command (or commands).
-func (c *Client) Execute(
-	ctx context.Context,
-	cmd string,
-	args ...interface{},
-) error {
+func (c *Client) Execute(ctx context.Context, cmd string, args ...interface{}) error { //nolint:lll
 	conn, err := c.pool.Acquire(ctx)
 	if err != nil {
 		return err
@@ -91,12 +100,7 @@ func (c *Client) Execute(
 }
 
 // Query runs a query and returns the results.
-func (c *Client) Query(
-	ctx context.Context,
-	cmd string,
-	out interface{},
-	args ...interface{},
-) error {
+func (c *Client) Query(ctx context.Context, cmd string, out interface{}, args ...interface{}) error { //nolint:lll
 	conn, err := c.pool.Acquire(ctx)
 	if err != nil {
 		return err
@@ -115,16 +119,15 @@ func (c *Client) Query(
 	return gel.FirstError(err, c.pool.Release(conn, err))
 }
 
-// QuerySingle runs a singleton-returning query and returns its element.
-// If the query executes successfully but doesn't return a result
-// a NoDataError is returned. If the out argument is an optional type the out
-// argument will be set to missing instead of returning a NoDataError.
-func (c *Client) QuerySingle(
-	ctx context.Context,
-	cmd string,
-	out interface{},
-	args ...interface{},
-) error {
+// needed for dock link [gelerr.NoDataError]
+var _ = gelerr.NoDataError
+
+// QuerySingle runs a singleton-returning query and returns its element.  If
+// the query executes successfully but doesn't return a result a
+// [gelerr.NoDataError] is returned.  If the out
+// argument is an optional type the out argument will be set to missing instead
+// of returning a NoDataError.
+func (c *Client) QuerySingle(ctx context.Context, cmd string, out interface{}, args ...interface{}) error { //nolint:lll
 	conn, err := c.pool.Acquire(ctx)
 	if err != nil {
 		return err
@@ -143,13 +146,8 @@ func (c *Client) QuerySingle(
 	return gel.FirstError(err, c.pool.Release(conn, err))
 }
 
-// QueryJSON runs a query and return the results as JSON.
-func (c *Client) QueryJSON(
-	ctx context.Context,
-	cmd string,
-	out *[]byte,
-	args ...interface{},
-) error {
+// QueryJSON runs a query and returns the results as JSON.
+func (c *Client) QueryJSON(ctx context.Context, cmd string, out *[]byte, args ...interface{}) error { //nolint:lll
 	conn, err := c.pool.Acquire(ctx)
 	if err != nil {
 		return err
@@ -170,13 +168,8 @@ func (c *Client) QueryJSON(
 
 // QuerySingleJSON runs a singleton-returning query.
 // If the query executes successfully but doesn't have a result
-// a NoDataError is returned.
-func (c *Client) QuerySingleJSON(
-	ctx context.Context,
-	cmd string,
-	out interface{},
-	args ...interface{},
-) error {
+// a [gelerr.NoDataError] is returned.
+func (c *Client) QuerySingleJSON(ctx context.Context, cmd string, out interface{}, args ...interface{}) error { //nolint:lll
 	conn, err := c.pool.Acquire(ctx)
 	if err != nil {
 		return err
@@ -196,12 +189,7 @@ func (c *Client) QuerySingleJSON(
 }
 
 // QuerySQL runs a SQL query and returns the results.
-func (c *Client) QuerySQL(
-	ctx context.Context,
-	cmd string,
-	out interface{},
-	args ...interface{},
-) error {
+func (c *Client) QuerySQL(ctx context.Context, cmd string, out interface{}, args ...interface{}) error { //nolint:lll
 	conn, err := c.pool.Acquire(ctx)
 	if err != nil {
 		return err
@@ -221,11 +209,7 @@ func (c *Client) QuerySQL(
 }
 
 // ExecuteSQL executes a SQL command (or commands).
-func (c *Client) ExecuteSQL(
-	ctx context.Context,
-	cmd string,
-	args ...interface{},
-) error {
+func (c *Client) ExecuteSQL(ctx context.Context, cmd string, args ...interface{}) error { //nolint:lll
 	conn, err := c.pool.Acquire(ctx)
 	if err != nil {
 		return err
@@ -249,11 +233,16 @@ func (c *Client) ExecuteSQL(
 	return gel.FirstError(err, c.pool.Release(conn, err))
 }
 
-// Tx runs action in a transaction retrying failed attempts.
+// Tx runs action in a transaction retrying failed attempts. Queries must be
+// executed on the [geltypes.Tx] that is passed to action. Queries executed on
+// the client in a geltypes.TxBlock will not run in the transaction and will be
+// applied immediately.
 //
-// Retries are governed by [gelcfg.RetryOptions] and [gelcfg.RetryRule].
-// retry options can be set using [Client.WithRetryOptions].
-// See [gelcfg.RetryRule] for more details on how they work.
+// The geltypes.TxBlock may be re-run if any of the queries fail in a way that
+// might succeed on subsequent attempts. Retries are governed by
+// [gelcfg.RetryOptions] and [gelcfg.RetryRule].  Retry options can be set
+// using [Client.WithRetryOptions].  See [gelcfg.RetryRule] for more details on
+// how they work.
 func (c *Client) Tx(ctx context.Context, action geltypes.TxBlock) error {
 	conn, err := c.pool.Acquire(ctx)
 	if err != nil {

client_examples_test.go

@@ -0,0 +1,122 @@
+// This source file is part of the Gel open source project.
+//
+// Copyright Gel Data Inc. and the Gel authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package gel_test
+
+import (
+	"fmt"
+	"log"
+
+	gel "github.com/geldata/gel-go"
+)
+
+func ExampleCreateClient() {
+	client, err := gel.CreateClient(opts)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	var result int64
+	err = client.QuerySingle(ctx, `SELECT 1`, &result)
+	if err != nil {
+		fmt.Println(err)
+	}
+
+	fmt.Println(result)
+	// Output: 1
+}
+
+func ExampleClient_Execute() {
+	err := client.Execute(ctx, "INSERT Product")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Output:
+}
+
+func ExampleClient_ExecuteSQL() {
+	err := client.ExecuteSQL(ctx, `INSERT INTO "Product" DEFAULT VALUES`)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	// Output:
+}
+
+func ExampleClient_Query() {
+	var output []struct {
+		Result int64 `gel:"result"`
+	}
+
+	err := client.Query(ctx, `SELECT {result := 2 + 2}`, &output)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Print(output)
+	// Output: [{4}]
+}
+
+func ExampleClient_QueryJSON() {
+	var output []byte
+	err := client.QueryJSON(ctx, `SELECT {result := 2 + 2}`, &output)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println(string(output))
+	// Output: [{"result" : 4}]
+}
+
+func ExampleClient_QuerySQL() {
+	var output []struct {
+		Result int32 `gel:"result"`
+	}
+
+	err := client.QuerySQL(ctx, `SELECT 2 + 2 AS result`, &output)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println(output)
+	// Output: [{4}]
+}
+
+func ExampleClient_QuerySingle() {
+	var output struct {
+		Result int64 `gel:"result"`
+	}
+
+	err := client.QuerySingle(ctx, `SELECT {result := 2 + 2}`, &output)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Print(output)
+	// Output: {4}
+}
+
+func ExampleClient_QuerySingleJSON() {
+	var output []byte
+	err := client.QuerySingleJSON(ctx, `SELECT {result := 2 + 2}`, &output)
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	fmt.Println(string(output))
+	// Output: {"result" : 4}
+}

connect_test.go

@@ -38,7 +38,7 @@ func TestAuth(t *testing.T) {
 		Port:       opts.Port,
 		User:       "user_with_password",
 		Password:   types.NewOptionalStr("secret"),
-		Database:   opts.Database, //nolint:staticcheck // SA1019
+		Database:   opts.Database,
 		TLSOptions: opts.TLSOptions,
 	})
 	require.NoError(t, err)
@@ -123,7 +123,7 @@ func TestConnectTimeout(t *testing.T) {
 		Port:               opts.Port,
 		User:               opts.User,
 		Password:           opts.Password,
-		Database:           opts.Database, //nolint:staticcheck // SA1019
+		Database:           opts.Database,
 		ConnectTimeout:     2 * time.Nanosecond,
 		WaitUntilAvailable: 1 * time.Nanosecond,
 	})