ddb

package module
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Jul 5, 2022 License: MIT Imports: 12 Imported by: 44

README

ddb

Go Reference

Common Fate helpers for working with DynamoDB.

Integration testing

You can provision an example table for testing as follows.

go run cmd/create/main.go

To run the integration tests, you need to set the TESTING_DYNAMODB_TABLE to be the name of the test table you created.

export TESTING_DYNAMODB_TABLE=ddb-testing

To cleanup the table:

go run cmd/destroy/main.go

Documentation

Overview

Example (CustomUnmarshalling)

For complex queries you can implement UnmarshalQueryOutput to control how the DynamoDB query results are unmarshaled.

Output:

Example (Simple)

For simple queries you can declare the query as a type alias. ddb will unmarshal the results directly into the query struct, as shown below.

Output:

Example (StructTag)
Output:

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrInvalidBatchSize error = errors.New("batch size must be greater than 0 and must not be greater than 25")

ErrInvalidBatchSize is returned if an invalid batch size is specified when creating a ddb instance.

View Source
var ErrNoItems error = errors.New("item query returned no items")

ErrNoItems is returned when we expect a query result to contain items, but it doesn't contain any.

Functions

func Limit added in v0.8.0

func Limit(limit int32) func(*QueryOpts)

Limit overrides the amount of items returned from the query. It is mapped to the 'Limit' argument in the dynamodb.Query method.

func Page added in v0.8.0

func Page(pageToken string) func(*QueryOpts)

Page sets the pagination token to provide an offset for the query. It is mapped to the 'ExclusiveStartKey' argument in the dynamodb.Query method.

func WithBatchSize added in v0.7.0

func WithBatchSize(batchSize int) func(*Client)

WithBatchSize allows a custom batchSize to be provided for putBatch operations.

func WithDynamoDBClient added in v0.4.0

func WithDynamoDBClient(d *dynamodb.Client) func(*Client)

WithDynamoDBClient allows a custom dynamodb.Client to be provided.

func WithPageTokenizer added in v0.8.0

func WithPageTokenizer(e Tokenizer) func(*Client)

WithPageTokenizer allows a tokenizer to be provided for turning LastEvaluatedKey items into strings.

Types

type Client added in v0.4.0

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

Client is a thin wrapper over the native DynamoDB client. It has methods which allow access patterns to be written in a more ergonomic fashion than the native client.

func New added in v0.4.0

func New(ctx context.Context, table string, opts ...func(*Client)) (*Client, error)

New creates a new DynamoDB Client.

func (*Client) Delete added in v0.7.0

func (c *Client) Delete(ctx context.Context, item Keyer) error

Delete calls DeleteItem to delete an item in DynamoDB.

func (*Client) Put added in v0.4.0

func (c *Client) Put(ctx context.Context, item Keyer) error

Put calls PutItem to create or update an item in DynamoDB.

func (*Client) PutBatch added in v0.4.0

func (c *Client) PutBatch(ctx context.Context, items ...Keyer) error

PutBatch calls BatchWriteItem to create or update items in DynamoDB.

DynamoDB BatchWriteItem api has a limit of 25 items per batch. PutBatch will automatically split the items into batches of 25 by default.

You can override this default batch size using WithBatchSize(n) when you initialize the client.

func (*Client) Query added in v0.4.0

func (c *Client) Query(ctx context.Context, qb QueryBuilder, opts ...func(*QueryOpts)) (*QueryResult, error)

Query DynamoDB using a given QueryBuilder. Under the hood, this uses the QueryItems API.

The QueryBuilder 'qb' defines the query, as well as how to unmarshal the result back into Go objects. The unmarshaling logic works as follows:

1. If qb implements UnmarshalQueryOutput, call it and return.

2. If qb contains a field with a `ddb:"result"` struct tag, unmarshal results to that field.

3. Unmarshal the results directly to qb.

The examples in this package show how to write simple and complex access patterns which use each of the three methods above.

func (*Client) TransactWriteItems added in v0.6.0

func (c *Client) TransactWriteItems(ctx context.Context, tx []TransactWriteItem) error

type JSONTokenizer added in v0.8.0

type JSONTokenizer struct{}

func (*JSONTokenizer) MarshalToken added in v0.8.0

func (e *JSONTokenizer) MarshalToken(item map[string]types.AttributeValue) (string, error)

func (*JSONTokenizer) UnmarshalToken added in v0.8.0

func (e *JSONTokenizer) UnmarshalToken(s string) (map[string]types.AttributeValue, error)

type Keyer added in v0.4.0

type Keyer interface {
	DDBKeys() (Keys, error)
}

Keyers give DynamoDB keys to be used when inserting an item.

type Keys added in v0.4.0

type Keys struct {
	PK     string
	SK     string
	GSI1PK string `json:",omitempty"`
	GSI1SK string `json:",omitempty"`
	GSI2PK string `json:",omitempty"`
	GSI2SK string `json:",omitempty"`
	GSI3PK string `json:",omitempty"`
	GSI3SK string `json:",omitempty"`
	GSI4PK string `json:",omitempty"`
	GSI4SK string `json:",omitempty"`
}

Keys are primary and Global Secondary Index (GSI) keys to be used when storing an item in DynamoDB. The ddb package is opinionated on the naming of these keys.

type QueryBuilder added in v0.4.0

type QueryBuilder interface {
	BuildQuery() (*dynamodb.QueryInput, error)
}

QueryBuilders build query inputs for DynamoDB access patterns. The inputs are passed to the QueryItems DynamoDB API.

When writing a new QueryBuilder access pattern you should always implement integration tests for it against a live DynamoDB database.

type QueryOpts added in v0.8.0

type QueryOpts struct {
	PageToken string
	Limit     int32
}

type QueryOutputUnmarshaler added in v0.4.0

type QueryOutputUnmarshaler interface {
	UnmarshalQueryOutput(out *dynamodb.QueryOutput) error
}

QueryOutputUnmarshalers implement custom logic to unmarshal the results of a DynamoDB QueryItems call.

type QueryResult added in v0.8.0

type QueryResult struct {
	// RawOutput is the DynamoDB API response. Usually you won't need this,
	// as results are parsed onto the QueryBuilder argument.
	RawOutput *dynamodb.QueryOutput

	// NextPage is the next page token. If empty, there is no next page.
	NextPage string
}

type Storage added in v0.4.0

type Storage interface {
	Query(ctx context.Context, qb QueryBuilder, opts ...func(*QueryOpts)) (*QueryResult, error)
	Put(ctx context.Context, item Keyer) error
	PutBatch(ctx context.Context, items ...Keyer) error
	TransactWriteItems(ctx context.Context, tx []TransactWriteItem) error
	Delete(ctx context.Context, item Keyer) error
}

Storage defines a common interface to make testing ddb easier. Both the real and mock clients meet this interface.

type Tokenizer added in v0.8.0

type Tokenizer interface {
	MarshalToken(item map[string]types.AttributeValue) (string, error)
	UnmarshalToken(s string) (map[string]types.AttributeValue, error)
}

Tokenizer converts DynamoDB page cursor items to and from opaque strings.

type TransactWriteItem added in v0.6.0

type TransactWriteItem struct {
	Put Keyer
}

TransactWriteItem is a wrapper over the DynamoDB TransactWriteItem type. Currently, only the Put option is exposed. The API supports other operations which can be added to this struct.

see: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html

Directories

Path Synopsis
cmd

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL