diff --git a/docs/connect/go/index.md b/docs/connect/go/index.md new file mode 100644 index 00000000..4143d2cf --- /dev/null +++ b/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. +:::: + +::::: diff --git a/docs/connect/go/ksql.md b/docs/connect/go/ksql.md new file mode 100644 index 00000000..dd6e3b80 --- /dev/null +++ b/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:password@testcluster.cratedb.net: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 diff --git a/docs/connect/go/pgx.md b/docs/connect/go/pgx.md new file mode 100644 index 00000000..ff316b8a --- /dev/null +++ b/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:password@testcluster.cratedb.net: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 diff --git a/docs/connect/go/pq.md b/docs/connect/go/pq.md new file mode 100644 index 00000000..cdb68a30 --- /dev/null +++ b/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:password@testcluster.cratedb.net: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 diff --git a/docs/connect/index.md b/docs/connect/index.md index e9e6b458..c8c26993 100644 --- a/docs/connect/index.md +++ b/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