gocqlx

README

gocqlx (Fork with CamelCase Column Name Support)

This is a fork of the original gocqlx library, specifically modified to support camelCase column names in the qb package.

Overview

gocqlx is a popular Go library that provides a set of extensions to the gocql driver for Apache Cassandra and ScyllaDB. It simplifies database interactions by offering a more ergonomic API for query building and execution.

This fork extends the functionality of the qb package to support camelCase column names, which is a common naming convention in many projects. The original library assumes snake_case column names by default, which may not align with your project's naming conventions.

Changes in This Fork

The main change in this fork is the modification of the qb package to handle camelCase column names. This allows you to use column names like userName, createdAt, or isActive directly in your queries without needing to manually convert them to snake_case.

Features

Subpackages provide additional functionality:

• CQL query builder (package qb)

Installation

git clone git@github.com:scylladb/gocqlx.git
cd gocqlx/cmd/schemagen/
go install .

Getting started

Wrap gocql Session:

// 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 {
	t.Fatal(err)
}

Specify table model:

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

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 {
	t.Fatal(err)
}

Load a single row to a struct:

p := Person{
	"Michał",
	"Matczuk",
	nil, // no email
}
q := session.Query(personTable.Get()).BindStruct(p)
if err := q.GetRelease(&p); err != nil {
	t.Fatal(err)
}
t.Log(p)
// stdout: {Michał Matczuk [michal@scylladb.com]}

Load all rows in to a slice:

var people []Person
q := session.Query(personTable.Select()).BindMap(qb.M{"first_name": "Michał"})
if err := q.SelectRelease(&people); err != nil {
	t.Fatal(err)
}
t.Log(people)
// stdout: [{Michał Matczuk [michal@scylladb.com]}]

Generating table metadata with schemagen

Installation

go get -u "github.com/sawyer523/gocqlx/cmd/schemagen"

Usage:

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:

schemagen -cluster="127.0.0.1:9042" -keyspace="examples" -output="models" -pkgname="models"

Generates models/models.go as follows:

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

License

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!

Documentation

Overview

Package gocqlx makes working with Scylla easy and error prone without sacrificing performance. It’s inspired by Sqlx, a tool for working with SQL databases, but it goes beyond what Sqlx provides.

For more details consult README.