repository·master·Indexed 21 days ago
https://github.com/scylladb/gocqlxAn extension for the gocql driver providing advanced features for ScyllaDB and Cassandra, including schema generation via the schemagen tool, migration management, and a CQL query builder (qb). GocqlX v3 exclusively supports the scylladb/gocql driver and provides utilities for wrapping sessions, binding structs to queries, and managing atomic batch operations.
The qb package provides tools to programmatically build CQL statements. Instead of writing raw strings, you use builders to generate a CQL statement string and a corresponding list of named parameters. These generated parameters can then be passed to gocqlx for binding and execution.
Supported CQL commands include:
SELECTINSERTUPDATEDELETEBATCHThe migrate tool manages database schema changes by reading CQL files from a flat directory.
Key behaviors:
schemagen is a tool that inspects a ScyllaDB keyspace and generates Go code containing table.Metadata and table.New definitions for your tables. This automates the creation of table models.
go get -u "github.com/scylladb/gocqlx/v3/cmd/schemagen"-cluster string: A comma-separated list of host:port tuples (default 127.0.0.1).-keyspace string: The keyspace to inspect (required).-output string: The name of the folder to output to (default models).-pkgname string: The name of the generated Go package (default models).To inspect the examples keyspace and output to a folder named models with package name models:
schemagen -cluster="127.0.0.1:9042" -keyspace="examples" -output="models" -pkgname="models"Because schemagen contains a replace directive in its go.mod, it cannot be installed via go install directly from a remote URL. You must clone the repository and install it manually from the local source.
Follow these steps:
gocqlx repository.cmd/schemagen directory.go install .git clone git@github.com:scylladb/gocqlx.git
cd gocqlx/cmd/schemagen/
go install .Add GocqlX to your Go module using go get.
Note: Starting with v3.0.0, GocqlX exclusively supports the scylladb/gocql driver. You must include a replace directive in your go.mod to point to the ScyllaDB fork of gocql to ensure compatibility with ScyllaDB-specific extensions.
go get github.com/scylladb/gocqlx/v3To use GocqlX, you first wrap a standard gocql.Session using gocqlx.WrapSession.
Then, define your table metadata using table.Metadata and create a table object with table.New. For your data structures (structs), GocqlX automatically maps field names to snake_case in the database. You can skip fields by using the db:"-" tag or by making the field unexported.
import (
"fmt"
"log"
"github.com/gocql/gocql"
"github.com/scylladb/gocqlx/v3"
"github.com/scylladb/gocqlx/v3/qb"
"github.com/scylladb/gocqlx/v3/table"
)
// 1. Wrap gocql Session
cluster := gocql.NewCluster(hosts...)
session, err := gocqlx.WrapSession(cluster.CreateSession())
if err != nil {
log.Fatal(err)
}
defer session.Close()
// 2. Specify table model
var personMetadata = table.Metadata{
Name: "person",
Columns: []string{"first_name", "last_name", "email"},
PartKey: []string{"first_name"},
SortKey: []string{"last_name"},
}
var personTable = table.New(personMetadata)
type Person struct {
FirstName string
LastName string
Email []string
HairColor string `db:"-"` // exported and skipped
eyeColor string // unexported also skipped
}The behavior of Get and Select depends on the type of the dest argument:
Iterx uses StructScan to map columns to struct fields by name.string, int, etc.) or a type implementing gocql.Unmarshaler/gocql.UDTUnmarshaler, the result row must contain exactly one column.Select(dest), dest must be a pointer to a slice. If the slice contains structs, StructScan is used for each row. If the slice contains other types, each row must have exactly one column.The schemagen tool handles complex CQL collection and composite types using the following logic:
set<T> and list<T> are mapped to Go slices: []T.map<K, V> is mapped to Go maps: map[K]V. Note that the key type K must be a comparable type.frozen<T> is unwrapped to its underlying type T.tuple<T1, T2, ...> is mapped to a Go struct with fields named Field1, Field2, etc. Tuples must be 'flat' (they cannot contain other nested tuples).[Name]UserType (where [Name] is the camelized version of the identifier).For every User-Defined Type (UDT) in your schema, schemagen generates a Go struct that embeds gocqlx.UDT. This allows the type to be used seamlessly within other structs or as standalone types in gocqlx queries.
Example generated structure:
type MyUserTypeUserType struct {
gocqlx.UDT
FieldName string `cql:"field_name"`
}When using schemagen, the tool generates both metadata objects and data structs.
TableName variable (of type table.Table) and a TableNameStruct struct.ViewName variable and a ViewNameStruct struct.Name_index variable and a Name_indexStruct struct.Each struct contains fields mapped from the database columns using mapScyllaToGoType and tagged with `cql:"column_name"`.
If you are using GocqlX v3.0.0 or newer, you must add a replace directive to your go.mod file to use the ScyllaDB fork of the gocql driver. This is required because GocqlX relies on ScyllaDB-specific extensions and bug fixes.
Example go.mod entry:
replace github.com/gocql/gocql => github.com/scylladb/gocql v1.16.0// 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.0The schemagen tool uses templates to generate Go code that maps ScyllaDB/Cassandra schema definitions to Go types and table.Metadata. The generated code provides two main components for every database object:
table.New(table.Metadata { ... }). This metadata defines the table name, columns, partition keys (PartKey), and clustering columns (SortKey). These are used by gocqlx to execute queries.TableNameStruct or TypeNameUserType) that represent the rows. These structs use cql struct tags to map Go fields to database columns. For User-Defined Types (UDTs), the generated struct embeds gocqlx.UDT.Note: Files generated by schemagen include a warning: // Code generated by "gocqlx/cmd/schemagen"; DO NOT EDIT.