GocqlX makes working with Scylla easy and error-prone without sacrificing performance. It’s inspired by Sqlx, a tool for working with SQL databases, but it goes beyond what Sqlx provides.
- 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.
Subpackages provide additional functionality:
- CQL query builder (package qb)
- CRUD operations based on table model (package table)
- Database migrations (package migrate)
go get -u github.com/scylladb/gocqlx/v2
Wrap gocql Session:
// 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 {
t.Fatal(err)
}
Specify table model:
// 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 camel case by default, no need to add special tags.
// If you want to disable a field add `db:"-"` tag, it will not be persisted.
type Person struct {
FirstName string
LastName string
Email []string
}
Bind data from a struct and insert a row:
p := Person{
"Michał",
"Matczuk",
[]string{"[email protected]"},
}
q := session.Query(personTable.Insert()).BindStruct(p)
if err := q.ExecRelease(); err != nil {
t.Fatal(err)
}
Load a single row to a struct:
p := Person{
"Michał",
"Matczuk",
nil, // no email
}
q := session.Query(personTable.Get()).BindStruct(p)
if err := q.GetRelease(&p); err != nil {
t.Fatal(err)
}
t.Log(p)
// stdout: {Michał Matczuk [[email protected]]}
Load all rows in to a slice:
var people []Person
q := session.Query(personTable.Select()).BindMap(qb.M{"first_name": "Michał"})
if err := q.SelectRelease(&people); err != nil {
t.Fatal(err)
}
t.Log(people)
// stdout: [{Michał Matczuk [[email protected]]}]
You can find lots of examples in example_test.go.
Go and run them locally:
make run-scylla
make run-examples
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.
Copyright (C) 2017 ScyllaDB
This project is distributed under the Apache 2.0 license. See the LICENSE file for details. It contains software from:
- gocql project, licensed under the BSD license
- sqlx project, 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!