A DynamoDB client for Go
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
internal Add NewAwsClientFromEnv, to run on AWS Lambda Jan 29, 2017
schema Fix some faux pas by 'go vet' Feb 10, 2016
streams More doc updates Mar 2, 2016
.travis.yml Fix travis build for v1 Jul 22, 2015
LICENSE.txt Fix type in LICENSE Mar 1, 2016
README.md Add NewAwsClientFromEnv, to run on AWS Lambda Jan 29, 2017
client.go Hide the new parameter from NewAwsExecutor to maintain semver Mar 28, 2017
client_env.go Hide the new parameter from NewAwsExecutor to maintain semver Mar 28, 2017
client_test.go Fix issues with endpoint urls and signing Jul 25, 2015
const.go More docs updates Apr 6, 2016
consumed_capacity.go More docs updates Apr 6, 2016
consumed_capacity_test.go Consumed Capacity reporting Oct 13, 2015
doc.go More docs updates Apr 6, 2016
errors.go More docs updates Apr 6, 2016
errors_test.go Apply stringer to errors; better error display Jul 24, 2015
example_client_test.go Add ConsistentRead to BatchGet and better docs Aug 19, 2015
example_test.go Move dynago to gopkg.in and pin first version Jul 22, 2015
executor.go Hide the new parameter from NewAwsExecutor to maintain semver Mar 28, 2017
functional_test.go Add ConsistentRead to Scan query Aug 7, 2017
helpers.go More docs updates Apr 6, 2016
mock_executor.go More doc updates Mar 2, 2016
mock_executor_test.go Add a helper function dynago.P for specifying params. Feb 10, 2016
request_batch.go Improvements to godoc comments Feb 10, 2016
request_batch_test.go Add ConsistentRead to BatchGet and better docs Aug 19, 2015
request_delete_item.go Consumed Capacity reporting Oct 13, 2015
request_get_item.go Improvements to godoc comments Feb 10, 2016
request_item_test.go Add ScanIndexForward for easier query building Aug 6, 2015
request_put_item.go Add Key to UpdateItem and Item to PutItem for more reusability. Apr 6, 2016
request_query.go Improvements to godoc comments Feb 10, 2016
request_scan.go Add ConsistentRead to Scan query Aug 7, 2017
request_table.go Documentation updates Mar 1, 2016
request_update_item.go Add Key to UpdateItem and Item to PutItem for more reusability. Apr 6, 2016
types.go More doc updates Mar 2, 2016
types_test.go Improvements to godoc comments Feb 10, 2016
wire.go Support encoding nils on the dynamo wire protocol Oct 13, 2015
wire_test.go Improvements to godoc comments Feb 10, 2016

README.md

Dynago

Build Status GoDoc

Dynago is a DynamoDB client API for Go.

Key design tenets of Dynago:

  • Most actions are done via chaining to build filters and conditions
  • objects are completely safe for passing between goroutines (even queries and the like)
  • To make understanding easier via docs, we use Amazon's naming wherever possible.

Installation

Install using go get:

go get gopkg.in/underarmour/dynago.v1

Docs are at http://godoc.org/gopkg.in/underarmour/dynago.v1

Example

Run a query:

client := dynago.NewAwsClient(region, accessKey, secretKey)
// or you can use below if you have AWS credential values in ENV,
// in case of running on AWS Lambda, etc.
// client := dynago.NewAwsClientFromEnv()

query := client.Query(table).
	KeyConditionExpression("UserId = :uid", dynago.P(":uid", 42)).
	FilterExpression("NumViews > :views").
	Param(":views", 50).
	Desc()

result, err := query.Execute()
if err != nil {
	// do something
}
for _, row := range result.Items {
	fmt.Printf("Name: %s, Views: %d", row["Name"], row["NumViews"])
}

Type Marshaling

Dynago lets you use go types instead of having to understand a whole lot about dynamo's internal type system.

Example:

doc := dynago.Document{
	"name": "Bob",
	"age": 45,
	"height": 2.1,
	"address": dynago.Document{
		"city": "Boston",
	},
	"tags": dynago.StringSet{"male", "middle_aged"},
}
client.PutItem("person", doc).Execute()
  • Strings use golang string
  • Numbers can be input as int (int64, uint64, etc) or float64 but always are returned as dynago.Number to not lose precision.
  • Maps can be either map[string]interface{} or dynago.Document
  • Opaque binary data can be put in []byte
  • String sets, number sets, binary sets are supported using dynago.StringSet dynago.NumberSet dynago.BinarySet
  • Lists are supported using dynago.List
  • time.Time is only accepted if it's a UTC time, and is marshaled to a dynamo string in iso8601 compact format. It comes back as a string, an can be got back using GetTime() on Document.

Debugging

Dynago can dump request or response information for you to use in debugging. Simply set dynago.Debug with the necessary flags:

dynago.Debug = dynago.DebugRequests | dynago.DebugResponses

If you would like to change how the debugging is printed, please set dynago.DebugFunc to your preference.

Version Compatibility

Dynago follows Semantic Versioning via the gopkg.in interface, and within the v1 chain, we will not break the existing API or behaviour of existing code using Dynago. We will add new methods and features, but it again should not break code.

Additional resources

The past, and the future

Dynago currently implements all of its support for the underlying DynamoDB API encoding, AWS signing/authentication, etc. This happened in part because the existing libraries out there at the time of writing used deprecated API's and complicated methods, and it was actually cleaner at the time to support the API by fresh implementation.

AWS-SDK-Go exists as of June 2015 and has a very up to date API, but the API is via bare structs which minimally wrap protocol-level details of DynamoDB, resulting in it being very verbose for writing applications (dealing with DynamoDB's internal type system is boilerplatey). Once Amazon has brought it out of developer preview, the plan is to have Dynago use it as the underlying protocol and signature implementation, but keep providing Dynago's clean and simple API for building queries and marshaling datatypes in DynamoDB.