dynago

package module
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 23, 2024 License: MIT Imports: 11 Imported by: 0

README

go-dynamodb

import (
  "github.com/oolio-group/dynago"
)

table, err := dynago.NewClient(ctx, dynago.ClientOptions{
  TableName:        "test-table",
  Region:           os.Getenv("AWS_REGION"),
  PartitionKeyName: "pk",
  SortKeyName:      "sk",
})

Usage with local dynamodb

Run dynago.locally
docker run -p docker run -p 8000:8000 amazon/dynago.local

import (
  "github.com/oolio-group/dynago"
)

table, err := dynago.NewClient(ctx, dynamite.ClientOptions{
  TableName: "test",
  Endpoint: &dynago.EndpointResolver{
    EndpointURL:     "http://localhost:8000",
    AccessKeyID:     "dummy",
    SecretAccessKey: "dummy",
  },
  PartitionKeyName: "pk",
  SortKeyName:      "sk",
  Region:           "us-east-1",
})
Get item
var jon Person
err, found := table.GetItem(ctx, dynago.StringValue("pk_jon"), dynago.StringValue("sk_jon"), &jon)
if err != nil {
  // connection or query error
  return err
}
if !found {
  // item does not exist
}

fmt.Println(jon)
Batch Get Items
var ids = [3]string{"1", "2", "3"}
var users []User
var items = make([]dynago.AttributeRecord, 0, len(ids))
for _, id := range ids {
  items = append(items, map[string]dynago.AttributeValue{
    "pk": dynago.StringValue("user#" + id),
    "sk": dynago.StringValue("user#" + id),
  })
}
err := table.BatchGetItems(ctx, items, &users)
if err != nil {
  // connection or query error
  return err
}
fmt.Println(users)
Put Item
event := Event{ Id: "one", Timestamp: time.Now().Unix() }
err := table.PutItem(
  context.TODO(),
  dynago.StringValue("event#"+event.id),
  dynago.NumberValue(event.Timestamp),
  &event
)
Query
var peeps []Person
_, found := table.Query(ctx,"pk = :pk_val", map[string]dynago.Attribute{
  ":pk_val": dynago.StringValue("merchant#id"),
}, &peeps)
if err != nil {
  // connection or query error
  return err
}

fmt.Println(peeps)
Query with options

Fetch 10 items from gsi1 index sorted in descending order (using sk)

table.Query(ctx, "pk = :pk_val", map[string]dynago.Attribute{
  ":pk_val": dynago.StringValue("merchant#id"),
}, &out, dynago.WithIndex("gsi1"), dynago.SortByAsc(false), dynago.WithLimit(10))
Query with pagination

Fetch 10 items per page

// get first page
cursor, err := table.Query(ctx, "pk = :pk_val", map[string]dynago.Attribute{
  ":pk_val": dynago.StringValue("merchant#id"),
}, &out, dynago.WithLimit(10))

// get next page
if cursor != nil {
  cursor, err := table.Query(ctx, "pk = :pk_val", map[string]dynago.Attribute{
    ":pk_val": dynago.StringValue("merchant#id"),
  }, &out, dynago.WithLimit(10), dynago.WithCursorKey(cursor))
}

Running Tets

By default, tests are run in offline mode. Using https://github.com/ory/dockertest, ephermal amazon/dynago.local containers are created for tests.

Requirements

Docker must be installed and docker must be on $PATH

yarn test # runs go test ./...

Documentation

Index

Constants

View Source 
const ChunkSize = 25

Variables

This section is empty.

Functions

func BoolValue 

func BoolValue(v bool) *types.AttributeValueMemberBOOL

func NumberValue 

func NumberValue(v int64) *types.AttributeValueMemberN

func StringValue 

func StringValue(v string) *types.AttributeValueMemberS

Types

type Attribute 

type Attribute = types.AttributeValue

type AttributeRecord 

type AttributeRecord = map[string]Attribute

type Client 

type Client struct {
	TableName string
	Keys      map[string]string
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(ctx context.Context, opt ClientOptions) (*Client, error)

Create a new instance of DynamoTable. internally creates aws connection configuration for the db If DynamoTable.Endpoint is specified connects to the db at the given URL, or the default credential of the system is used To connect to AWS DynamoDB from a running pod or EC2 instance, use the default credentials without Endpoint option To connect to a local DynamoDB process, provider Endpoint 

table, err := dynamite.NewDynamoTable(dynamite.ClientOptions{
  TableName: "test",
  Endpoint: &dynamite.EndpointResolver{
    EndpointURL:     "http://localhost:" + port,
    AccessKeyID:     "dummy",
    SecretAccessKey: "dummy",
  },
  PartitionKeyName: "pk",
  SortKeyName:      "sk",
  Region:           "us-east-1",
})

func (*Client) BatchDeleteItems 

func (t *Client) BatchDeleteItems(ctx context.Context, input []map[string]types.AttributeValue) []map[string]types.AttributeValue

* * Used to batch delete records from dynamodb * @param input slice of record want to put to DB * @return error

func (*Client) BatchGetItems 

func (t *Client) BatchGetItems(ctx context.Context, input []AttributeRecord, out interface{}) (err error)

func (*Client) BatchWriteItems 

func (t *Client) BatchWriteItems(ctx context.Context, input []map[string]types.AttributeValue) error

func (*Client) DeleteItem 

func (t *Client) DeleteItem(ctx context.Context, pk string, sk string) error

* * Used to delete a db record from dynamodb given a partition key and sort key * @param pk the partition key of the record * @param sk the sort key of the record

  • @return true if the record was deleted, false otherwise

func (*Client) GetDynamoDBClient 

func (t *Client) GetDynamoDBClient() *dynamodb.Client

func (*Client) GetItem 

func (t *Client) GetItem(ctx context.Context, pk Attribute, sk Attribute, out interface{}) (err error, found bool)

Used to get a db record from dynamodb given a partition key and sort key @param partitionKey the partition key of the record @param sortKey the sort key of the record @param result the result of the query written to given memory reference @return error, true if the record was found, false otherwise

func (*Client) NewKeys 

func (t *Client) NewKeys(pk Attribute, sk Attribute) map[string]Attribute

Generate DynamoDB item key map for the given value Name of the keys were registered during the NewDynamoTable call

func (*Client) PutItem 

func (t *Client) PutItem(ctx context.Context, pk Attribute, sk Attribute, item interface{}) error

* * Used to put and update a db record from dynamodb given a partition key and sort key * @param item the item put into the database

  • @return true if the record was put, false otherwise

func (*Client) Query 

func (t *Client) Query(
	ctx context.Context,
	condition string, values map[string]Attribute, out interface{}, opts ...QueryOptions,
) (cursor map[string]Attribute, err error)

TODO: improve with generics and avoid the `out` argument

func (*Client) TransactDeleteItems 

func (t *Client) TransactDeleteItems(ctx context.Context, inputs []*TransactDeleteItemsInput) error

TODO: [low priority] The aggregate size of the items in the transaction cannot exceed 4 MB.

func (*Client) TransactItems 

func (t *Client) TransactItems(ctx context.Context, input ...types.TransactWriteItem) error

func (*Client) TransactPutItems 

func (t *Client) TransactPutItems(ctx context.Context, inputs []*TransactPutItemsInput) error

TransactWriteItems is a synchronous and idempotent write operation that groups up to 100 write actions in a single all-or-nothing operation. These actions can target up to 100 distinct items in one or more DynamoDB tables within the same AWS account and in the same Region. The aggregate size of the items in the transaction cannot exceed 4 MB. The actions are completed atomically so that either all of them succeed or none of them succeeds.

func (*Client) WithDeleteItem 

func (t *Client) WithDeleteItem(pk string, sk string) types.TransactWriteItem

func (*Client) WithPutItem 

func (t *Client) WithPutItem(pk string, sk string, item interface{}) types.TransactWriteItem

type ClientOptions 

type ClientOptions struct {
	TableName        string
	Region           string
	PartitionKeyName string
	SortKeyName      string
	Endpoint         *EndpointResolver
	Middlewares      []func(*aws.Config)
}

type DynamoClient 

type DynamoClient interface {
	ReadAPI
	WriteAPI
	QueryAPI
	TransactionAPI
}

type EndpointResolver 

type EndpointResolver struct {
	EndpointURL     string
	AccessKeyID     string
	SecretAccessKey string
}

func (EndpointResolver) ResolveEndpoint 

func (r EndpointResolver) ResolveEndpoint(s string, region string, o ...interface{}) (aws.Endpoint, error)

type Index 

type Index struct {
	IndexName        string
	PartitionKeyName string
	SortKeyName      string
}

type QueryAPI 

type QueryAPI interface {
	// Perform a DynamoDB query with the key condition expression in first argument.
	//
	// If key condition contains template params eg: pk = :pk for values, second argument should provide values
	Query(ctx context.Context, condition string, params map[string]Attribute, out interface{}, opts ...QueryOptions) (map[string]Attribute, error)
}

type QueryInput 

type QueryInput = dynamodb.QueryInput

type QueryOptions 

type QueryOptions func(q *dynamodb.QueryInput)

Fuction Struct for providing option input prams

func SortByAsc 

func SortByAsc(v bool) QueryOptions

FIXME: WithDescOrder instead? SortByAsc(true) doesn't make sense as dynamodb sorts by asc (default)

func WithCursorKey 

func WithCursorKey(key map[string]Attribute) QueryOptions

func WithFields 

func WithFields(fields []string) QueryOptions

WithFields func to be passed as optional param function to select specfic fielld from the db enity

func WithFilter 

func WithFilter(filterCon string) QueryOptions

func WithIndex 

func WithIndex(i string) QueryOptions

func WithLimit 

func WithLimit(v int32) QueryOptions

type ReadAPI 

type ReadAPI interface {
	GetItem(ctx context.Context, pk Attribute, sk Attribute, out interface{}) (error, bool)
	BatchGetItems(ctx context.Context, input []AttributeRecord, out interface{}) error
}

type TransactDeleteItemsInput 

type TransactDeleteItemsInput struct {
	PartitionKeyValue Attribute
	SortKeyValue      Attribute
}

type TransactPutItemsInput 

type TransactPutItemsInput struct {
	PartitionKeyValue Attribute
	SortKeyValue      Attribute
	Item              interface{}
}

type TransactWriteItem 

type TransactWriteItem types.TransactWriteItem

type TransactionAPI 

type TransactionAPI interface {
	TransactPutItems(ctx context.Context, items []*TransactPutItemsInput) error
	TransactItems(ctx context.Context, input ...types.TransactWriteItem) error
}

type WriteAPI 

type WriteAPI interface {
	// Create or update given item in DynamoDB. Must implemenmt DynamoRecord interface.
	// DynamoRecord.GetKeys will be called to get values for parition and sort keys.
	PutItem(ctx context.Context, pk Attribute, sk Attribute, item interface{}) error
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.