Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/scylladb/gocqlx
All-In-One: CQL query builder, ORM and migration tool
https://github.com/scylladb/gocqlx
cassandra cql gocql golang migration orm query-builder scylla
Last synced: 27 days ago
JSON representation
All-In-One: CQL query builder, ORM and migration tool
- Host: GitHub
- URL: https://github.com/scylladb/gocqlx
- Owner: scylladb
- License: apache-2.0
- Created: 2017-07-20T13:50:33.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-09-20T12:15:32.000Z (about 2 months ago)
- Last Synced: 2024-09-30T04:02:36.882Z (about 1 month ago)
- Topics: cassandra, cql, gocql, golang, migration, orm, query-builder, scylla
- Language: Go
- Homepage:
- Size: 367 KB
- Stars: 923
- Watchers: 24
- Forks: 122
- Open Issues: 33
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-repositories - scylladb/gocqlx - All-In-One: CQL query builder, ORM and migration tool (Go)
README
# 🚀 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.
## 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
```bash
git clone [email protected]:scylladb/gocqlx.git
cd gocqlx/cmd/schemagen/
go install .
```
## Getting started
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 {
t.Fatal(err)
}
```
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{"[email protected]"},
"red", // not persisted
"hazel" // not persisted
}
q := session.Query(personTable.Insert()).BindStruct(p)
if err := q.ExecRelease(); err != nil {
t.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 {
t.Fatal(err)
}
t.Log(p)
// stdout: {Michał Matczuk [[email protected]]}
```
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 {
t.Fatal(err)
}
t.Log(people)
// stdout: [{Michał Matczuk [[email protected]]}]
```
## 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!