Driver: Add page about Go

docs/connect/go/index.md

@@ -0,0 +1,54 @@
+(connect-go)=
+
+# Go
+
+:::{include} /_include/links.md
+:::
+
+:::{div} sd-text-muted
+Connect to CrateDB from Go applications.
+:::
+
+The `pgx` and `pq` packages have been validated with CrateDB.
+`pq` is in maintenance mode, so their authors recommend using
+`pgx` which is under active development.
+
+The `KSQL` package is a convenience wrapper that also uses the
+`pgx` library to connect to CrateDB.
+
+:::{rubric} Overview
+:::
+
+:::{toctree}
+:hidden:
+pgx
+pq
+ksql
+:::
+
+:::::{grid} 2 2 2 3
+:gutter: 2
+:padding: 0
+
+::::{grid-item-card} {octicon}`package;2em;sd-text-info`   pgx
+:link: go-pgx
+:link-type: ref
+:link-alt: pgx for Go
+pgx is a pure Go driver and toolkit for PostgreSQL.
+::::
+
+::::{grid-item-card} {octicon}`package;2em;sd-text-info`   pq
+:link: go-pq
+:link-type: ref
+:link-alt: pq for Go
+pq is a pure Go PostgreSQL driver for Go's database/sql package.
+::::
+
+::::{grid-item-card} {octicon}`package;2em;sd-text-info`   KSQL
+:link: go-ksql
+:link-type: ref
+:link-alt: KSQL for Go
+KSQL, the _Keep it Simple_ SQL library.
+::::
+
+:::::

docs/connect/go/ksql.md

@@ -0,0 +1,101 @@
+(go-ksql)=
+# KSQL
+
+:::{rubric} About
+:::
+
+[KSQL] is a simple and powerful Golang SQL library based on
+`pgx` and `database/sql`.
+
+:::{rubric} Features
+:::
+
+- Support for all common relational databases: `mysql`, `sqlite`, `sqlserver`, `postgresql`, `cratedb`
+- Generic and powerful functions for Querying and Scanning data into structs
+- Works on top of existing battle-tested libraries such as `database/sql` and `pgx`
+- Helper functions for everyday operations, namely: Insert, Patch and Delete
+- Supports `sql.Scanner` and `sql.Valuer` and also all `pgx` special types (when using `kpgx`)
+- Every operation returns errors a single time, so its easier to handle them
+
+... and many more.
+
+:::{rubric} Synopsis
+:::
+
+`example.go`
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "log"
+
+    "github.com/vingarcia/ksql"
+    "github.com/vingarcia/ksql/adapters/kpgx"
+)
+
+var SummitsTable = ksql.NewTable("summits")
+
+type Summit struct {
+    Mountain  string  `ksql:"mountain"`
+    Region    string  `ksql:"region"`
+    Height    int     `ksql:"height"`
+    Latitude  float32 `ksql:"latitude"`
+    Longitude float32 `ksql:"longitude"`
+}
+
+func main() {
+    ctx := context.Background()
+
+    // Connect to database.
+    dbURL := "postgresql://crate:crate@localhost:5432/doc?sslmode=disable"
+    db, err := kpgx.New(ctx, dbURL, ksql.Config{})
+    if err != nil {
+        log.Fatalf("unable connect to database: %s", err)
+    }
+    defer db.Close()
+
+    // Invoke query.
+    var rows []Summit
+    db.Query(ctx, &rows, `
+        SELECT
+            mountain, region, height,
+            LATITUDE(coordinates) AS latitude,
+            LONGITUDE(coordinates) AS longitude
+        FROM sys.summits
+        ORDER BY height DESC
+        LIMIT 5`)
+
+    // Display results.
+    for _, row := range rows {
+        fmt.Printf("- %#v\n", row)
+    }
+}
+```
+
+:::{rubric} CrateDB Cloud
+:::
+
+For connecting to CrateDB Cloud, use `sslmode=require`, and
+replace username, password, and hostname with values matching
+your environment.
+```go
+dbURL := "postgresql://admin:[email protected]:5432/doc?sslmode=require"
+```
+
+:::{rubric} Quickstart example
+:::
+
+Create the file `example.go` including the synopsis code shared above.
+
+:::{include} ../_cratedb.md
+:::
+```shell
+go mod init github.com/cratedb-guide/connect/go/ksql
+go mod tidy
+go run example.go
+```
+
+
+[KSQL]: https://github.com/VinGarcia/ksql

docs/connect/go/pgx.md

@@ -0,0 +1,100 @@
+(go-pgx)=
+# pgx
+
+:::{div} .float-right .text-right
+[![Go pgx CI](https://github.com/crate/cratedb-examples/actions/workflows/lang-go-pgx.yml/badge.svg)](https://github.com/crate/cratedb-examples/actions/workflows/lang-go-pgx.yml)
+:::
+:::{div} .clearfix
+:::
+
+:::{rubric} About
+:::
+
+[pgx] is a pure Go driver and toolkit for PostgreSQL.
+
+:::{rubric} Features
+:::
+
+- Support for approximately 70 different PostgreSQL types
+- Connection pool with after-connect hook for arbitrary connection setup
+- Adapter for Go's standard `database/sql` interface
+- Automatic statement preparation and caching
+- Single-round trip query mode
+- Full TLS connection control
+- Tracing and logging support
+- Batch queries
+
+... and many more.
+
+:::{rubric} Synopsis
+:::
+
+`example.go`
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+
+    "github.com/jackc/pgx/v5"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Connect to database.
+    conn, _ := pgx.Connect(ctx, "postgresql://crate:crate@localhost:5432/doc?sslmode=disable")
+    defer conn.Close(ctx)
+
+    // Invoke basic query.
+    rows, _ := conn.Query(ctx, "SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")
+    defer rows.Close(ctx)
+
+    // Display results.
+    for rows.Next() {
+        var mountain string
+        var height int
+        rows.Scan(&mountain, &height)
+        fmt.Println(mountain, height)
+    }
+}
+```
+
+:::{rubric} CrateDB Cloud
+:::
+
+For connecting to CrateDB Cloud, use `sslmode=require`, and
+replace username, password, and hostname with values matching
+your environment.
+```go
+conn, _ := pgx.Connect(ctx, "postgresql://admin:[email protected]:5432/doc?sslmode=require")
+```
+
+:::{rubric} Quickstart example
+:::
+
+Create the file `example.go` including the synopsis code shared above.
+
+:::{include} ../_cratedb.md
+:::
+```shell
+go mod init github.com/cratedb-guide/connect/go/pgx
+go mod tidy
+go run example.go
+```
+
+:::{rubric} Full example
+:::
+
+:::{card}
+:link: https://github.com/crate/cratedb-examples/tree/main/by-language/go-pgx
+:link-type: url
+{material-regular}`play_arrow;2em`
+Connect to CrateDB and CrateDB Cloud using Go.
++++
+Demonstrates basic examples and bulk insert operations using the pgx driver.
+:::
+
+
+[pgx]: https://github.com/jackc/pgx

docs/connect/go/pq.md

@@ -0,0 +1,68 @@
+(go-pq)=
+# pq
+
+:::{rubric} About
+:::
+
+[pq] is a pure Go PostgreSQL driver for Go's `database/sql` package.
+
+:::{rubric} Synopsis
+:::
+
+`example.go`
+```go
+package main
+
+import (
+    "database/sql"
+    "fmt"
+
+    _ "github.com/lib/pq"
+)
+
+func main() {
+
+    // Connect to database.
+    connStr := "postgresql://crate:crate@localhost:5432/doc?sslmode=disable"
+    db, _ := sql.Open("postgres", connStr)
+    defer db.Close()
+
+    // Invoke basic query.
+    rows, _ := db.Query("SELECT mountain, height FROM sys.summits ORDER BY height DESC LIMIT 3")
+    defer rows.Close()
+
+    // Display results.
+    for rows.Next() {
+        var mountain string
+        var height int
+        rows.Scan(&mountain, &height)
+        fmt.Println(mountain, height)
+    }
+}
+```
+
+:::{rubric} CrateDB Cloud
+:::
+
+For connecting to CrateDB Cloud, use `sslmode=require`, and
+replace username, password, and hostname with values matching
+your environment.
+```go
+connStr := "postgresql://admin:[email protected]:5432/doc?sslmode=require"
+```
+
+:::{rubric} Quickstart example
+:::
+
+Create the file `example.go` including the synopsis code shared above.
+
+:::{include} ../_cratedb.md
+:::
+```shell
+go mod init github.com/cratedb-guide/connect/go/pq
+go mod tidy
+go run example.go
+```
+
+
+[pq]: https://github.com/lib/pq

docs/connect/index.md

@@ -49,6 +49,18 @@ CrateDB drivers and adapters for supported programming languages, frameworks, an
 :gutter: 3
 :padding: 0
 
+::::{grid-item-card} Go
+:link: connect-go
+:link-type: ref
+:link-alt: Connect to CrateDB using Go
+:padding: 3
+:text-align: center
+:class-card: sd-pt-3
+:class-body: sd-fs-1
+:class-title: sd-fs-6
+{fab}`golang`
+::::
+
 ::::{grid-item-card} Java
 :link: connect-java
 :link-type: ref
@@ -199,6 +211,7 @@ application
 :maxdepth: 1
 :hidden:
 
+go/index
 java/index
 javascript
 php