gocqltable

README

#GoCqlTable

GoCqlTable is a wrapper around the GoCql-driver that seeks to simplify working with the Cassandra database in Golang projects.

The project consists of two packages you need to know about:

1. gocqltable (the base) – Contains wrapper objects for working with Keyspaces and Tables. Simplifies creating, dropping and querying. Returns rowset's as []interface{}, that should be type asserted to the row model struct.
2. recipes – Contains code that extends the table implementation by adding more functionality. The recipes. CRUD type implements a simple object relational mapper (ORM) that makes it simple to Insert/Update/Get/Delete, and for compound clustering theres even List/Range methods that allow you to filter your results on range columns.

Note: The project is very much in development, and may not be stable enough for production use. The API may change without notice.

Documentation

Examples of use

For extensive examples see the examples folder. The base-example shows you the base API. The CRUD example takes you through most of the ORM functionality.

For a quick taste (using recipes.CRUD):

// Generic initialization of gocql
c := gocql.NewCluster("127.0.0.1")
s, err := c.CreateSession()
if err != nil {
    log.Fatalln("Unable to open up a session with the Cassandra database (err=" + err.Error() + ")")
}

// Tell gocqltable to use this session object as the default for new objects
gocqltable.SetDefaultSession(s)


// Now we're ready to create our first keyspace. We start by getting a keyspace object
keyspace := gocqltable.NewKeyspace("gocqltable_test")

// Now lets create that in the database using the simple strategy and durable writes (true)
err = keyspace.Create(map[string]interface{}{
    "class": "SimpleStrategy",
    "replication_factor": 1,
}, true)
if err != nil { // If something went wrong we print the error and quit.
    log.Fatalln(err)
}


// Now that we have a very own keyspace to play with, lets create our first table.

// First we need a Row-object to base the table on. It will later be passed to the table wrapper
// to be used for returning row-objects as the answer to fetch requests.
type User struct{
    Email string // Our primary key
    Password string `password`     // Use Tags to rename fields
    Active bool     `cql:"active"` // If there are multiple tags, use `cql:""` to specify what the table column will be
    Created time.Time
}

// Let's define and instantiate a table object for our user table
userTable := struct{
    recipes.CRUD    // If you looked at the base example first, notice we replaced this line with the recipe
}{
    recipes.CRUD{ // Here we didn't replace, but rather wrapped the table object in our recipe, effectively adding more methods to the end API
        keyspace.NewTable(
            "users",            // The table name
            []string{"email"},  // Row keys
            nil,                // Range keys
            User{},             // We pass an instance of the user struct that will be used as a type template during fetches.
        ),
    },
}

// Lets create this table in our cassandra database
err = userTable.Create()
if err != nil {
    log.Fatalln(err)
}


// Now that we have a keyspace with a table in it: lets make a few rows! In the base example we had to write out the CQL manually, this time
// around, however, we can insert entire User objects.

// Lets instantiate a user object, set its values and insert it
user1 := User{
    Email: "1@example.com",
    Password: "123456",
    Active: true,
    Created: time.Now().UTC(),
}
err = userTable.Insert(user1)
if err != nil {
    log.Fatalln(err)
}


// With our database filled up with users, lets query it and print out the results (containing all users in the database).
rowset, err := userTable.List() // Our rowset variable is a "interface{}", and here we type assert it to a slice of pointers to "User"
for _, user := range rowset.([]*User) {
    fmt.Println(user)
}
if err != nil {
    log.Fatalln(err)
}


// You can also fetch a single row, obviously
row, err := userTable.Get("1@example.com")
if err != nil {
    log.Fatalln(err)
}
user := row.(*User)


// Lets update this user by changing his password
user.Password = "654321"
err = userTable.Update(user)
if err != nil {
    log.Fatalln(err)
}


// Lets delete user 1@example.com
err = userTable.Delete(user)
if err != nil {
    log.Fatalln(err)
}

// Lets clean up after ourselves by dropping the keyspace.
keyspace.Drop()

Documentation

Index

• func SetDefaultSession(s *gocql.Session)
• type Counter
• type Iterator
  • func (i *Iterator) Close() error
  • func (i *Iterator) Next() interface{}
  • func (i *Iterator) Range() <-chan interface{}
• type Keyspace
  • func NewKeyspace(name string) Keyspace
  • func (ks Keyspace) Create(replication map[string]interface{}, durableWrites bool) error
  • func (ks Keyspace) Drop() error
  • func (ks Keyspace) Name() string
  • func (ks Keyspace) NewTable(name string, rowKeys, rangeKeys []string, row interface{}) Table
  • func (ks Keyspace) Session() *gocql.Session
  • func (ks *Keyspace) SetSession(session *gocql.Session)
  • func (ks Keyspace) Tables() ([]string, error)
• type KeyspaceInterface
• type Query
  • func (q Query) Exec() error
  • func (q Query) Fetch() *Iterator
  • func (q Query) FetchRow() (interface{}, error)
• type Table
  • func (t Table) Create() error
  • func (t Table) CreateWithProperties(props ...string) error
  • func (t Table) Drop() error
  • func (t Table) Keyspace() Keyspace
  • func (t Table) Name() string
  • func (t Table) Query(statement string, values ...interface{}) Query
  • func (t Table) RangeKeys() []string
  • func (t Table) Row() interface{}
  • func (t Table) RowKeys() []string
• type TableInterface

Functions

func SetDefaultSession

func SetDefaultSession(s *gocql.Session)

Types

type Counter

type Counter int

type Iterator

type Iterator struct {
	// contains filtered or unexported fields
}

func (*Iterator) Close

func (i *Iterator) Close() error

func (*Iterator) Next

func (i *Iterator) Next() interface{}

func (*Iterator) Range

func (i *Iterator) Range() <-chan interface{}

type Keyspace

type Keyspace struct {
	// contains filtered or unexported fields
}

func NewKeyspace

func NewKeyspace(name string) Keyspace

func (Keyspace) Create

func (ks Keyspace) Create(replication map[string]interface{}, durableWrites bool) error

func (Keyspace) Drop

func (ks Keyspace) Drop() error

func (Keyspace) Name

func (ks Keyspace) Name() string

func (Keyspace) NewTable

func (ks Keyspace) NewTable(name string, rowKeys, rangeKeys []string, row interface{}) Table

func (Keyspace) Session

func (ks Keyspace) Session() *gocql.Session

func (*Keyspace) SetSession

func (ks *Keyspace) SetSession(session *gocql.Session)

func (Keyspace) Tables

func (ks Keyspace) Tables() ([]string, error)

type KeyspaceInterface

type KeyspaceInterface interface {
	Name() string
	Session() *gocql.Session
}

type Query

type Query struct {
	Statement string
	Values    []interface{}

	Table   Table
	Session *gocql.Session
}

func (Query) Exec

func (q Query) Exec() error

func (Query) Fetch

func (q Query) Fetch() *Iterator

func (Query) FetchRow

func (q Query) FetchRow() (interface{}, error)

type Table

type Table struct {
	// contains filtered or unexported fields
}

func (Table) Create

func (t Table) Create() error

func (Table) CreateWithProperties

func (t Table) CreateWithProperties(props ...string) error

func (Table) Drop

func (t Table) Drop() error

func (Table) Keyspace

func (t Table) Keyspace() Keyspace

func (Table) Name

func (t Table) Name() string

func (Table) Query

func (t Table) Query(statement string, values ...interface{}) Query

func (Table) RangeKeys

func (t Table) RangeKeys() []string

func (Table) Row

func (t Table) Row() interface{}

func (Table) RowKeys

func (t Table) RowKeys() []string

type TableInterface

type TableInterface interface {
	Create() error
	Drop() error
	Query(statement string, params ...interface{}) Query
	Name() string
	Keyspace() Keyspace
	RowKeys() []string
	RangeKeys() []string
	Row() interface{}
}