38001d64ac
* Update gocql version to v1.16.1 1. Update gocql to v1.16.1 2. Update golang to 1.25, since new gocql version requres it * Update golangci to 2.5.0 It is needed since 1.64.8 does not support golang 1.25. 1. Update golangci to 2.5.0 2. Migrate from golangci config v1 to v2 3. Integrate fieldaligment to golangci 4. Drop fieldaligment from Makefile 5. Address complaints
273 lines
8.4 KiB
Markdown
273 lines
8.4 KiB
Markdown
# 🚀 GocqlX [](https://pkg.go.dev/github.com/scylladb/gocqlx/v3) [](https://goreportcard.com/report/github.com/scylladb/gocqlx) [](https://travis-ci.org/scylladb/gocqlx)
|
||
|
||
GocqlX makes working with Scylla easy and less error-prone.
|
||
It’s inspired by [Sqlx](https://github.com/jmoiron/sqlx), a tool for working with SQL databases, but it goes beyond what Sqlx provides.
|
||
|
||
## Compatibility
|
||
|
||
Versions of GocqlX prior to v3.0.0 are compatible with both [Apache Cassandra’s gocql](https://github.com/apache/cassandra-gocql-driver) and [ScyllaDB’s fork](https://github.com/scylladb/gocql).
|
||
However, starting with v3.0.0, GocqlX exclusively supports the scylladb/gocql driver.
|
||
If you are using GocqlX v3.0.0 or newer, you must ensure your `go.mod` includes a replace directive to point to ScyllaDB’s fork:
|
||
|
||
```go
|
||
// Use the latest version of scylladb/gocql; check for updates at https://github.com/scylladb/gocql/releases
|
||
replace github.com/gocql/gocql => github.com/scylladb/gocql v1.16.0
|
||
```
|
||
|
||
This is required because GocqlX relies on ScyllaDB-specific extensions and bug fixes introduced in the gocql fork. Attempting to use the standard gocql driver with GocqlX v3.0.0+ may lead to build or runtime issues.
|
||
|
||
## Features
|
||
|
||
* Binding query parameters from struct fields, map, or both
|
||
* Scanning query results into structs based on field names
|
||
* Convenient functions for common tasks such as loading a single row into a struct or all rows into a slice (list) of structs
|
||
* Making any struct a UDT without implementing marshalling functions
|
||
* GocqlX is fast. Its performance is comparable to raw driver. You can find some benchmarks [here](#performance).
|
||
|
||
Subpackages provide additional functionality:
|
||
|
||
* CQL query builder ([package qb](https://github.com/scylladb/gocqlx/blob/master/qb))
|
||
* CRUD operations based on table model ([package table](https://github.com/scylladb/gocqlx/blob/master/table))
|
||
* Database migrations ([package migrate](https://github.com/scylladb/gocqlx/blob/master/migrate))
|
||
|
||
## Installation GocqlX
|
||
|
||
Add GocqlX to your Go module:
|
||
|
||
```bash
|
||
go get github.com/scylladb/gocqlx/v3
|
||
```
|
||
|
||
## Installation schemagen
|
||
|
||
Unfortunately you can't install it via `go install`, since `go.mod` contains `replace` directive.
|
||
So, you have to check it out and install manually:
|
||
```bash
|
||
git clone git@github.com:scylladb/gocqlx.git
|
||
cd gocqlx/cmd/schemagen/
|
||
go install .
|
||
```
|
||
|
||
## Getting started
|
||
|
||
First, import the required packages:
|
||
|
||
```go
|
||
import (
|
||
"fmt"
|
||
"log"
|
||
|
||
"github.com/gocql/gocql"
|
||
"github.com/scylladb/gocqlx/v3"
|
||
"github.com/scylladb/gocqlx/v3/qb"
|
||
"github.com/scylladb/gocqlx/v3/table"
|
||
)
|
||
```
|
||
|
||
Wrap gocql Session:
|
||
|
||
```go
|
||
// Create gocql cluster.
|
||
cluster := gocql.NewCluster(hosts...)
|
||
// Wrap session on creation, gocqlx session embeds gocql.Session pointer.
|
||
session, err := gocqlx.WrapSession(cluster.CreateSession())
|
||
if err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
defer session.Close()
|
||
```
|
||
|
||
Specify table model:
|
||
|
||
```go
|
||
// metadata specifies table name and columns it must be in sync with schema.
|
||
var personMetadata = table.Metadata{
|
||
Name: "person",
|
||
Columns: []string{"first_name", "last_name", "email"},
|
||
PartKey: []string{"first_name"},
|
||
SortKey: []string{"last_name"},
|
||
}
|
||
|
||
// personTable allows for simple CRUD operations based on personMetadata.
|
||
var personTable = table.New(personMetadata)
|
||
|
||
// Person represents a row in person table.
|
||
// Field names are converted to snake case by default, no need to add special tags.
|
||
// A field will not be persisted by adding the `db:"-"` tag or making it unexported.
|
||
type Person struct {
|
||
FirstName string
|
||
LastName string
|
||
Email []string
|
||
HairColor string `db:"-"` // exported and skipped
|
||
eyeColor string // unexported also skipped
|
||
}
|
||
```
|
||
|
||
Bind data from a struct and insert a row:
|
||
|
||
```go
|
||
p := Person{
|
||
"Michał",
|
||
"Matczuk",
|
||
[]string{"michal@scylladb.com"},
|
||
"red", // not persisted
|
||
"hazel" // not persisted
|
||
}
|
||
q := session.Query(personTable.Insert()).BindStruct(p)
|
||
if err := q.ExecRelease(); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
```
|
||
|
||
Load a single row to a struct:
|
||
|
||
```go
|
||
p := Person{
|
||
"Michał",
|
||
"Matczuk",
|
||
nil, // no email
|
||
}
|
||
q := session.Query(personTable.Get()).BindStruct(p)
|
||
if err := q.GetRelease(&p); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
fmt.Println(p)
|
||
// stdout: {Michał Matczuk [michal@scylladb.com]}
|
||
```
|
||
|
||
Load all rows in to a slice:
|
||
|
||
```go
|
||
var people []Person
|
||
q := session.Query(personTable.Select()).BindMap(qb.M{"first_name": "Michał"})
|
||
if err := q.SelectRelease(&people); err != nil {
|
||
log.Fatal(err)
|
||
}
|
||
fmt.Println(people)
|
||
// stdout: [{Michał Matczuk [michal@scylladb.com]}]
|
||
```
|
||
|
||
## Generating table metadata with schemagen
|
||
|
||
Installation
|
||
|
||
```bash
|
||
go get -u "github.com/scylladb/gocqlx/v3/cmd/schemagen"
|
||
```
|
||
|
||
Usage:
|
||
```bash
|
||
schemagen [flags]
|
||
|
||
Flags:
|
||
-cluster string
|
||
a comma-separated list of host:port tuples (default "127.0.0.1")
|
||
-keyspace string
|
||
keyspace to inspect (required)
|
||
-output string
|
||
the name of the folder to output to (default "models")
|
||
-pkgname string
|
||
the name you wish to assign to your generated package (default "models")
|
||
```
|
||
|
||
Example:
|
||
|
||
Running the following command for `examples` keyspace:
|
||
```bash
|
||
schemagen -cluster="127.0.0.1:9042" -keyspace="examples" -output="models" -pkgname="models"
|
||
```
|
||
|
||
Generates `models/models.go` as follows:
|
||
```go
|
||
// Code generated by "gocqlx/cmd/schemagen"; DO NOT EDIT.
|
||
|
||
package models
|
||
|
||
import "github.com/scylladb/gocqlx/v3/table"
|
||
|
||
// Table models.
|
||
var (
|
||
Playlists = table.New(table.Metadata{
|
||
Name: "playlists",
|
||
Columns: []string{
|
||
"album",
|
||
"artist",
|
||
"id",
|
||
"song_id",
|
||
"title",
|
||
},
|
||
PartKey: []string{
|
||
"id",
|
||
},
|
||
SortKey: []string{
|
||
"title",
|
||
"album",
|
||
"artist",
|
||
},
|
||
})
|
||
|
||
Songs = table.New(table.Metadata{
|
||
Name: "songs",
|
||
Columns: []string{
|
||
"album",
|
||
"artist",
|
||
"data",
|
||
"id",
|
||
"tags",
|
||
"title",
|
||
},
|
||
PartKey: []string{
|
||
"id",
|
||
},
|
||
SortKey: []string{},
|
||
})
|
||
)
|
||
```
|
||
|
||
## Examples
|
||
|
||
You can find lots of examples in [example_test.go](https://github.com/scylladb/gocqlx/blob/master/example_test.go).
|
||
|
||
Go and run them locally:
|
||
|
||
```bash
|
||
make run-scylla
|
||
make run-examples
|
||
```
|
||
|
||
## Training
|
||
|
||
The course [Using Scylla Drivers](https://university.scylladb.com/courses/using-scylla-drivers) in Scylla University explains how to use drivers in different languages to interact with a Scylla cluster. The lesson, [Golang and Scylla Part 3 - GoCQLX](https://university.scylladb.com/courses/using-scylla-drivers/lessons/golang-and-scylla-part-3-gocqlx/), goes over a sample application that, using GoCQLX, interacts with a three-node Scylla cluster. It connects to a Scylla cluster, displays the contents of a table, inserts and deletes data, and shows the contents of the table after each action. [Scylla University](https://university.scylladb.com/) includes other training material and online courses which will help you become a Scylla NoSQL database expert.
|
||
|
||
## Performance
|
||
|
||
GocqlX performance is comparable to the raw `gocql` driver.
|
||
Below benchmark results running on my laptop.
|
||
|
||
```
|
||
BenchmarkBaseGocqlInsert 2392 427491 ns/op 7804 B/op 39 allocs/op
|
||
BenchmarkGocqlxInsert 2479 435995 ns/op 7803 B/op 39 allocs/op
|
||
BenchmarkBaseGocqlGet 2853 452384 ns/op 7309 B/op 35 allocs/op
|
||
BenchmarkGocqlxGet 2706 442645 ns/op 7646 B/op 38 allocs/op
|
||
BenchmarkBaseGocqlSelect 747 1664365 ns/op 49415 B/op 927 allocs/op
|
||
BenchmarkGocqlxSelect 667 1877859 ns/op 42521 B/op 932 allocs/op
|
||
```
|
||
|
||
See the benchmark in [benchmark_test.go](https://github.com/scylladb/gocqlx/blob/master/benchmark_test.go).
|
||
|
||
## License
|
||
|
||
Copyright (C) 2017 ScyllaDB
|
||
|
||
This project is distributed under the Apache 2.0 license. See the [LICENSE](https://github.com/scylladb/gocqlx/blob/master/LICENSE) file for details.
|
||
It contains software from:
|
||
|
||
* [gocql project](https://github.com/gocql/gocql), licensed under the BSD license
|
||
* [sqlx project](https://github.com/jmoiron/sqlx), licensed under the MIT license
|
||
|
||
Apache®, Apache Cassandra® are either registered trademarks or trademarks of
|
||
the Apache Software Foundation in the United States and/or other countries.
|
||
No endorsement by The Apache Software Foundation is implied by the use of these marks.
|
||
|
||
GitHub star is always appreciated!
|