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.

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 (see more)
• Database migrations (see more)
• Fast!

Example

// Field names are converted to camel case by default, no need to add
// `db:"first_name"`, if you want to disable a filed add `db:"-"` tag.
type Person struct {
    FirstName string
    LastName  string
    Email     []string
}

// Bind query parameters from a struct.
{
    p := Person{
        "Patricia",
        "Citizen",
        []string{"patricia.citzen@gocqlx_test.com"},
    }

    stmt, names := qb.Insert("gocqlx_test.person").
        Columns("first_name", "last_name", "email").
        ToCql()

    err := gocqlx.Query(session.Query(stmt), names).BindStruct(&p).ExecRelease()
    if err != nil {
        t.Fatal(err)
    }
}

// Load the first result into a struct.
{
    stmt, names := qb.Select("gocqlx_test.person").
        Where(qb.Eq("first_name")).
        ToCql()

    var p Person

    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.
{
    stmt, names := qb.Select("gocqlx_test.person").
        Where(qb.In("first_name")).
        ToCql()

    var people []Person

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

// Use named query parameters.
{
    p := &Person{
        "Jane",
        "Citizen",
        []string{"jane.citzen@gocqlx_test.com"},
    }

    stmt, names, err := gocqlx.CompileNamedQuery([]byte("INSERT INTO gocqlx_test.person (first_name, last_name, email) VALUES (:first_name, :last_name, :email)"))
    if err != nil {
        t.Fatal(err)
    }

    err = gocqlx.Query(session.Query(stmt), names).BindStruct(p).ExecRelease()
    if err != nil {
        t.Fatal(err)
    }
}

See more examples in 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:

• 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!