dynago

package module
v0.1.9 Latest Latest
Warning

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

 Go to latest Published: Jul 22, 2023 License: MIT Imports: 12 Imported by: 0

README

Dynago

codecov

The aim of this package is to make it easier to work with AWS DynamoDB.

Documentation

For full documentation see pkg.go.dev.

Usage

Basic
package main

import (
	"fmt"
	"os"
	"time"

	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/dynamodb"
	"github.com/twharmon/dynago"
)

type Schema struct {}

func (s *Schema) PrimaryKeys() []string {
	return []string{"PK", "SK"}
}

type Post struct {
	// Embed a struct that implements the dynago.Keyer interface.
	*Schema

	// Set attribute name with `attr` tag if it needs to be different
	// than field name. Use `fmt:"Post#{}"` to indicate how the value
	// will be stored in DynamoDB.
	ID string `attr:"PK" fmt:"Post#{}"`

	Created  time.Time `attr:"SK" fmt:"Created#{}"`
	AuthorID string
	Title    string
	Body     string
}

func main() {
	// Get client.
	ddb := dynago.New(getDynamoDB(), &dynago.Config{
		DefaultTableName: "tmp",
	})

	// Put item in DynamoDB.
	p := Post{
		ID:      "hello-world",
		Title:   "Hi",
		Body:    "Hello world!",
		Created: time.Now(),
	}
	if err := ddb.PutItem(&p).Exec(); err != nil {
		panic(err)
	}

	// Get same item from DynamoDB. Fields used in the primary key
	// must be set.
	p2 := Post{
		ID:      p.ID,
		Created: p.Created,
	}
	if err := ddb.GetItem(&p2).Exec(); err != nil {
		panic(err)
	}
	fmt.Println(p2)
}

func getDynamoDB() *dynamodb.DynamoDB {
	os.Setenv("AWS_SDK_LOAD_CONFIG", "true")
	sess, err := session.NewSession()
	if err != nil {
		panic(err)
	}
	return dynamodb.New(sess)
}
Additional Attributes
package main

import (
	"fmt"
	"os"
	"reflect"
	"time"

	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/dynamodb"
	"github.com/twharmon/dynago"
)

type Schema struct {}

func (s *Schema) PrimaryKeys() []string {
	return []string{"PK", "SK"}
}

type Post struct {
	// Embed a struct that implements the dynago.Keyer interface.
	*Schema

	ID       string `attr:"PK" fmt:"Post#{}"`
	AuthorID string
	Title    string
	Body     string
	Created  time.Time `attr:"SK" fmt:"Created#{}"`
}

type Author struct {
	ID   string `attr:"PK" fmt:"Author#{}"`

	// Copy same value to attribute AltName by using `copy:"AltName"` in tag.
	Name string `copy:"AltName"`
}

func main() {
	// Get client.
	ddb := dynago.New(getDynamoDB(), &dynago.Config{
		DefaultTableName: "tmp",
		AdditionalAttrs:  additionalAttrs,
	})

	// ...
}

func additionalAttrs(item map[string]*dynamodb.AttributeValue, v reflect.Value) {
	ty := v.Type().Name()

	// Add a "Type" attribute to every item
	item["Type"] = &dynamodb.AttributeValue{S: &ty}

	// Add additional attributes for specific types
	switch val := v.Interface().(type) {
	case Author:
		// Add a fat partition or sparse global secondary index to
		// make querying for all authors possible
		author := fmt.Sprintf("Author#%s", val.ID)
		item["GSIPK"] = &dynamodb.AttributeValue{S: &ty}
		item["GSISK"] = &dynamodb.AttributeValue{S: &author}
	}
}
Compound Field Attributes
type Event struct {
	Org string `attr:"PK" fmt:"Org#{}"`

	// In this `fmt` tag, {} is equivalent to {Country}. You can
	// reference a different field name by putting it's name in
	// curly brackets.
	Country string `attr:"SK" fmt:"Country#{}#City#{City}"`

	// Since the City is specified in the "SK" attribute, we can
	// skip putting it in another attribute if we want.
	City    string `attr:"-"`
	Created time.Time
}

Contribute

Make a pull request.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrItemNotFound = errors.New("item not found")

ErrItemNotFound is returned when the item is not found.

Functions

This section is empty.

Types

type ConditionCheck added in v0.0.6 

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

ConditionCheck represents a request to perform a check that an item exists or to check the condition of specific attributes of the item.

func (*ConditionCheck) ConditionExpression added in v0.0.6 

func (q *ConditionCheck) ConditionExpression(exp string) *ConditionCheck

ConditionExpression sets the ConditionExpression.

func (*ConditionCheck) ExpressionAttributeName added in v0.0.6 

func (q *ConditionCheck) ExpressionAttributeName(name string, sub string) *ConditionCheck

ExpressionAttributeName sets an ExpressionAttributeName.

func (*ConditionCheck) ExpressionAttributeValue added in v0.0.6 

func (q *ConditionCheck) ExpressionAttributeValue(key string, val interface{}, layout ...string) *ConditionCheck

ExpressionAttributeValue sets an ExpressionAttributeValue.

func (*ConditionCheck) TableName added in v0.0.6 

func (c *ConditionCheck) TableName(name string) *ConditionCheck

TableName sets the table to be checked.

func (*ConditionCheck) TransactionWriteItem added in v0.0.6 

func (c *ConditionCheck) TransactionWriteItem() (*dynamodb.TransactWriteItem, error)

TransactionWriteItem implements the TransactionWriteItemer interface.

type Config 

type Config struct {
	// AttrTagName specifies which tag is used for a DynamoDB
	// item attribute name. Defaults to "attr".
	AttrTagName string

	// FmtTagName specifies which tag is used to format the attribute
	// value. This is only used for String types. Defaults to "fmt".
	FmtTagName string

	// TypeTagName specifies which tag is used for DynamoDB type.
	// Defaults to "type".
	TypeTagName string

	// LayoutTagName specifies which tag is used for formatting time
	// values. Defaults to "layout".
	LayoutTagName string

	// AttrsToCopyTagName specifies which tag is used to determine
	// which other attributes should have same value. Defaults to
	// "copy".
	AttrsToCopyTagName string

	// AdditionalAttrs can be added for each dynamodb item.
	AdditionalAttrs func(map[string]*dynamodb.AttributeValue, reflect.Value)

	// DefaultTableName is the default table queried when not
	// specified.
	DefaultTableName string

	// DefaultConsistentRead is the default read consistency model.
	DefaultConsistentRead bool
}

Config is used to customize struct tag names.

type DeleteItem 

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

DeleteItem represents a delete item operation.

func (*DeleteItem) ConditionExpression added in v0.0.3 

func (q *DeleteItem) ConditionExpression(exp string) *DeleteItem

ConditionExpression sets the ConditionExpression.

func (*DeleteItem) Exec 

func (q *DeleteItem) Exec() error

Exec executes the operation.

func (*DeleteItem) ExpressionAttributeName added in v0.0.3 

func (q *DeleteItem) ExpressionAttributeName(name string, sub string) *DeleteItem

ExpressionAttributeName sets a ExpressionAttributeName.

func (*DeleteItem) ExpressionAttributeValue added in v0.0.3 

func (q *DeleteItem) ExpressionAttributeValue(key string, val interface{}, layout ...string) *DeleteItem

ExpressionAttributeValue sets an ExpressionAttributeValue.

func (*DeleteItem) TableName added in v0.0.3 

func (q *DeleteItem) TableName(name string) *DeleteItem

TableName sets the table.

func (*DeleteItem) TransactionWriteItem added in v0.0.2 

func (q *DeleteItem) TransactionWriteItem() (*dynamodb.TransactWriteItem, error)

TransactionWriteItem implements the TransactionWriteItemer interface.

type Dynago 

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

Dynago provides the API operation methods for making requests to Amazon DynamoDB. Dynago methods are safe to use concurrently.

func New 

func New(ddb dynamodbiface.DynamoDBAPI, config ...*Config) *Dynago

New creates a new Dynago client. An optional config can be passed in second argument.

func (*Dynago) ConditionCheck added in v0.0.6 

func (d *Dynago) ConditionCheck(item Keyer) *ConditionCheck

ConditionCheck creates a ConditionCheck operation. The given item must have the primary key fields set.

func (*Dynago) DeleteItem 

func (d *Dynago) DeleteItem(item Keyer) *DeleteItem

DeleteItem creates a DeleteItem operation.

func (*Dynago) GetItem 

func (d *Dynago) GetItem(item Keyer) *GetItem

GetItem returns a GetItem operation.

func (*Dynago) Marshal 

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

Marshal converts a Go struct into a DynamoDB item.

func (*Dynago) PutItem 

func (d *Dynago) PutItem(item Keyer) *PutItem

PutItem returns a PutItem operation.

func (*Dynago) Query 

func (d *Dynago) Query(items interface{}) *Query

Query returns a Query operation.

func (*Dynago) Scan added in v0.0.3 

func (d *Dynago) Scan(items interface{}) *Scan

Scan returns a Scan operation.

func (*Dynago) TransactionWriteItems added in v0.0.7 

func (d *Dynago) TransactionWriteItems() *TransactionWriteItems

TransactionWriteItems returns a TransactionWriteItems operation.

func (*Dynago) Unmarshal 

func (d *Dynago) Unmarshal(item map[string]*dynamodb.AttributeValue, v interface{}) error

Unmarshal converts a DynamoDB item into a Go struct.

func (*Dynago) UpdateItem added in v0.0.6 

func (d *Dynago) UpdateItem(item Keyer) *UpdateItem

UpdateItem returns an UpdateItem operation.

type DynagoAPI added in v0.0.7 

type DynagoAPI interface {
	DeleteItem(Keyer) *DeleteItem
	PutItem(Keyer) *PutItem
	GetItem(Keyer) *GetItem
	Query(interface{}) *Query
	Scan(interface{}) *Scan
	UpdateItem(Keyer) *UpdateItem
	ConditionCheck(Keyer) *ConditionCheck
	TransactionWriteItems() *TransactionWriteItems
	Marshal(interface{}) (map[string]*dynamodb.AttributeValue, error)
	Unmarshal(map[string]*dynamodb.AttributeValue, interface{}) error
}

DynagoAPI provides an interface to enable mocking the dynago.Dynago service client's API operations. This make unit testing your code easier.

type Float added in v0.0.3 

type Float interface {
	float32 | float64
}

type GetItem 

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

GetItem represents a GetItem operation.

func (*GetItem) ConsistentRead added in v0.0.3 

func (q *GetItem) ConsistentRead(consisten bool) *GetItem

ConsistentRead sets ConsistentRead.

func (*GetItem) Exec 

func (q *GetItem) Exec() error

Exec exeutes the operation.

func (*GetItem) ExpressionAttributeName added in v0.0.3 

func (q *GetItem) ExpressionAttributeName(name string, sub string) *GetItem

ExpressionAttributeName sets an ExpressionAttributeName.

func (*GetItem) ProjectionExpression added in v0.0.3 

func (q *GetItem) ProjectionExpression(exp string) *GetItem

ProjectionExpression sets the ProjectionExpression.

func (*GetItem) TableName added in v0.0.3 

func (q *GetItem) TableName(name string) *GetItem

TableName sets the table.

type Keyer added in v0.1.0 

type Keyer interface {
	PrimaryKeys() []string
}

type PutItem 

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

PutItem represents a PutItem operation.

func (*PutItem) ConditionExpression added in v0.0.3 

func (q *PutItem) ConditionExpression(exp string) *PutItem

ConditionExpression sets the ConditionExpression.

func (*PutItem) Exec 

func (q *PutItem) Exec() error

Exec exeutes the operation.

func (*PutItem) ExpressionAttributeName added in v0.0.3 

func (q *PutItem) ExpressionAttributeName(name string, sub string) *PutItem

ExpressionAttributeName sets an ExpressionAttributeName.

func (*PutItem) ExpressionAttributeValue added in v0.0.3 

func (q *PutItem) ExpressionAttributeValue(key string, val interface{}, layout ...string) *PutItem

ExpressionAttributeValue sets an ExpressionAttributeValue.

func (*PutItem) TableName added in v0.0.3 

func (q *PutItem) TableName(table string) *PutItem

TableName sets the table.

func (*PutItem) TransactionWriteItem added in v0.0.2 

func (q *PutItem) TransactionWriteItem() (*dynamodb.TransactWriteItem, error)

TransactionWriteItem implements the TransactionWriteItemer interface.

type Query 

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

Query represents a Query operation.

func (*Query) ConsistentRead added in v0.0.3 

func (q *Query) ConsistentRead(val bool) *Query

ConsistentRead sets ConsistentRead.

func (*Query) ExclusiveStartKey added in v0.0.3 

func (q *Query) ExclusiveStartKey(key map[string]*dynamodb.AttributeValue) *Query

ExclusiveStartKey sets the ExclusiveStartKey.

func (*Query) Exec 

func (q *Query) Exec() error

Exec executes the operation.

func (*Query) ExpressionAttributeName added in v0.0.3 

func (q *Query) ExpressionAttributeName(name string, sub string) *Query

ExpressionAttributeName sets an ExpressionAttributeName.

func (*Query) ExpressionAttributeValue 

func (q *Query) ExpressionAttributeValue(key string, val interface{}, layout ...string) *Query

ExpressionAttributeValue sets an ExpressionAttributeValue.

func (*Query) FilterExpression added in v0.0.3 

func (q *Query) FilterExpression(exp string) *Query

FilterExpression sets the FilterExpression.

func (*Query) IndexName added in v0.0.3 

func (q *Query) IndexName(index string) *Query

IndexName sets the index.

func (*Query) KeyConditionExpression 

func (q *Query) KeyConditionExpression(exp string) *Query

KeyConditionExpression sets the KeyConditionExpression.

func (*Query) Limit added in v0.0.3 

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

Limit sets the Limit.

func (*Query) ProjectionExpression added in v0.0.3 

func (q *Query) ProjectionExpression(exp string) *Query

ProjectionExpression sets the ProjectionExpression.

func (*Query) ScanIndexForward added in v0.0.2 

func (q *Query) ScanIndexForward(val bool) *Query

ScanIndexForward sets whether or not to scan index forward.

func (*Query) Select added in v0.0.3 

func (q *Query) Select(attrs string) *Query

Select sets which attributes will be selected.

func (*Query) TableName added in v0.0.3 

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

TableName sets the table.

type Scan added in v0.0.3 

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

Scan represents a Scan operation.

func (*Scan) ConsistentRead added in v0.0.3 

func (q *Scan) ConsistentRead(val bool) *Scan

ConsistentRead sets ConsistentRead.

func (*Scan) ExclusiveStartKey added in v0.0.3 

func (q *Scan) ExclusiveStartKey(key map[string]*dynamodb.AttributeValue) *Scan

ExclusiveStartKey sets the ExclusiveStartKey.

func (*Scan) Exec added in v0.0.3 

func (q *Scan) Exec() error

Exec executes the operation.

func (*Scan) ExpressionAttributeName added in v0.0.3 

func (q *Scan) ExpressionAttributeName(name string, sub string) *Scan

ExpressionAttributeName sets an ExpressionAttributeName.

func (*Scan) ExpressionAttributeValue added in v0.0.3 

func (q *Scan) ExpressionAttributeValue(key string, val interface{}, layout ...string) *Scan

ExpressionAttributeValue sets an ExpressionAttributeValue.

func (*Scan) FilterExpression added in v0.0.3 

func (q *Scan) FilterExpression(exp string) *Scan

FilterExpression sets the FilterExpression.

func (*Scan) IndexName added in v0.0.3 

func (q *Scan) IndexName(index string) *Scan

IndexName sets the IndexName.

func (*Scan) Limit added in v0.0.3 

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

Limit sets the Limit.

func (*Scan) Output added in v0.1.8 

func (q *Scan) Output(output *ScanOutput) *Scan

func (*Scan) ProjectionExpression added in v0.0.3 

func (q *Scan) ProjectionExpression(exp string) *Scan

ProjectionExpression sets the ProjectionExpression.

func (*Scan) Segment added in v0.0.3 

func (q *Scan) Segment(segment int64) *Scan

Segment sets Segment.

func (*Scan) Select added in v0.0.3 

func (q *Scan) Select(attrs string) *Scan

Select sets which attributes will be selected.

func (*Scan) TableName added in v0.0.3 

func (q *Scan) TableName(name string) *Scan

TableName sets the table.

func (*Scan) TotalSegments added in v0.0.3 

func (q *Scan) TotalSegments(segments int64) *Scan

TotalSegments sets TotalSegments.

type ScanOutput added in v0.1.8 

type ScanOutput struct {
	LastEvaluatedKey map[string]*dynamodb.AttributeValue
}

ScanOutput represents the output of a scan command.

type TransactionWriteItemer added in v0.0.2 

type TransactionWriteItemer interface {
	TransactionWriteItem() (*dynamodb.TransactWriteItem, error)
}

TransactionWriteItemer interface is to provide a dynamodb.TransactWriteItem.

type TransactionWriteItems added in v0.0.6 

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

TransactionWriteItems represents a TransactWriteItems operation.

func (*TransactionWriteItems) ClientRequestToken added in v0.0.6 

func (i *TransactionWriteItems) ClientRequestToken(token string) *TransactionWriteItems

ClientRequestToken sets the ClientRequestToken.

func (*TransactionWriteItems) Exec added in v0.0.6 

func (i *TransactionWriteItems) Exec() error

Exec executes the operation.

func (*TransactionWriteItems) Items added in v0.0.6 

func (i *TransactionWriteItems) Items(items ...TransactionWriteItemer) *TransactionWriteItems

Items adds items to the transaction.

type UpdateItem added in v0.0.6 

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

UpdateItem represents an UpdateItem operation.

func (*UpdateItem) ConditionExpression added in v0.0.6 

func (q *UpdateItem) ConditionExpression(exp string) *UpdateItem

ConditionExpression sets the ConditionExpression.

func (*UpdateItem) Exec added in v0.0.6 

func (q *UpdateItem) Exec() error

Exec executes the operation.

func (*UpdateItem) ExpressionAttributeName added in v0.0.6 

func (q *UpdateItem) ExpressionAttributeName(name string, sub string) *UpdateItem

ExpressionAttributeName sets an ExpressionAttributeName.

func (*UpdateItem) ExpressionAttributeValue added in v0.0.6 

func (q *UpdateItem) ExpressionAttributeValue(key string, val interface{}, layout ...string) *UpdateItem

ExpressionAttributeValue sets an ExpressionAttributeValue.

func (*UpdateItem) TableName added in v0.0.6 

func (q *UpdateItem) TableName(table string) *UpdateItem

TableName sets the TableName.

func (*UpdateItem) TransactionWriteItem added in v0.0.6 

func (q *UpdateItem) TransactionWriteItem() (*dynamodb.TransactWriteItem, error)

TransactionWriteItem implements the TransactionWriteItemer interface.

func (*UpdateItem) UpdateExpression added in v0.0.6 

func (q *UpdateItem) UpdateExpression(exp string) *UpdateItem

UpdateExpression sets the UpdateExpression.

Source Files

View all Source files

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.