guregu/dynamo

You can specify the schema for creating tables (including Hash keys, Range keys, and Indexes) directly in your Go structs using dynamo, index, and localIndex tags.

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"` 
}

If you need to use the official dynamodbattribute encoding (using dynamodbav tags), you must wrap your objects with dynamo.AWSEncoding.

Note: When retrieving an item, you must pass a pointer to AWSEncoding to the One method.

// Notice the use of the dynamodbav struct tag
type book struct {
	ID    int    `dynamodbav:"id"` 
	Title string `dynamodbav:"title"` 
}

// Putting an item
err := db.Table("Books").Put(dynamo.AWSEncoding(book{
	ID:    42,
	Title: "Principia Discordia",
})).Run(ctx)

// When getting an item you MUST pass a pointer to AWSEncoding!
var someBook book
err := db.Table("Books").Get("ID", 555).One(ctx, dynamo.AWSEncoding(&someBook))

In v2, dynamo relies on the AWS SDK for retries. By default, canceled transactions (conflicting transactions) are not retried. To enable automatic retrying for transaction conflicts, configure the AWS SDK Retryer with dynamo.RetryTxConflicts.

import (
	"context"
	"log"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/aws/retry"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/guregu/dynamo/v2"
)

func main() {
	cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
		return retry.NewStandard(dynamo.RetryTxConflicts)
	}))
	if err != nil {
		log.Fatal(err)
	}
	db := dynamo.New(cfg)
	// use db
}

To run integration tests against a local instance (e.g., via Docker), set the following environment variables and run go test:

# Use Docker to run DynamoDB local on port 8880
docker compose -f '.github/docker-compose.yml' up -d

# Run the tests with a fresh table
DYNAMO_TEST_ENDPOINT='http://localhost:8880' \
	DYNAMO_TEST_REGION='local' \
	DYNAMO_TEST_TABLE='TestDB-%' \
	AWS_ACCESS_KEY_ID='dummy' \
	AWS_SECRET_ACCESS_KEY='dummy' \
	AWS_REGION='local' \
	go test -v -race ./... -cover -coverpkg=./...

The Iter interface is used for traversing result sets. There are three specialized types of iterators:

• Iter: The base interface for sequential traversal using Next(ctx, out) and Err().
• PagingIter: An iterator that supports pagination. It provides LastEvaluatedKey(ctx) which returns a PagingKey. You can pass this key to StartFrom in subsequent Query or Scan calls to resume pagination.
• ParallelIter: An iterator representing combined results from multiple parallel segments. It provides LastEvaluatedKeys(ctx) which returns a slice of PagingKey objects, one for each parallel segment.

To speed up large scans, use IterParallel(ctx context.Context, segments int). This method automatically splits the table into the specified number of segments and runs them in parallel using goroutines.

Key behaviors:

• Canceling the provided ctx will cancel all underlying segment scans.
• It returns a ParallelIter which can be used to iterate over items across all segments as they arrive.
• It is more efficient than manual segmentation for large datasets.

When using conditional puts, you can control whether the item that caused the condition check failure is included in the error response using IncludeItemInCondCheckFail(bool).

• If enabled is true, the item is included in the error, which can be extracted using UnmarshalItemFromCondCheckFailed (for single puts) or UnmarshalItemsFromTxCondCheckFailed (for transactions).
• If false, the item is not included.

This is particularly useful when using CurrentValue, which uses ReturnValuesOnConditionCheckFailureAllOld internally to allow you to inspect the existing item when a write fails due to a condition.

The Description struct includes GSI (Global Secondary Indexes) and LSI (Local Secondary Indexes) as slices of Index objects.

An Index object contains:

• Name and ARN.
• Status and Backfilling (for GSIs).
• Local: A boolean that is true for LSIs and false for GSIs.
• HashKey / RangeKey and their respective KeyTypes.
• HashKeys / RangeKeys: Used for composite GSIs with multiple keys.
• Throughput: The provisioned throughput for the index.
• ProjectionType: The type of index projection.
• ProjectionAttribs: The non-key attributes included in the projection (if ProjectionType is IncludeProjection).