dynamo

package module
v0.0.0-...-e003c93 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 4, 2016 License: BSD-2-Clause Imports: 16 Imported by: 0

README

dynamo GoDoc Circle CI

import "github.com/guregu/dynamo"

dynamo is an expressive DynamoDB client for Go, with an API heavily inspired by mgo. dynamo integrates with the official AWS SDK.

dynamo is still under development, so the API may change!

Example

package dynamo

import (
	"time"

	"github.com/aws/aws-sdk-go/aws"
	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/guregu/dynamo"
)

// Use struct tags much like the standard JSON library,
// you can embed anonymous structs too!
type widget struct {
	UserID int       // Hash key, a.k.a. partition key
	Time   time.Time // Range key, a.k.a. sort key
	
	Msg       string   `dynamo:"Message"`
	Count     int      `dynamo:",omitempty"`
	Friends   []string `dynamo:",set"` // Sets 
	SecretKey string   `dynamo:"-"`    // Ignored
	Children  []any    // Lists
}

func main() {
	db := dynamo.New(session.New(), &aws.Config{Region: aws.String("us-west-2")})
	table := db.Table("Widgets")
	
	// put item
	w := widget{UserID: 613, Time: time.Now(), Msg: "hello"}
	err := table.Put(w).Run() 
	
	// get the same item 
	var result widget
	err = table.Get("UserID", w.UserID).
				Range("Time", dynamo.Equal, w.Time).
				Filter("'Count' = ? AND $ = ?", w.Count, "Message", w.Msg). // placeholders in expressions
				One(&result)
	
	// get all items
	var results []widget
	err = table.Scan().All(&results)
	// ...
}

Expressions

dynamo will help you write expressions used to filter results in queries and scans, and add conditions to puts and deletes.

Attribute names may be written as is if it is not a reserved word, or be escaped with single quotes (''). You may also use dollar signs ($) as placeholders for attribute names. DynamoDB has very large amount of reserved words so it may be a good idea to just escape everything.

Question marks (?) are used as placeholders for attribute values. DynamoDB doesn't have value literals, so you need to substitute everything.

Please see the DynamoDB reference on expressions for more information.

// Using single quotes to escape a reserved word, and a question mark as a value placeholder.
// Finds all items whose date is greater than or equal to lastUpdate.
table.Scan().Filter("'Date' >= ?", lastUpdate).All(&results)

// Using dollar signs as a placeholder for attribute names. 
// Deletes the item with an ID of 42 if its score is at or below the cutoff, and its name starts with G.
table.Delete("ID", 42).If("Score <= ? AND begins_with($, ?)", cutoff, "Name", "G").Run()

// Put a new item, only if it doesn't already exist.
table.Put(item{ID: 42}).If("attribute_not_exists(ID)").Run()

Integration tests

By default, tests are run in offline mode. Create a table called TestDB, with a Number Parition Key called UserID and a String Sort Key called Time. Change the table name with the environment variable DYNAMO_TEST_TABLE. You must specify DYNAMO_TEST_REGION, setting it to the AWS region where your test table is.

DYNAMO_TEST_REGION=us-west-2 go test github.com/guregu/dynamo/... -cover

License

BSD

Documentation

Overview

Package dynamo offers a rich DynamoDB client.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrNotFound is returned when no items could be found in Get or OldValue a and similar operations.
	ErrNotFound = errors.New("dynamo: no item found")
	// ErrTooMany is returned when one item was requested, but the query returned multiple items.
	ErrTooMany = errors.New("dynamo: too many items")
)
View Source 
var (
	Equal          = Operator(aws.String("EQ"))
	NotEqual       = Operator(aws.String("NE"))
	Less           = Operator(aws.String("LT"))
	LessOrEqual    = Operator(aws.String("LE"))
	Greater        = Operator(aws.String("GT"))
	GreaterOrEqual = Operator(aws.String("GE"))
	BeginsWith     = Operator(aws.String("BEGINS_WITH"))
	Between        = Operator(aws.String("BETWEEN"))
)

Operators used for comparing against the range key.

View Source 
var (
	Ascending  = Order(aws.Bool(true))  // ScanIndexForward = true
	Descending = Order(aws.Bool(false)) // ScanIndexForward = false
)

Orders for sorting results.

View Source 
var RetryTimeout = 1 * time.Minute

RetryTimeout defines the maximum amount of time that requests will attempt to automatically retry for. In other words, this is the maximum amount of time that dynamo operations will block. Higher values are better when using tables with lower throughput.

Functions

func Marshal 

func Marshal(v interface{}) (*dynamodb.AttributeValue, error)

Marshal converts the given value into a DynamoDB attribute value.

func MarshalItem 

func MarshalItem(v interface{}) (map[string]*dynamodb.AttributeValue, error)

MarshalItem converts the given struct into a DynamoDB item.

func Unmarshal 

func Unmarshal(av *dynamodb.AttributeValue, out interface{}) error

Unmarshal decodes a DynamoDB value into out, which must be a pointer.

func UnmarshalItem 

func UnmarshalItem(item map[string]*dynamodb.AttributeValue, out interface{}) error

Unmarshal decodes a DynamoDB item into out, which must be a pointer.

Types

type Batch 

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

Batch stores the names of the hash key and range key for creating new batches.

func (Batch) Get 

func (b Batch) Get(keys ...Keyed) *BatchGet

Get creates a new batch get item request with the given keys. 

table.Batch("ID", "Month").
	Get([]dynamo.Keys{{1, "2015-10"}, {42, "2015-12"}, {42, "1992-02"}}...).
	All(&results)

func (Batch) Write 

func (b Batch) Write() *BatchWrite

Write creates a new batch write request, to which puts and deletes can be added.

type BatchGet 

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

BatchGet is a BatchGetItem operation.

func (*BatchGet) All 

func (bg *BatchGet) All(out interface{}) error

All executes this request and unmarshals all results to out, which must be a pointer to a slice.

func (*BatchGet) And 

func (bg *BatchGet) And(keys ...Keyed) *BatchGet

And adds more keys to be gotten.

func (*BatchGet) Consistent 

func (bg *BatchGet) Consistent(on bool) *BatchGet

Consistent will, if on is true, make this batch use a strongly consistent read. Reads are eventually consistent by default. Strongly consistent reads are more resource-heavy than eventually consistent reads.

func (*BatchGet) Iter 

func (bg *BatchGet) Iter() Iter

Iter returns a results iterator for this batch.

type BatchWrite 

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

BatchWrite is a BatchWriteItem operation.

func (*BatchWrite) Delete 

func (bw *BatchWrite) Delete(keys ...Keyed) *BatchWrite

Delete adds delete operations for the given keys to this batch.

func (*BatchWrite) Put 

func (bw *BatchWrite) Put(items ...interface{}) *BatchWrite

Put adds put operations for items to this batch.

func (*BatchWrite) Run 

func (bw *BatchWrite) Run() (wrote int, err error)

Run executes this batch. For batches with more than 25 operations, an error could indicate that some records have been written and some have not. Consult the wrote return amount to figure out which operations have succeeded.

type CreateTable 

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

CreateTable is a request to create a new table. See: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CreateTable.html

func (*CreateTable) Project 

func (ct *CreateTable) Project(index string, projection IndexProjection, includeAttribs ...string) *CreateTable

Project specifies the projection type for the given table. When using IncludeProjection, you must specify the additional attributes to include via includeAttribs.

func (*CreateTable) Provision 

func (ct *CreateTable) Provision(readUnits, writeUnits int64) *CreateTable

Provision specifies the provisioned read and write capacity for this table. If Provision isn't called, the table will be created with 1 unit each.

func (*CreateTable) ProvisionIndex 

func (ct *CreateTable) ProvisionIndex(index string, readUnits, writeUnits int64) *CreateTable

ProvisionIndex specifies the provisioned read and write capacity for the given global secondary index. Local secondary indices share their capacity with the table.

func (*CreateTable) Run 

func (ct *CreateTable) Run() error

Run creates this table or returns and error.

func (*CreateTable) Stream 

func (ct *CreateTable) Stream(view StreamView) *CreateTable

Stream enables DynamoDB Streams for this table which the specified type of view. Streams are disabled by default.

type DB 

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

DB is a DynamoDB client.

func New 

func New(p client.ConfigProvider, cfgs ...*aws.Config) *DB

New creates a new client with the given configuration.

func (*DB) CreateTable 

func (db *DB) CreateTable(name string, from interface{}) *CreateTable

CreateTable begins a new operation to create a table with the given name. The second parameter must be a struct with appropriate hash and range key struct tags for the primary key and all indices.

An example of a from struct follows: 

type UserAction struct {
	UserID string    `dynamo:"ID,hash" index:"Seq-ID-index,range"`
	Time   time.Time `dynamo:",range"`
	Seq    int64     `localIndex:"ID-Seq-index,range" index:"Seq-ID-index,hash"`
	UUID   string    `index:"UUID-index,hash"`
}

This creates a table with the primary hash key ID and range key Time. It creates two global secondary indices called UUID-index and Seq-ID-index, and a local secondary index called ID-Seq-index.

func (*DB) Table 

func (db *DB) Table(name string) Table

Table returns a Table handle specified by name.

type Delete 

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

Delete is a request to delete an item. See: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html

func (*Delete) If 

func (d *Delete) If(expr string, args ...interface{}) *Delete

If specifies a conditional expression for this delete to succeed. Use single quotes to specificy reserved names inline (like 'Count'). Use the placeholder ? within the expression to substitute values, and use $ for names. You need to use quoted or placeholder names when the name is a reserved word in DynamoDB.

func (*Delete) OldValue 

func (d *Delete) OldValue(out interface{}) error

OldValue executes this delete request, unmarshaling the previous value to out. Returns ErrNotFound is there was no previous value.

func (*Delete) Range 

func (d *Delete) Range(name string, value interface{}) *Delete

Range specifies the range key (a.k.a. sort key) to delete. Name is the name of the range key. Value is the value of the range key.

func (*Delete) Run 

func (d *Delete) Run() error

Run executes this delete request.

type DeleteTable 

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

DeleteTable is a request to delete a table. See: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteTable.html

func (*DeleteTable) Run 

func (dt *DeleteTable) Run() error

Run executes this request and deletes the table.

type IndexProjection 

type IndexProjection string

IndexProjection determines which attributes are mirrored into indices. 

var (
	// Only the key attributes of the modified item are written to the stream.
	KeysOnlyProjection IndexProjection = dynamodb.ProjectionTypeKeysOnly
	// All of the table attributes are projected into the index.
	AllProjection IndexProjection = dynamodb.ProjectionTypeAll
	// Only the specified table attributes are projected into the index.
	IncludeProjection IndexProjection = dynamodb.ProjectionTypeInclude
)

type Iter 

type Iter interface {
	// Next tries to unmarshal the next result into out.
	// Returns false when it is complete or if it runs into an error.
	Next(out interface{}) bool
	// Err returns the error encountered, if any.
	// You should check this after Next is finished.
	Err() error
}

Iter is an iterator for request results.

type Keyed 

type Keyed interface {
	HashKey() interface{}
	RangeKey() interface{}
}

Keyed provides hash key and range key values.

type Keys 

type Keys [2]interface{}

Keys provides an easy way to specify the hash and range keys. 

table.Batch("ID", "Month").
	Get([]dynamo.Keys{{1, "2015-10"}, {42, "2015-12"}, {42, "1992-02"}}...).
	All(&results)

func (Keys) HashKey 

func (k Keys) HashKey() interface{}

HashKey returns the hash key's value.

func (Keys) RangeKey 

func (k Keys) RangeKey() interface{}

RangeKey returns the range key's value.

type Marshaler 

type Marshaler interface {
	MarshalDynamo() (*dynamodb.AttributeValue, error)
}

Marshaler is the interface implemented by objects that can marshal themselves into an AttributeValue.

type Operator 

type Operator *string

Operator is an operation to apply in key comparisons.

type Order 

type Order *bool

Order is used for specifying the order of results.

type Put 

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

Put is a request to create or replace an item. See: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html

func (*Put) If 

func (p *Put) If(expr string, args ...interface{}) *Put

If specifies a conditional expression for this put to succeed. Use single quotes to specificy reserved names inline (like 'Count'). Use the placeholder ? within the expression to substitute values, and use $ for names. You need to use quoted or placeholder names when the name is a reserved word in DynamoDB.

func (*Put) OldValue 

func (p *Put) OldValue(out interface{}) error

OldValue executes this put, unmarshaling the previous value into out. Returns ErrNotFound is there was no previous value.

func (*Put) Run 

func (p *Put) Run() error

Run executes this put.

type Query 

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

Query is a request to get one or more items in a table. Query uses the DynamoDB query for requests for multiple items, and GetItem for one. See: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html and http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html

func (*Query) All 

func (q *Query) All(out interface{}) error

All executes this request and unmarshals all results to out, which must be a pointer to a slice.

func (*Query) Consistent 

func (q *Query) Consistent(on bool) *Query

Consistent will, if on is true, make this query a strongly consistent read. Queries are eventually consistent by default. Strongly consistent reads are more resource-heavy than eventually consistent reads.

func (*Query) Count 

func (q *Query) Count() (int64, error)

Count executes this request, returning the number of results.

func (*Query) Filter 

func (q *Query) Filter(expr string, args ...interface{}) *Query

Filter takes an expression that all results will be evaluated against. Use single quotes to specificy reserved names inline (like 'Count'). Use the placeholder ? within the expression to substitute values, and use $ for names. You need to use quoted or placeholder names when the name is a reserved word in DynamoDB. Multiple calls to Filter will be combined with AND.

func (*Query) Index 

func (q *Query) Index(name string) *Query

Index specifies the name of the index that this query will operate on.

func (*Query) Iter 

func (q *Query) Iter() Iter

Iter returns a results iterator for this request.

func (*Query) Limit 

func (q *Query) Limit(limit int64) *Query

Limit specifies the maximum amount of results to return.

func (*Query) One 

func (q *Query) One(out interface{}) error

One executes this query and retrieves a single result, unmarshaling the result to out.

func (*Query) Order 

func (q *Query) Order(order Order) *Query

Order specifies the desired result order. Requires a range key (a.k.a. partition key) to be specified.

func (*Query) Project 

func (q *Query) Project(paths ...string) *Query

Project limits the result attributes to the given paths.

func (*Query) Range 

func (q *Query) Range(name string, op Operator, values ...interface{}) *Query

Range specifies the range key (a.k.a. sort key) or keys to get. For single item requests using One, op must be Equal. Name is the name of the range key. Op specifies the operator to use when comparing values.

func (*Query) SearchLimit 

func (q *Query) SearchLimit(limit int64) *Query

SearchLimit specifies the maximum amount of results to examine. If a filter is not specified, the number of results will be limited. If a filter is specified, the number of results to consider for filtering will be limited.

type Scan 

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

Scan is a request to scan all the data in a table. See: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html

func (*Scan) All 

func (s *Scan) All(out interface{}) error

All executes this request and unmarshals all results to out, which must be a pointer to a slice.

func (*Scan) Consistent 

func (s *Scan) Consistent(on bool) *Scan

Consistent will, if on is true, make this scan use a strongly consistent read. Scans are eventually consistent by default. Strongly consistent reads are more resource-heavy than eventually consistent reads.

func (*Scan) Filter 

func (s *Scan) Filter(expr string, args ...interface{}) *Scan

Filter takes an expression that all results will be evaluated against. Use single quotes to specificy reserved names inline (like 'Count'). Use the placeholder ? within the expression to substitute values, and use $ for names. You need to use quoted or placeholder names when the name is a reserved word in DynamoDB.

func (*Scan) Index 

func (s *Scan) Index(name string) *Scan

Index specifies the name of the index that Scan will operate on.

func (*Scan) Iter 

func (s *Scan) Iter() Iter

Iter returns a results iterator for this request.

func (*Scan) Project 

func (s *Scan) Project(paths ...string) *Scan

Project limits the result attributes to the given paths.

type StreamView 

type StreamView string

StreamView determines what information is written to a table's stream. 

var (
	// Only the key attributes of the modified item are written to the stream.
	KeysOnlyView StreamView = dynamodb.StreamViewTypeKeysOnly
	// The entire item, as it appears after it was modified, is written to the stream.
	NewImageView StreamView = dynamodb.StreamViewTypeNewImage
	// The entire item, as it appeared before it was modified, is written to the stream.
	OldImageView StreamView = dynamodb.StreamViewTypeOldImage
	// Both the new and the old item images of the item are written to the stream.
	NewAndOldImagesView StreamView = dynamodb.StreamViewTypeNewAndOldImages
)

type Table 

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

Table is a DynamoDB table.

func (Table) Batch 

func (table Table) Batch(hashAndRangeKeyName ...string) Batch

Batch creates a new batch with the given hash key name, and range key name if provided. For purely Put batches, neither is necessary.

func (Table) Delete 

func (table Table) Delete(name string, value interface{}) *Delete

Delete creates a new request to delete an item. Key is the name of the hash key (a.k.a. partition key). Value is the value of the hash key.

func (Table) DeleteTable 

func (table Table) DeleteTable() *DeleteTable

DeleteTable begins a new request to delete this table.

func (Table) Get 

func (table Table) Get(name string, value interface{}) *Query

Get creates a new request to get an item. Name is the name of the hash key (a.k.a. partition key). Value is the value of the hash key.

func (Table) Name 

func (table Table) Name() string

Name returns this table's name.

func (Table) Put 

func (table Table) Put(item interface{}) *Put

Put creates a new request to create or replace an item.

func (Table) Scan 

func (table Table) Scan() *Scan

Scan creates a new request to scan this table.

func (Table) Update 

func (table Table) Update(hashKey string, value interface{}) *Update

Update creates a new request to modify an existing item.

type Unmarshaler 

type Unmarshaler interface {
	UnmarshalDynamo(av *dynamodb.AttributeValue) error
}

Unmarshaler is the interface implemented by objects that can unmarshal an AttributeValue into themselves.

type Update 

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

Update represents changes to an existing item. It uses the UpdateItem API. See: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html

func (*Update) Add 

func (u *Update) Add(path string, value interface{}) *Update

Add adds value to path. Path can be a number or a set. If path represents a set, value must be []int or []string. Path must be a top-level attribute.

func (*Update) AddFloatsToSet 

func (u *Update) AddFloatsToSet(path string, values ...float64) *Update

AddFloatsToSet adds the given values to the number set specified by path.

func (*Update) AddIntsToSet 

func (u *Update) AddIntsToSet(path string, values ...int) *Update

AddIntsToSet adds the given values to the number set specified by path.

func (*Update) AddStringsToSet 

func (u *Update) AddStringsToSet(path string, values ...string) *Update

AddStringsToSet adds the given values to the string set specified by path.

func (*Update) Append 

func (u *Update) Append(path string, value interface{}) *Update

Append appends value to the end of the list specified by path.

func (*Update) DeleteFloatsFromSet 

func (u *Update) DeleteFloatsFromSet(path string, values ...float64) *Update

DeleteFloatsFromSet deletes the given values from the number set specified by path.

func (*Update) DeleteIntsFromSet 

func (u *Update) DeleteIntsFromSet(path string, values ...int) *Update

DeleteIntsFromSet deletes the given values from the number set specified by path.

func (*Update) DeleteStringsFromSet 

func (u *Update) DeleteStringsFromSet(path string, values ...string) *Update

DeleteStringsFromSet deletes the given values from the string set specified by path.

func (*Update) If 

func (u *Update) If(expr string, args ...interface{}) *Update

If specifies a conditional expression for this update to succeed. Use single quotes to specificy reserved names inline (like 'Count'). Use the placeholder ? within the expression to substitute values, and use $ for names. You need to use quoted or placeholder names when the name is a reserved word in DynamoDB.

func (*Update) OldValue 

func (u *Update) OldValue(out interface{}) error

OldValue executes this update, encoding out with the previous value.

func (*Update) Prepend 

func (u *Update) Prepend(path string, value interface{}) *Update

Prepend inserts value to the beginning of the list specified by path.

func (*Update) Range 

func (u *Update) Range(name string, value interface{}) *Update

Range specifies the range key (sort key) for the item to update.

func (*Update) Remove 

func (u *Update) Remove(paths ...string) *Update

Remove removes the paths from this item, deleting the specified attributes.

func (*Update) Run 

func (u *Update) Run() error

Run executes this update.

func (*Update) Set 

func (u *Update) Set(path string, value interface{}) *Update

Set changes path to the given value. Paths that are reserved words are automatically escaped. Use single quotes to escape complex values like 'User'.'Count'.

func (*Update) SetIfNotExists 

func (u *Update) SetIfNotExists(path string, value interface{}) *Update

SetIfNotExists changes path to the given value, if it does not already exist.

func (*Update) Value 

func (u *Update) Value(out interface{}) error

Value executes this update, encoding out with the new value.

Source Files

View all Source files

Directories

Path Synopsis
internal
exprs
Package exprs is the internal package for parsing DynamoDB "expressions", including condition expressions and filter expressions.
 Package exprs is the internal package for parsing DynamoDB "expressions", including condition expressions and filter expressions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.