gocqlx/README.md

# 🚀 GocqlX [![GoDoc](https://pkg.go.dev/badge/github.com/scylladb/gocqlx/v3.svg)](https://pkg.go.dev/github.com/scylladb/gocqlx/v3) [![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 makes working with Scylla easy and less error-prone.
It’s inspired by [Sqlx](https://github.com/jmoiron/sqlx), a tool for working with SQL databases, but it goes beyond what Sqlx provides.

## Compatibility

Versions of GocqlX prior to v3.0.0 are compatible with both [Apache Cassandra’s gocql](https://github.com/apache/cassandra-gocql-driver) and [ScyllaDB’s fork](https://github.com/scylladb/gocql).
However, starting with v3.0.0, GocqlX exclusively supports the scylladb/gocql driver.
If you are using GocqlX v3.0.0 or newer, you must ensure your `go.mod` includes a replace directive to point to ScyllaDB’s fork:

```go
// Use the latest version of scylladb/gocql; check for updates at https://github.com/scylladb/gocql/releases
replace github.com/gocql/gocql => github.com/scylladb/gocql v1.16.0
```

This is required because GocqlX relies on ScyllaDB-specific extensions and bug fixes introduced in the gocql fork. Attempting to use the standard gocql driver with GocqlX v3.0.0+ may lead to build or runtime issues.

## 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 GocqlX

Add GocqlX to your Go module:

```bash
go get github.com/scylladb/gocqlx/v3
```

## Installation schemagen

Unfortunately you can't install it via `go install`, since `go.mod` contains `replace` directive.
So, you have to check it out and install manually:
```bash
git clone git@github.com:scylladb/gocqlx.git
cd gocqlx/cmd/schemagen/
go install .
```

## Getting started

First, import the required packages:

```go
import (
	"fmt"
	"log"

	"github.com/gocql/gocql"
	"github.com/scylladb/gocqlx/v3"
	"github.com/scylladb/gocqlx/v3/qb"
	"github.com/scylladb/gocqlx/v3/table"
)
```

Wrap gocql Session:

```go
// 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 {
	log.Fatal(err)
}
defer session.Close()
```

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"},
}

// personTable allows for simple CRUD operations based on personMetadata.
var personTable = table.New(personMetadata)

// Person represents a row in person table.
// Field names are converted to snake case by default, no need to add special tags.
// A field will not be persisted by adding the `db:"-"` tag or making it unexported.
type Person struct {
	FirstName string
	LastName  string
	Email     []string
	HairColor string `db:"-"`  // exported and skipped
	eyeColor  string           // unexported also skipped
}
```

Bind data from a struct and insert a row:

```go
p := Person{
	"Michał",
	"Matczuk",
	[]string{"michal@scylladb.com"},
	"red",    // not persisted
	"hazel"   // not persisted
}
q := session.Query(personTable.Insert()).BindStruct(p)
if err := q.ExecRelease(); err != nil {
	log.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 {
	log.Fatal(err)
}
fmt.Println(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 {
	log.Fatal(err)
}
fmt.Println(people)
// stdout: [{Michał Matczuk [michal@scylladb.com]}]
```

## Generating table metadata with schemagen

Installation

```bash
go get -u "github.com/scylladb/gocqlx/v3/cmd/schemagen"
```

Usage:
```bash
schemagen [flags]

Flags:
  -cluster string
    	a comma-separated list of host:port tuples (default "127.0.0.1")
  -keyspace string
    	keyspace to inspect (required)
  -output string
    	the name of the folder to output to (default "models")
  -pkgname string
    	the name you wish to assign to your generated package (default "models") 
```

Example:

Running the following command for `examples` keyspace: 
```bash
schemagen -cluster="127.0.0.1:9042" -keyspace="examples" -output="models" -pkgname="models"
```

Generates `models/models.go` as follows:
```go
// Code generated by "gocqlx/cmd/schemagen"; DO NOT EDIT.

package models

import "github.com/scylladb/gocqlx/v3/table"

// Table models.
var (
	Playlists = table.New(table.Metadata{
		Name: "playlists",
		Columns: []string{
			"album",
			"artist",
			"id",
			"song_id",
			"title",
		},
		PartKey: []string{
			"id",
		},
		SortKey: []string{
			"title",
			"album",
			"artist",
		},
	})

	Songs = table.New(table.Metadata{
		Name: "songs",
		Columns: []string{
			"album",
			"artist",
			"data",
			"id",
			"tags",
			"title",
		},
		PartKey: []string{
			"id",
		},
		SortKey: []string{},
	})
)
```

## Examples

You can find lots of examples in [example_test.go](https://github.com/scylladb/gocqlx/blob/master/example_test.go).

Go and run them locally:

```bash
make run-scylla
make run-examples
```

## Training

The course [Using Scylla Drivers](https://university.scylladb.com/courses/using-scylla-drivers) in Scylla University explains how to use drivers in different languages to interact with a Scylla cluster. The lesson, [Golang and Scylla Part 3 - GoCQLX](https://university.scylladb.com/courses/using-scylla-drivers/lessons/golang-and-scylla-part-3-gocqlx/), goes over a sample application that, using GoCQLX, interacts with a three-node Scylla cluster. 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. [Scylla University](https://university.scylladb.com/) includes other training material and online courses which will help you become a Scylla NoSQL database expert.

## Performance

GocqlX performance is comparable to the raw `gocql` driver.
Below benchmark results running on my laptop.

```
BenchmarkBaseGocqlInsert            2392            427491 ns/op            7804 B/op         39 allocs/op
BenchmarkGocqlxInsert               2479            435995 ns/op            7803 B/op         39 allocs/op
BenchmarkBaseGocqlGet               2853            452384 ns/op            7309 B/op         35 allocs/op
BenchmarkGocqlxGet                  2706            442645 ns/op            7646 B/op         38 allocs/op
BenchmarkBaseGocqlSelect             747           1664365 ns/op           49415 B/op        927 allocs/op
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).

## License

Copyright (C) 2017 ScyllaDB

This project is distributed under the Apache 2.0 license. See the [LICENSE](https://github.com/scylladb/gocqlx/blob/master/LICENSE) file for details.
It contains software from:

* [gocql project](https://github.com/gocql/gocql), licensed under the BSD license
* [sqlx project](https://github.com/jmoiron/sqlx), 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!