dynamis

README

Dynamis

Dynamis is a lightweight tool for working with DynamoDB via the aws-sdk. Its goal is to reduce some of the repetitive and cumbersome aspects of the API, rather than to abstract it.

Status: Dynamis is well tested, and seems to have a stable API, but is minimal in its scope. Please open an issue or pull request if you need funtionality that seems to be missing.

Example

Following is a simple example of writing and reading fields to DynamoDB, and how dynamis saves you some headaches.

// Initialize the item to write to DynamoDB
item := map[string]*dynamodb.AttributeValue{}

// Initialize a dyanmis.ValueWriter for convenience.
w := dynamis.NewValueWriter(item)
w.Str("user_id", u.UserID.String())

// Name could be empty, which DynamoDB doesn't allow. Dynamis
// doesn't add it to the map if the value is empty.
w.Str("name", u.Name)

// See below to define a custom reader to turn this back into a date.
w.Str("start_date", u.StartDate.Format(time.RFC822)

// Use the item like normal.
resp, err := db.PutItem(&dynamodb.PutItemInput{
  TableName:           aws.String(tableName),
  Item:                item,
})

Now read the record out. Dynamis lets us access fields without an excess of error handling, preferring to return a type's zero value over errors.

resp, err := db.GetItem(&dynamodb.GetItemInput{
  TableName: aws.String(tableName),
  Key: map[string]*dynamodb.AttributeValue{
    "user_id": {
      S: aws.String(id.String()),
    },
  },
})

// Initialize a ValueReader of the response item.
r := dynamis.NewValueReader(resp.Item)

// Define a custom reader for start_date to turn it back into a time.
r.Def("start_date", func(vr dynamis.ValueReader) interface{} {
  time, _ := time.Parse(time.RFC822, vr.Str("start_date"))
  return time // will be time.Time's zero value if error.
})

// Now read from the item. ValueReader handles missing keys, missing values, 
// etc, and returns a zero value instead.
user := &User{
  UserID: UserID(r.Str("user_id")),

  // Name could be missing but that's ok.
  Name: r.Str("name"),

  // We know that the Def() of start_date returns a Time, so typecasting is safe.
  StartDate: r.Get("start_date").(time.Time),
}

Author

Ryan Carver (ryan@ryancarver.com / @rcarver)

License

MIT

Documentation

Index

• func CheckRowCount(db *dynamodb.DynamoDB, tableName string) int
• func CheckRows(db *dynamodb.DynamoDB, tableName string) ([]Row, ValueDefiner)
• func Create(cfg *aws.Config, schema []Schema, abortOnErr bool) error
• func Delete(cfg *aws.Config, schema []Schema, abortOnErr bool) error
• func Int(item map[string]*dynamodb.AttributeValue, key string) int
• func SetInt(item map[string]*dynamodb.AttributeValue, key string, val int)
• func SetStr(item map[string]*dynamodb.AttributeValue, key string, val string)
• func Str(item map[string]*dynamodb.AttributeValue, key string) string
• type DefFunc
• type Row
• type Schema
• type Table
  • func CheckTable(db *dynamodb.DynamoDB, tableName string) Table
  • func (t Table) RowCount() int
  • func (t Table) Rows() ([]Row, ValueDefiner)
• type ValueDefiner
• type ValueReader
  • func NewValueReader(item map[string]*dynamodb.AttributeValue) ValueReader
• type ValueWriter
  • func NewValueWriter(item map[string]*dynamodb.AttributeValue) ValueWriter
  • func (w ValueWriter) Int(key string, val int)
  • func (w ValueWriter) Str(key string, val string)

Functions

func CheckRowCount

func CheckRowCount(db *dynamodb.DynamoDB, tableName string) int

CheckRowCount returns the number of records in a table.

func CheckRows

func CheckRows(db *dynamodb.DynamoDB, tableName string) ([]Row, ValueDefiner)

CheckRows returns a Row accessor for every row in a table. The order of rows is unspecified. If an error occurs, the rows will be nil. The returned ValueDefiner can be used to define access to custom types across all rows.

func Create

func Create(cfg *aws.Config, schema []Schema, abortOnErr bool) error

Create makes sure that all of the schemas exist. If abortOnErr is false, it iterates through all schemas even if one returns an error. This is generally what you want to do since each table schema is independent, and it makes calling this function idempotent.

func Delete

func Delete(cfg *aws.Config, schema []Schema, abortOnErr bool) error

Delete makes sure that none of the schemas exist. If abortOnErr is false, it continues deleting even if one causes an error. This is generally what you want to do, since each table is independent. It also makes this function idempotent.

func Int

func Int(item map[string]*dynamodb.AttributeValue, key string) int

Int returns an int from a DynamoDB attribute value. If anything goes wrong reading or parsing the value, 0 is returned.

func SetInt

func SetInt(item map[string]*dynamodb.AttributeValue, key string, val int)

SetInt stores an int attribute.

func SetStr

func SetStr(item map[string]*dynamodb.AttributeValue, key string, val string)

SetStr stores a string attribute. If the string is empty, it is not stored.

func Str

func Str(item map[string]*dynamodb.AttributeValue, key string) string

Str returns a string from a DynamoDB attribute value. If anything goes wrong reading the value, an empty string is returned.

Types

type DefFunc

type DefFunc func(ValueReader) interface{}

DefFunc is the handler for custom types.

type Row

type Row struct {
	ValueReader
}

Row is a generic accessor for any dynamodb row. It implements ValueReader, so all of the convenient methods defined there are available.

type Schema

type Schema interface {

	// Create ensures that the table(s) exist. It should return an error if
	// the table already exists or there is any problem creating it.
	Create(*aws.Config) error

	// Delete ensures that the table(s) do not exist. It should return an
	// error if the table cannot be deleted or if it does not exist.
	Delete(*aws.Config) error
}

Schema is the interface for managing table schemas.

type Table

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

Table is a convient wrapper over any DynamoDB table.

func CheckTable

func CheckTable(db *dynamodb.DynamoDB, tableName string) Table

CheckTable initializes a new wrapper over the table.

func (Table) RowCount

func (t Table) RowCount() int

RowCount returns the number of rows in the table.

func (Table) Rows

func (t Table) Rows() ([]Row, ValueDefiner)

Rows returns a simple accessor for each row in the table. The rows are returned in no particular order. The returned ValueDefiner can be used to initialize access to complex values.

type ValueDefiner

type ValueDefiner interface {
	// Def defines a custom conversion, accessible via Get.
	Def(key string, f DefFunc)
}

ValueDefiner lets you define accessors for custom types.

type ValueReader

type ValueReader interface {

	// Str returns a string value from the item.
	Str(key string) string

	// Int returns an int value from the item.
	Int(key string) int

	// Get returns the value from a custom-defined field.
	Get(key string) interface{}

	// ValueDefiner provides Def()
	ValueDefiner
}

ValueReader defines access to different types of value.

func NewValueReader

func NewValueReader(item map[string]*dynamodb.AttributeValue) ValueReader

NewValueReader initializes a ValueReader over an item.

type ValueWriter

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

ValueWriter lets you easily set values in an DynamoDB AttributeValue map.

func NewValueWriter

func NewValueWriter(item map[string]*dynamodb.AttributeValue) ValueWriter

NewValueWriter initializes a ValueWriter over an item.

func (ValueWriter) Int

func (w ValueWriter) Int(key string, val int)

Int writes an int values to the item.

func (ValueWriter) Str

func (w ValueWriter) Str(key string, val string)

Str writes a string value to the item.