gocloud.dev: gocloud.dev/docstore/awsdynamodb Index | Examples | Files

package awsdynamodb

import "gocloud.dev/docstore/awsdynamodb"

Package awsdynamodb provides a docstore implementation backed by Amazon DynamoDB. Use OpenCollection to construct a *docstore.Collection.


For docstore.OpenCollection, awsdynamodb registers for the scheme "dynamodb". The default URL opener will use an AWS session with the default credentials and configuration; see https://docs.aws.amazon.com/sdk-for-go/api/aws/session/ for more details. To customize the URL opener, or for more details on the URL format, see URLOpener. See https://gocloud.dev/concepts/urls/ for background information.


awsdynamodb exposes the following types for As:

- Collection.As: *dynamodb.DynamoDB
- ActionList.BeforeDo: *dynamodb.BatchGetItemInput or *dynamodb.PutItemInput or *dynamodb.DeleteItemInput
                       or *dynamodb.UpdateItemInput
- Query.BeforeQuery: *dynamodb.QueryInput or *dynamodb.ScanInput
- DocumentIterator: *dynamodb.QueryOutput or *dynamodb.ScanOutput
- ErrorAs: awserr.Error


// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
// PRAGMA: On gocloud.dev, add a blank import: _ "gocloud.dev/docstore/awsdynamodb"
// PRAGMA: On gocloud.dev, hide lines until the next blank line.
ctx := context.Background()

// docstore.OpenCollection creates a *docstore.Collection from a URL.
coll, err := docstore.OpenCollection(ctx, "dynamodb://my-table?partition_key=name")
if err != nil {
defer coll.Close()



Package Files

codec.go dynamo.go query.go urls.go


const Scheme = "dynamodb"

Scheme is the URL scheme dynamodb registers its URLOpener under on docstore.DefaultMux.


var Set = wire.NewSet(
    wire.Struct(new(URLOpener), "ConfigProvider"),

Set holds Wire providers for this package.

func Dial Uses

func Dial(p client.ConfigProvider) (*dyn.DynamoDB, error)

Dial gets an AWS DynamoDB service client.

func OpenCollection Uses

func OpenCollection(db *dyn.DynamoDB, tableName, partitionKey, sortKey string, opts *Options) (*docstore.Collection, error)

OpenCollection creates a *docstore.Collection representing a DynamoDB collection.


// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
sess, err := session.NewSession()
if err != nil {
coll, err := awsdynamodb.OpenCollection(
    dynamodb.New(sess), "docstore-test", "partitionKeyField", "", nil)
if err != nil {
defer coll.Close()

type FallbackFunc Uses

type FallbackFunc func(context.Context, *driver.Query, RunQueryFunc) (driver.DocumentIterator, error)

FallbackFunc is a function for executing queries that cannot be run by the built-in awsdynamodb logic. See Options.RunQueryFunc for details.

func InMemorySortFallback Uses

func InMemorySortFallback(createDocument func() interface{}) FallbackFunc

InMemorySortFallback returns a query fallback function for Options.RunQueryFallback. The function accepts a query with an OrderBy clause. It runs the query without that clause, reading all documents into memory, then sorts the documents according to the OrderBy clause.

Only string, numeric, time and binary ([]byte) fields can be sorted.

createDocument should create an empty document to be passed to DocumentIterator.Next. The DocumentIterator returned by the FallbackFunc will also expect the same type of document. If nil, then a map[string]interface{} will be used.

type Options Uses

type Options struct {
    // If false, queries that can only be executed by scanning the entire table
    // return an error instead (with the exception of a query with no filters).
    AllowScans bool

    // The name of the field holding the document revision.
    // Defaults to docstore.DefaultRevisionField.
    RevisionField string

    // If set, call this function on queries that we cannot execute at all (for
    // example, a query with an OrderBy clause that lacks an equality filter on a
    // partition key). The function should execute the query however it wishes, and
    // return an iterator over the results. It can use the RunQueryFunc passed as its
    // third argument to have the DynamoDB driver run a query, for instance a
    // modified version of the original query.
    // If RunQueryFallback is nil, queries that cannot be executed will fail with a
    // error that has code Unimplemented.
    RunQueryFallback FallbackFunc

    // The maximum number of concurrent goroutines started for a single call to
    // ActionList.Do. If less than 1, there is no limit.
    MaxOutstandingActionRPCs int

    // If true, a strongly consistent read is used whenever possible, including
    // get, query, scan, etc.; default to false, where an eventually consistent
    // read is used.
    // Not all read operations support this mode however, such as querying against
    // a global secondary index, the operation will return an InvalidArgument error
    // in such case, please check the official DynamoDB documentation for more
    // details.
    // The native client for DynamoDB uses this option in a per-action basis, if
    // you need the flexibility to run both modes on the same collection, create
    // two collections with different mode.
    ConsistentRead bool

type RunQueryFunc Uses

type RunQueryFunc func(context.Context, *driver.Query) (driver.DocumentIterator, error)

RunQueryFunc is the type of the function passed to RunQueryFallback.

type URLOpener Uses

type URLOpener struct {
    // ConfigProvider must be set to a non-nil value.
    ConfigProvider client.ConfigProvider

URLOpener opens dynamodb URLs like "dynamodb://mytable?partition_key=partkey&sort_key=sortkey".

The URL Host is used as the table name. See https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html for more details.

The following query parameters are supported:

- partition_key (required): the path to the partition key of a table or an index.
- sort_key: the path to the sort key of a table or an index.
- allow_scans: if "true", allow table scans to be used for queries

See https://godoc.org/gocloud.dev/aws#ConfigFromURLParams for supported query parameters for overriding the aws.Session from the URL.

func (*URLOpener) OpenCollectionURL Uses

func (o *URLOpener) OpenCollectionURL(_ context.Context, u *url.URL) (*docstore.Collection, error)

OpenCollectionURL opens the collection at the URL's path. See the package doc for more details.

Package awsdynamodb imports 23 packages (graph) and is imported by 2 packages. Updated 2019-08-12. Refresh now. Tools for package owners.