Structable: Struct-Table Mapping for Go
Warning: This is the Structable 4 development branch. For a stable
release, use version 3.1.0. Structable development happens very slowly.
This library provides basic struct-to-table mapping for Go.
It is based on the Squirrel library.
What It Does
Structable maps a struct (Record) to a database table via a
structable.Recorder. It is intended to be used as a back-end tool for
building systems like Active Record mappers.
It is designed to satisfy a CRUD-centered record management system,
filling the following contract:
type Recorder interface {
Bind(string, Record) Recorder // link struct to table
Interface() interface{} // Get the struct that has been linked
Insert() error // INSERT just one record
Update() error // UPDATE just one record
Delete() error // DELETE just one record
Exists() (bool, error) // Check for just one record
ExistsWhere(cond interface{}, args ...interface{}) (bool, error)
Load() error // SELECT just one record
LoadWhere(cond interface{}, args ...interface{}) error // Alternate Load()
}
Squirrel already provides the ability to perform more complicated
operations.
How To Install It
The usual way...
$ glide get github.com/Masterminds/structable
$ # or...
$ go get github.com/Masterminds/structable
And import it via:
import "github.com/Masterminds/structable"
How To Use It
Structable works by mapping a struct to columns in a database.
To annotate a struct, you do something like this:
type Stool struct {
Id int `stbl:"id, PRIMARY_KEY, AUTO_INCREMENT"`
Legs int `stbl:"number_of_legs"`
Material string `stbl:"material"`
Ignored string // will not be stored. No tag.
}
To manage instances of this struct, you do something like this:
stool := new(Stool)
stool.Material = "Wood"
db := getDb() // Get a sql.Db. You're on the hook to do this part.
// Create a new structable.Recorder and tell it to
// bind the given struct as a row in the given table.
r := structable.New(db, "mysql").Bind("test_table", stool)
// This will insert the stool into the test_table.
err := r.Insert()
And of course you have Load(), Update(), Delete() and so on.
The target use case for Structable is to use it as a backend for an
Active Record pattern. An example of this can be found in the
structable_test.go file
Most of Structable focuses on individual objects, but there are helpers
for listing objects:
// Get a list of things that have the same type as object.
stool := new(Stool)
items, err := structable.List(stool, offset, limit)
// Customize a list of things that have the same type as object.
fn = func(object structable.Describer, sql squirrel.SelectBuilder) (squirrel.SelectBuilder, error) {
return sql.Limit(10), nil
}
items, err := structable.ListWhere(stool, fn)
For example, here is a function that uses ListWhere to get collection
of definitions from a table described in a struct named Table:
func (s *SchemaInfo) Tables() ([]*Table, error) {
// Bind a new recorder. We use an empty object just to get the field
// data for that struct.
t := &Table{}
st := structable.New(s.Queryer, s.Driver).Bind(t.TableName(), t)
// We want to return no more than 10 of these.
fn := func(d structable.Describer, q squirrel.SelectBuilder) (squirrel.SelectBuilder, error) {
return q.Limit(10), nil
}
// Fetch a list of Table structs.
items, err := structable.ListWhere(st, fn)
if err != nil {
return []*Table{}, err
}
// Because we get back a []Recorder, we need to get the original data
// back out. We have to manually convert it back to its real type.
tables := make([]*Table, len(items))
for i, item := range items {
tables[i] = item.Interface().(*Table)
}
return tables, nil
}
Tested On
- MySQL (5.5)
- PostgreSQL (9.3, 9.4, 9.6)
- SQLite 3
What It Does Not Do
It does not...
- Create or manage schemas.
- Guess or enforce table or column names. (You have to tell it how to
map.) - Provide relational mapping.
- Handle bulk operations (use Squirrel for that)
LICENSE
This software is licensed under an MIT-style license. See LICENSE.txt