General purpose extensions to Go Cassandra driver - gocql
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
gocqlxtest added golangci (#59) Aug 7, 2018
migrate readme: updated docs May 25, 2018
qb Add qb.Like to query keys Jan 14, 2019
reflectx added golangci (#59) Aug 7, 2018
table table: added function to return table Metadata Nov 15, 2018
testdata test-fixtures renamed to testdata Sep 22, 2017
.gitignore initial version Jul 24, 2017
.golangci.yml added golangci (#59) Aug 7, 2018
.travis.yml travis: bump go to 1.11.1 Oct 23, 2018
.travis_start_db.sh added golangci (#59) Aug 7, 2018
LICENSE license and notice Jul 25, 2017
Makefile makefile: bump goloangci-lint to 1.10.2 Oct 23, 2018
README.md table: introduced table package Nov 14, 2018
benchmark_test.go benchmark fix and update Aug 23, 2018
doc.go readme: updated docs May 25, 2018
example_test.go table: introduced table package Nov 14, 2018
go.mod Update gocql version Jan 7, 2019
gocqlx.go reflectx: code ported from github.com/jmoiron/sqlx a2429ba May 25, 2018
iterx.go reflectx: code ported from github.com/jmoiron/sqlx a2429ba May 25, 2018
iterx_test.go workaround for gocql bug gocql/gocql#1161 Aug 23, 2018
mapper.go reflectx: code ported from github.com/jmoiron/sqlx a2429ba May 25, 2018
mapper_bench_test.go testing: benchmarks moved to separate files May 23, 2018
mapper_test.go testing: benchmarks moved to separate files May 23, 2018
queryx.go queryx: added Iter function Oct 23, 2018
queryx_bench_test.go testing: benchmarks moved to separate files May 23, 2018
queryx_test.go testing: benchmarks moved to separate files May 23, 2018

README.md

GoCQLX GoDoc Go Report Card Build Status

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.

Installation

go get -u github.com/scylladb/gocqlx

Features

  • Binding query parameters form struct or map
  • Scanning results directly into struct or slice
  • CQL query builder (package qb)
  • Super simple CRUD operations based on table model (package table)
  • Database migrations (package migrate)
  • Fast!

Example

// 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
}

// 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)
    }
}

// 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)

// 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)
    }
}

See more examples in example_test.go and table/example_test.go.

Performance

Gocqlx is fast, this is a benchmark result comparing gocqlx to raw gocql on a local machine, Intel(R) Core(TM) i7-7500U CPU @ 2.70GHz.

BenchmarkE2EGocqlInsert            20000             86713 ns/op            2030 B/op         33 allocs/op
BenchmarkE2EGocqlxInsert           20000             87882 ns/op            2030 B/op         33 allocs/op
BenchmarkE2EGocqlGet               20000             94308 ns/op            1504 B/op         29 allocs/op
BenchmarkE2EGocqlxGet              20000             95722 ns/op            2128 B/op         33 allocs/op
BenchmarkE2EGocqlSelect             1000           1792469 ns/op           43595 B/op        921 allocs/op
BenchmarkE2EGocqlxSelect            1000           1839574 ns/op           36986 B/op        927 allocs/op

See the benchmark in benchmark_test.go.

License

Copyright (C) 2017 ScyllaDB

This project is distributed under the Apache 2.0 license. See the LICENSE file for details. It contains software from:

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!