awsdynamodb

Documentation

Overview

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

URLs

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.

As

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

Example (OpenCollectionFromURL)

package main

import (
	"context"
	"log"

	"gocloud.dev/docstore"
)

func main() {
	// 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 {
		log.Fatal(err)
	}
	defer coll.Close()
}

Index

• Constants
• Variables
• func Dial(p client.ConfigProvider) (*dyn.DynamoDB, error)
• func OpenCollection(db *dyn.DynamoDB, tableName, partitionKey, sortKey string, opts *Options) (*docstore.Collection, error)
• type FallbackFunc
  • func InMemorySortFallback(createDocument func() interface{}) FallbackFunc
• type Options
• type RunQueryFunc
• type URLOpener
  • func (o *URLOpener) OpenCollectionURL(_ context.Context, u *url.URL) (*docstore.Collection, error)

Examples

• Package (OpenCollectionFromURL)
• OpenCollection

Constants

const Scheme = "dynamodb"

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

Variables

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

Set holds Wire providers for this package.

Functions

func Dial

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

Dial gets an AWS DynamoDB service client.

func OpenCollection

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

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

Example

package main

import (
	"log"

	"github.com/aws/aws-sdk-go/aws/session"
	"github.com/aws/aws-sdk-go/service/dynamodb"
	"gocloud.dev/docstore/awsdynamodb"
)

func main() {
	// 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 {
		log.Fatal(err)
	}
	coll, err := awsdynamodb.OpenCollection(
		dynamodb.New(sess), "docstore-test", "partitionKeyField", "", nil)
	if err != nil {
		log.Fatal(err)
	}
	defer coll.Close()
}

Types

type FallbackFunc

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

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

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

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

RunQueryFunc is the type of the function passed to RunQueryFallback.

type URLOpener

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
• consistent_read: if "true", a strongly consistent read is used whenever possible.

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

func (*URLOpener) OpenCollectionURL

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.