diff --git a/README.md b/README.md index f970d50..1ba1584 100644 --- a/README.md +++ b/README.md @@ -13,51 +13,61 @@ hood it uses `sqlx/reflectx` package so `sqlx` models will also work with `gocql ## Features -* Flexible `SELECT`, `INSERT`, `UPDATE` `DELETE` and `BATCH` query building using a DSL -* Support for named parameters (:identifier) in queries +* Builders for `SELECT`, `INSERT`, `UPDATE` `DELETE` and `BATCH` +* Queries with named parameters (:identifier) support * Binding parameters form struct or map -* Scanning results into structs +* Scanning results into structs and slices +* Automatic query releasing * Fast! -Example, see [full example here](https://github.com/scylladb/gocqlx/blob/master/example_test.go) +## Example ```go type Person struct { - FirstName string // no need to add `db:"first_name"` etc. - LastName string - Email []string + 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 +// Insert with query parameters bound from 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 { + q := gocqlx.Query(session.Query(stmt), names).BindStruct(p) + + if err := q.ExecRelease(); err != nil { t.Fatal(err) } } -// Get +// Get first result into a struct. { - q := session.Query("SELECT * FROM gocqlx_test.person WHERE first_name=?", "Patricia") + 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", + }) var p Person - if err := gocqlx.Get(&p, q); err != nil { + if err := gocqlx.Get(&p, q.Query); err != nil { t.Fatal("get:", err) } + t.Log(p) + // {Patricia Citizen [patricia.citzen@gocqlx_test.com patricia1.citzen@gocqlx_test.com]} } -// Select +// Select, load all results into a slice. { stmt, names := qb.Select("gocqlx_test.person"). Where(qb.In("first_name")). @@ -73,10 +83,10 @@ p := &Person{ } t.Log(people) - // [{Ian Citizen [igy.citzen@gocqlx_test.com]} {Igy Citizen [ian.citzen@gocqlx_test.com]} {Patricia Citizen [patricia.citzen@gocqlx_test.com patricia1.citzen@gocqlx_test.com]}] + // [{Patricia Citizen [patricia.citzen@gocqlx_test.com patricia1.citzen@gocqlx_test.com]} {Igy Citizen [igy.citzen@gocqlx_test.com]} {Ian Citizen [ian.citzen@gocqlx_test.com]}] } -// Batch +// Batch insert two rows in a single query, advanced struct binding. { i := qb.Insert("gocqlx_test.person").Columns("first_name", "last_name", "email") @@ -84,31 +94,33 @@ p := &Person{ Add("a.", i). Add("b.", i). ToCql() - q := gocqlx.Query(session.Query(stmt), names) - b := struct { + batch := struct { A Person B Person }{ A: Person{ "Igy", "Citizen", - []string{"ian.citzen@gocqlx_test.com"}, + []string{"igy.citzen@gocqlx_test.com"}, }, B: Person{ "Ian", "Citizen", - []string{"igy.citzen@gocqlx_test.com"}, + []string{"ian.citzen@gocqlx_test.com"}, }, } - err := q.BindStruct(&b).ExecRelease() - if err != nil { + q := gocqlx.Query(session.Query(stmt), names).BindStruct(&batch) + + if err := q.ExecRelease(); err != nil { t.Fatal(err) } } ``` +See more examples in [example_test.go](https://github.com/scylladb/gocqlx/blob/master/example_test.go). + ## Performance Gocqlx is fast, this is a benchmark result comparing `gocqlx` to raw `gocql` @@ -124,7 +136,7 @@ BenchmarkE2EGocqlSelect-4 30000 2588562 ns/op 34605 BenchmarkE2EGocqlxSelect-4 30000 2637187 ns/op 27718 B/op 951 allocs/op ``` -See the [benchmark here](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). ## Notice diff --git a/example_test.go b/example_test.go index 4e9f963..39a82da 100644 --- a/example_test.go +++ b/example_test.go @@ -40,35 +40,36 @@ func TestExample(t *testing.T) { []string{"patricia.citzen@gocqlx_test.com"}, } - // Insert + // Insert with query parameters bound from struct. { 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 { + q := gocqlx.Query(session.Query(stmt), names).BindStruct(p) + + if err := q.ExecRelease(); err != nil { t.Fatal(err) } } - // Insert with TTL + // Insert with query parameters bound from struct extended with a map. { stmt, names := qb.Insert("gocqlx_test.person"). Columns("first_name", "last_name", "email"). TTL(). ToCql() - err := gocqlx.Query(session.Query(stmt), names).BindStructMap(p, qb.M{ + q := gocqlx.Query(session.Query(stmt), names).BindStructMap(p, qb.M{ "_ttl": qb.TTL(86400 * time.Second), - }).ExecRelease() + }) - if err != nil { + if err := q.ExecRelease(); err != nil { t.Fatal(err) } } - // Update + // Easy update with all parameters bound from struct. { p.Email = append(p.Email, "patricia1.citzen@gocqlx_test.com") @@ -77,13 +78,14 @@ func TestExample(t *testing.T) { Where(qb.Eq("first_name"), qb.Eq("last_name")). ToCql() - err := gocqlx.Query(session.Query(stmt), names).BindStruct(p).ExecRelease() - if err != nil { + q := gocqlx.Query(session.Query(stmt), names).BindStruct(p) + + if err := q.ExecRelease(); err != nil { t.Fatal(err) } } - // Batch + // Batch insert two rows in a single query, advanced struct binding. { i := qb.Insert("gocqlx_test.person").Columns("first_name", "last_name", "email") @@ -91,36 +93,42 @@ func TestExample(t *testing.T) { Add("a.", i). Add("b.", i). ToCql() - q := gocqlx.Query(session.Query(stmt), names) - b := struct { + batch := struct { A Person B Person }{ A: Person{ "Igy", "Citizen", - []string{"ian.citzen@gocqlx_test.com"}, + []string{"igy.citzen@gocqlx_test.com"}, }, B: Person{ "Ian", "Citizen", - []string{"igy.citzen@gocqlx_test.com"}, + []string{"ian.citzen@gocqlx_test.com"}, }, } - err := q.BindStruct(&b).ExecRelease() - if err != nil { + q := gocqlx.Query(session.Query(stmt), names).BindStruct(&batch) + + if err := q.ExecRelease(); err != nil { t.Fatal(err) } } - // Get + // Get first result into a struct. { - q := session.Query("SELECT * FROM gocqlx_test.person WHERE first_name=?", "Patricia") + 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", + }) var p Person - if err := gocqlx.Get(&p, q); err != nil { + if err := gocqlx.Get(&p, q.Query); err != nil { t.Fatal("get:", err) } @@ -128,7 +136,7 @@ func TestExample(t *testing.T) { // {Patricia Citizen [patricia.citzen@gocqlx_test.com patricia1.citzen@gocqlx_test.com]} } - // Select + // Select, load all results into a slice. { stmt, names := qb.Select("gocqlx_test.person"). Where(qb.In("first_name")). @@ -144,42 +152,50 @@ func TestExample(t *testing.T) { } t.Log(people) - // [{Ian Citizen [igy.citzen@gocqlx_test.com]} {Igy Citizen [ian.citzen@gocqlx_test.com]} {Patricia Citizen [patricia.citzen@gocqlx_test.com patricia1.citzen@gocqlx_test.com]}] + // [{Patricia Citizen [patricia.citzen@gocqlx_test.com patricia1.citzen@gocqlx_test.com]} {Igy Citizen [igy.citzen@gocqlx_test.com]} {Ian Citizen [ian.citzen@gocqlx_test.com]}] } - // Named queries, using `:name` as the bindvar. + // Easy token based pagination. { - // compile query to valid gocqlx query and list of named parameters + p := &Person{ + "Ian", + "Citizen", + []string{"ian.citzen@gocqlx_test.com"}, + } + + stmt, names := qb.Select("gocqlx_test.person"). + Where(qb.Token("first_name").Gt()). + Limit(10). + ToCql() + + q := gocqlx.Query(session.Query(stmt), names).BindStruct(p) + + var people []Person + if err := gocqlx.Select(&people, q.Query); err != nil { + t.Fatal("select:", err) + } + + t.Log(people) + // [{Patricia Citizen [patricia.citzen@gocqlx_test.com patricia1.citzen@gocqlx_test.com]} {Igy Citizen [igy.citzen@gocqlx_test.com]}] + } + + // Named query compilation. + { + 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("compile:", err) } - q := gocqlx.Query(session.Query(stmt), names) - // bind named parameters from a struct - { - p := &Person{ - "Jane", - "Citizen", - []string{"jane.citzen@gocqlx_test.com"}, - } + q := gocqlx.Query(session.Query(stmt), names).BindStruct(p) - if err := q.BindStruct(p).Exec(); err != nil { - t.Fatal(err) - } - } - - // bind named parameters from a map - { - m := map[string]interface{}{ - "first_name": "Bin", - "last_name": "Smuth", - "email": []string{"bensmith@allblacks.nz"}, - } - - if err := q.BindMap(m).Exec(); err != nil { - t.Fatal(err) - } + if err := q.ExecRelease(); err != nil { + t.Fatal(err) } } } diff --git a/qb/cmp.go b/qb/cmp.go index 3c7f21e..35edcb5 100644 --- a/qb/cmp.go +++ b/qb/cmp.go @@ -1,6 +1,11 @@ package qb -import "bytes" +// Functions reference: +// http://cassandra.apache.org/doc/latest/cql/functions.html + +import ( + "bytes" +) // op specifies Cmd operation type. type op byte @@ -19,12 +24,54 @@ const ( type Cmp struct { op op column string - name string + fn string + names []string } -func (cmp Cmp) writeCql(cql *bytes.Buffer) string { - cql.WriteString(cmp.column) - switch cmp.op { +// Func wraps comparator value with a custom function, fn is a function name, +// names are function arguments' bind names. For instance function: +// +// CREATE FUNCTION somefunction(somearg int, anotherarg text) +// +// can be used like this: +// +// stmt, names := qb.Select("table"). +// Where(qb.Eq("t").Func("somefunction", "somearg", "anotherarg")). +// ToCql() +// +// q := gocqlx.Query(session.Query(stmt), names).BindMap(qb.M{ +// "somearg": 1, +// "anotherarg": "text", +// }) +func (c Cmp) Func(fn string, names ...string) Cmp { + c.fn = fn + c.names = names + return c +} + +// MinTimeuuid sets minTimeuuid(?) compare value. +func (c Cmp) MinTimeuuid(name string) Cmp { + return c.Func("minTimeuuid", name) +} + +// MaxTimeuuid sets maxTimeuuid(?) compare value. +func (c Cmp) MaxTimeuuid(name string) Cmp { + return c.Func("maxTimeuuid", name) +} + +// Now sets now() compare value. +func (c Cmp) Now() Cmp { + return c.Func("now") +} + +// Token sets Token(?,?...) compare value. +func (c Cmp) Token(names ...string) Cmp { + return c.Func("token", names...) +} + +func (c Cmp) writeCql(cql *bytes.Buffer) (names []string) { + cql.WriteString(c.column) + switch c.op { case eq: cql.WriteByte('=') case lt: @@ -42,9 +89,23 @@ func (cmp Cmp) writeCql(cql *bytes.Buffer) string { case cnt: cql.WriteString(" CONTAINS ") } - cql.WriteByte('?') - return cmp.name + if c.fn == "" { + cql.WriteByte('?') + if c.names == nil { + names = append(names, c.column) + } else { + names = append(names, c.names...) + } + } else { + cql.WriteString(c.fn) + cql.WriteByte('(') + placeholders(cql, len(c.names)) + cql.WriteByte(')') + names = append(names, c.names...) + } + + return } // Eq produces column=?. @@ -52,7 +113,6 @@ func Eq(column string) Cmp { return Cmp{ op: eq, column: column, - name: column, } } @@ -61,7 +121,7 @@ func EqNamed(column, name string) Cmp { return Cmp{ op: eq, column: column, - name: name, + names: []string{name}, } } @@ -70,7 +130,6 @@ func Lt(column string) Cmp { return Cmp{ op: lt, column: column, - name: column, } } @@ -79,7 +138,7 @@ func LtNamed(column, name string) Cmp { return Cmp{ op: lt, column: column, - name: name, + names: []string{name}, } } @@ -88,7 +147,6 @@ func LtOrEq(column string) Cmp { return Cmp{ op: leq, column: column, - name: column, } } @@ -97,7 +155,7 @@ func LtOrEqNamed(column, name string) Cmp { return Cmp{ op: leq, column: column, - name: name, + names: []string{name}, } } @@ -106,7 +164,6 @@ func Gt(column string) Cmp { return Cmp{ op: gt, column: column, - name: column, } } @@ -115,7 +172,7 @@ func GtNamed(column, name string) Cmp { return Cmp{ op: gt, column: column, - name: name, + names: []string{name}, } } @@ -124,7 +181,6 @@ func GtOrEq(column string) Cmp { return Cmp{ op: geq, column: column, - name: column, } } @@ -133,7 +189,7 @@ func GtOrEqNamed(column, name string) Cmp { return Cmp{ op: geq, column: column, - name: name, + names: []string{name}, } } @@ -142,7 +198,6 @@ func In(column string) Cmp { return Cmp{ op: in, column: column, - name: column, } } @@ -151,7 +206,7 @@ func InNamed(column, name string) Cmp { return Cmp{ op: in, column: column, - name: name, + names: []string{name}, } } @@ -160,7 +215,6 @@ func Contains(column string) Cmp { return Cmp{ op: cnt, column: column, - name: column, } } @@ -169,7 +223,7 @@ func ContainsNamed(column, name string) Cmp { return Cmp{ op: cnt, column: column, - name: name, + names: []string{name}, } } @@ -177,7 +231,7 @@ type cmps []Cmp func (cs cmps) writeCql(cql *bytes.Buffer) (names []string) { for i, c := range cs { - names = append(names, c.writeCql(cql)) + names = append(names, c.writeCql(cql)...) if i < len(cs)-1 { cql.WriteString(" AND ") } diff --git a/qb/cmp_test.go b/qb/cmp_test.go index d0870eb..7daa619 100644 --- a/qb/cmp_test.go +++ b/qb/cmp_test.go @@ -11,77 +11,106 @@ func TestCmp(t *testing.T) { table := []struct { C Cmp S string - N string + N []string }{ + // Basic comparators { C: Eq("eq"), S: "eq=?", - N: "eq", - }, - { - C: EqNamed("eq", "name"), - S: "eq=?", - N: "name", + N: []string{"eq"}, }, { C: Lt("lt"), S: "lt?", - N: "gt", - }, - { - C: GtNamed("gt", "name"), - S: "gt>?", - N: "name", + N: []string{"gt"}, }, { C: GtOrEq("gt"), S: "gt>=?", - N: "gt", - }, - { - C: GtOrEqNamed("gt", "name"), - S: "gt>=?", - N: "name", + N: []string{"gt"}, }, { C: In("in"), S: "in IN ?", - N: "in", - }, - { - C: InNamed("in", "name"), - S: "in IN ?", - N: "name", + N: []string{"in"}, }, { C: Contains("cnt"), S: "cnt CONTAINS ?", - N: "cnt", + N: []string{"cnt"}, + }, + + // Custom bind names + { + C: EqNamed("eq", "name"), + S: "eq=?", + N: []string{"name"}, + }, + { + C: LtNamed("lt", "name"), + S: "lt?", + N: []string{"name"}, + }, + { + C: GtOrEqNamed("gt", "name"), + S: "gt>=?", + N: []string{"name"}, + }, + { + C: InNamed("in", "name"), + S: "in IN ?", + N: []string{"name"}, }, { C: ContainsNamed("cnt", "name"), S: "cnt CONTAINS ?", - N: "name", + N: []string{"name"}, + }, + + // Functions + { + C: Eq("eq").Func("fn", "arg0", "arg1"), + S: "eq=fn(?,?)", + N: []string{"arg0", "arg1"}, + }, + { + C: Eq("eq").MaxTimeuuid("arg0"), + S: "eq=maxTimeuuid(?)", + N: []string{"arg0"}, + }, + { + C: Eq("eq").MinTimeuuid("arg0"), + S: "eq=minTimeuuid(?)", + N: []string{"arg0"}, + }, + { + C: Eq("eq").Now(), + S: "eq=now()", + }, + { + C: Eq("eq").Token("arg0", "arg1"), + S: "eq=token(?,?)", + N: []string{"arg0", "arg1"}, }, } diff --git a/qb/token.go b/qb/token.go new file mode 100644 index 0000000..dc32cc1 --- /dev/null +++ b/qb/token.go @@ -0,0 +1,114 @@ +package qb + +import ( + "fmt" + "strings" +) + +// Token creates a new TokenBuilder. +func Token(columns ...string) TokenBuilder { + return TokenBuilder(columns) +} + +// TokenBuilder helps implement pagination using token function. +type TokenBuilder []string + +// Eq produces token(column)=token(?). +func (t TokenBuilder) Eq() Cmp { + return Cmp{ + op: eq, + fn: "token", + column: fmt.Sprint("token(", strings.Join(t, ","), ")"), + names: t, + } +} + +// EqNamed produces token(column)=token(?) with a custom parameter name. +func (t TokenBuilder) EqNamed(names ...string) Cmp { + return Cmp{ + op: eq, + fn: "token", + column: fmt.Sprint("token(", strings.Join(t, ","), ")"), + names: names, + } +} + +// Lt produces token(column)token(?). +func (t TokenBuilder) Gt() Cmp { + return Cmp{ + op: gt, + fn: "token", + column: fmt.Sprint("token(", strings.Join(t, ","), ")"), + names: t, + } +} + +// GtNamed produces token(column)>token(?) with a custom parameter name. +func (t TokenBuilder) GtNamed(names ...string) Cmp { + return Cmp{ + op: gt, + fn: "token", + column: fmt.Sprint("token(", strings.Join(t, ","), ")"), + names: names, + } +} + +// GtOrEq produces token(column)>=token(?). +func (t TokenBuilder) GtOrEq() Cmp { + return Cmp{ + op: geq, + fn: "token", + column: fmt.Sprint("token(", strings.Join(t, ","), ")"), + names: t, + } +} + +// GtOrEqNamed produces token(column)>=token(?) with a custom parameter name. +func (t TokenBuilder) GtOrEqNamed(names ...string) Cmp { + return Cmp{ + op: geq, + fn: "token", + column: fmt.Sprint("token(", strings.Join(t, ","), ")"), + names: names, + } +} diff --git a/qb/token_test.go b/qb/token_test.go new file mode 100644 index 0000000..58146fc --- /dev/null +++ b/qb/token_test.go @@ -0,0 +1,82 @@ +package qb + +import ( + "bytes" + "testing" + + "github.com/google/go-cmp/cmp" +) + +func TestToken(t *testing.T) { + table := []struct { + C Cmp + S string + N []string + }{ + // Basic comparators + { + C: Token("a", "b").Eq(), + S: "token(a,b)=token(?,?)", + N: []string{"a", "b"}, + }, + { + C: Token("a", "b").Lt(), + S: "token(a,b)token(?,?)", + N: []string{"a", "b"}, + }, + { + C: Token("a", "b").GtOrEq(), + S: "token(a,b)>=token(?,?)", + N: []string{"a", "b"}, + }, + + // Custom bind names + { + C: Token("a", "b").EqNamed("c", "d"), + S: "token(a,b)=token(?,?)", + N: []string{"c", "d"}, + }, + { + C: Token("a", "b").LtNamed("c", "d"), + S: "token(a,b)token(?,?)", + N: []string{"c", "d"}, + }, + { + C: Token("a", "b").GtOrEqNamed("c", "d"), + S: "token(a,b)>=token(?,?)", + N: []string{"c", "d"}, + }, + } + + buf := bytes.Buffer{} + for _, test := range table { + buf.Reset() + name := test.C.writeCql(&buf) + if diff := cmp.Diff(test.S, buf.String()); diff != "" { + t.Error(diff) + } + if diff := cmp.Diff(test.N, name); diff != "" { + t.Error(diff) + } + } +}