gocqlx/README.md

gocqlx

Package gocqlx is a Scylla / Cassandra productivity toolkit for gocql. It's similar to what sqlx is to database/sql.

It contains wrappers over gocql types that provide convenience methods which are useful in the development of database driven applications. Under the hood it uses sqlx/reflectx package so sqlx models will also work with gocqlx.

Installation

go get github.com/scylladb/gocqlx

Features

Fast, boilerplate free and flexible SELECTS, INSERTS, UPDATES and DELETES.

type Person struct {
	FirstName string  // no need to add `db:"first_name"` etc.
	LastName  string
	Email     []string
}

p := &Person{
	"Patricia",
	"Citizen",
	[]string{"patricia.citzen@gocqlx_test.com"},
}

// Insert
{
    stmt, names := qb.Insert("person").Columns("first_name", "last_name", "email").ToCql()
    q := gocqlx.Query(session.Query(stmt), names)

    if err := q.BindStruct(p).Exec(); err != nil {
        log.Fatal(err)
    }
}

// Insert with TTL
{
    stmt, names := qb.Insert("person").Columns("first_name", "last_name", "email").TTL().ToCql()
    q := gocqlx.Query(session.Query(stmt), names)

    if err := q.BindStructMap(p, qb.M{"_ttl": qb.TTL(86400 * time.Second)}).Exec(); err != nil {
        log.Fatal(err)
    }
}

// Update
{
    p.Email = append(p.Email, "patricia1.citzen@gocqlx_test.com")

    stmt, names := qb.Update("person").Set("email").Where(qb.Eq("first_name"), qb.Eq("last_name")).ToCql()
    q := gocqlx.Query(session.Query(stmt), names)

    if err := q.BindStruct(p).Exec(); err != nil {
        log.Fatal(err)
    }
}

// Select
{
    stmt, names := qb.Select("person").Where(qb.In("first_name")).ToCql()
    q := gocqlx.Query(session.Query(stmt), names)

    q.BindMap(qb.M{"first_name": []string{"Patricia", "John"}})
    if err := q.Err(); err != nil {
        log.Fatal(err)
    }

    var people []Person
    if err := gocqlx.Select(&people, q.Query); err != nil {
        log.Fatal("select:", err)
    }
    log.Println(people)

    // [{Patricia Citizen [patricia.citzen@com patricia1.citzen@com]} {John Doe [johndoeDNE@gmail.net]}]
}

For more details see example test.

Performance

Gocqlx is fast, below is a benchmark result comparing gocqlx to raw gocql on my machine, see the benchmark here.

For query binding gocqlx is faster as it does not require parameter rewriting while binding. For get and insert the performance is comparable.

BenchmarkE2EGocqlInsert-4          10000            227031 ns/op            2628 B/op         59 allocs/op
BenchmarkE2EGocqlxInsert-4         10000            115548 ns/op            1556 B/op         34 allocs/op
BenchmarkE2EGocqlGet-4             10000            135755 ns/op            1970 B/op         55 allocs/op
BenchmarkE2EGocqlxGet-4            10000            123814 ns/op            2323 B/op         58 allocs/op
BenchmarkE2EGocqlSelect-4            500           2462437 ns/op           34627 B/op        946 allocs/op
BenchmarkE2EGocqlxSelect-4           500           2561537 ns/op           28875 B/op        957 allocs/op

Gocqlx comes with automatic snake case support for field names and does not require manual tagging. This is also fast, below is a comparison to strings.ToLower function (sqlx default).

BenchmarkSnakeCase-4            10000000               124 ns/op              32 B/op          2 allocs/op
BenchmarkToLower-4              100000000               57.9 ns/op             0 B/op          0 allocs/op

Building queries is fast and low on allocations too.

BenchmarkCmp-4                   3000000               464 ns/op             112 B/op          3 allocs/op
BenchmarkDeleteBuilder-4        10000000               214 ns/op             112 B/op          2 allocs/op
BenchmarkInsertBuilder-4        20000000               103 ns/op              64 B/op          1 allocs/op
BenchmarkSelectBuilder-4        10000000               214 ns/op             112 B/op          2 allocs/op
BenchmarkUpdateBuilder-4        10000000               212 ns/op             112 B/op          2 allocs/op

Enyoy!