pixeldrain/gocqlx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Updated examples and README for 2.0

Browse Source 
Signed-off-by: Michał Matczuk <michal@scylladb.com>
This commit is contained in:
Michał Matczuk
2020-04-20 18:00:01 +02:00
committed by Michal Jan Matczuk
parent 227d152ac2
commit 0675f72f4f
9 changed files with 799 additions and 403 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
README.md
View File

@@ -1,104 +1,118 @@
# GoCQLX [![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](http://godoc.org/github.com/scylladb/gocqlx) [![Go Report Card](https://goreportcard.com/badge/github.com/scylladb/gocqlx)](https://goreportcard.com/report/github.com/scylladb/gocqlx) [![Build Status](https://travis-ci.org/scylladb/gocqlx.svg?branch=master)](https://travis-ci.org/scylladb/gocqlx)
# 🚀 GocqlX [![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](http://godoc.org/github.com/scylladb/gocqlx) [![Go Report Card](https://goreportcard.com/badge/github.com/scylladb/gocqlx)](https://goreportcard.com/report/github.com/scylladb/gocqlx) [![Build Status](https://travis-ci.org/scylladb/gocqlx.svg?branch=master)](https://travis-ci.org/scylladb/gocqlx)
Package `gocqlx` is an idiomatic extension to `gocql` that provides usability features. With gocqlx you can bind the query parameters from maps and structs, use named query parameters (:identifier) and scan the query results into structs and slices. It comes with a fluent and flexible CQL query builder and a database migrations module.
GocqlX makes working with Scylla easy and error prone without sacrificing performance.
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
go get -u github.com/scylladb/gocqlx
## Features
## Getting started
* Binding query parameters form struct
* Scanning results into struct or slice
* Automated UDT support
* CRUD operations based on table model ([package table](https://github.com/scylladb/gocqlx/blob/master/table))
* CQL query builder ([package qb](https://github.com/scylladb/gocqlx/blob/master/qb))
* Database migrations ([package migrate](https://github.com/scylladb/gocqlx/blob/master/migrate))
* Fast!
## Training and Scylla University
[Scylla University](https://university.scylladb.com/) includes training material and online courses which will help you become a Scylla NoSQL database expert.
The course [Using Scylla Drivers](https://university.scylladb.com/courses/using-scylla-drivers/) explains how to use drivers in different languages to interact with a Scylla cluster.
The lesson, [Golang and Scylla Part 3](https://university.scylladb.com/courses/using-scylla-drivers/lessons/golang-and-scylla-part-3-gocqlx/) includes a sample application that uses the GoCQXL package.
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.
Courses in [Scylla University](https://university.scylladb.com/) cover a variety of topics dealing with Scylla data modeling, administration, architecture and also covering some basic NoSQL concepts.
## Example
Wrap gocql Session:
```go
// 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
// 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)
}
```
// Insert, bind data from struct.
{
stmt, names := qb.Insert("gocqlx_test.person").Columns("first_name", "last_name", "email").ToCql()
q := gocqlx.Query(session.Query(stmt), names).BindStruct(p)
if err := q.ExecRelease(); err != nil {
t.Fatal(err)
}
}
// Get first result into a struct.
{
var p Person
stmt, names := qb.Select("gocqlx_test.person").Where(qb.Eq("first_name")).ToCql()
q := gocqlx.Query(session.Query(stmt), names).BindMap(qb.M{
"first_name": "Patricia",
})
if err := q.GetRelease(&p); err != nil {
t.Fatal(err)
}
}
// Load all the results into a slice.
{
var people []Person
stmt, names := qb.Select("gocqlx_test.person").Where(qb.In("first_name")).ToCql()
q := gocqlx.Query(session.Query(stmt), names).BindMap(qb.M{
"first_name": []string{"Patricia", "Igy", "Ian"},
})
if err := q.SelectRelease(&people); 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"},
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)
// Get by primary key.
{
p := Person{
"Patricia",
"Citizen",
nil, // no email
}
stmt, names := personTable.Get() // you can filter columns too
q := gocqlx.Query(session.Query(stmt), names).BindStruct(p)
if err := q.GetRelease(&p); err != nil {
t.Fatal(err)
}
// 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
}
```
See more examples in [example_test.go](https://github.com/scylladb/gocqlx/blob/master/example_test.go) and [table/example_test.go](https://github.com/scylladb/gocqlx/blob/master/table/example_test.go).
Bind data from a struct and insert a row:
```go
p := Person{
"Michał",
"Matczuk",
[]string{"michal@scylladb.com"},
}
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 [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 {
t.Fatal(err)
}
t.Log(people)
// stdout: [{Michał Matczuk [michal@scylladb.com]}]
```
## Examples
You can find lots of other examples in [example_test.go](https://github.com/scylladb/gocqlx/blob/master/example_test.go), go and run the examples locally:
```bash
make run-scylla
make run-examples
```
## Performance
With regards to performance `gocqlx` package is comparable to the raw `gocql` baseline.
GocqlX performance is comparable to the raw `gocql` driver.
Below benchmark results running on my laptop.
```
@@ -110,7 +124,12 @@ BenchmarkBaseGocqlSelect 747 1664365 ns/op 49415
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).
See the benchmark in [benchmark_test.go](https://github.com/scylladb/gocqlx/blob/master/benchmark_test.go), you can run the benchmark locally:
```bash
make run-scylla
make bench
```
## License