README
¶
ddb
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:
Index ¶
- Variables
- func Limit(limit int32) func(*QueryOpts)
- func Page(pageToken string) func(*QueryOpts)
- func WithBatchSize(batchSize int) func(*Client)
- func WithDynamoDBClient(d *dynamodb.Client) func(*Client)
- func WithPageTokenizer(e Tokenizer) func(*Client)
- type Client
- func (c *Client) Delete(ctx context.Context, item Keyer) error
- func (c *Client) Put(ctx context.Context, item Keyer) error
- func (c *Client) PutBatch(ctx context.Context, items ...Keyer) error
- func (c *Client) Query(ctx context.Context, qb QueryBuilder, opts ...func(*QueryOpts)) (*QueryResult, error)
- func (c *Client) TransactWriteItems(ctx context.Context, tx []TransactWriteItem) error
- type JSONTokenizer
- type Keyer
- type Keys
- type QueryBuilder
- type QueryOpts
- type QueryOutputUnmarshaler
- type QueryResult
- type Storage
- type Tokenizer
- type TransactWriteItem
Examples ¶
Constants ¶
This section is empty.
Variables ¶
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.
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
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
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
WithBatchSize allows a custom batchSize to be provided for putBatch operations.
func WithDynamoDBClient ¶ added in v0.4.0
WithDynamoDBClient allows a custom dynamodb.Client to be provided.
func WithPageTokenizer ¶ added in v0.8.0
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 (*Client) PutBatch ¶ added in v0.4.0
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 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 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