dynamodb

Documentation

Overview

Package dynamodb provides a typed DynamoDB integration block. It wraps the AWS SDK v2 DynamoDB client and exposes a minimal, strongly-typed CRUD API. The block is generic over T, the item model struct.

Index

• type Block
  • func New[T any](name string, opts ...Option) *Block[T]
  • func (b *Block[T]) DeleteItem(ctx context.Context, partitionKeyValue, sortKeyValue any) error
  • func (b *Block[T]) GetItem(ctx context.Context, partitionKeyValue, sortKeyValue any) (T, error)
  • func (b *Block[T]) Init(ctx context.Context) error
  • func (b *Block[T]) Name() string
  • func (b *Block[T]) PutItem(ctx context.Context, item T) error
  • func (b *Block[T]) QueryItems(ctx context.Context, in QueryInput) (Page[T], error)
  • func (b *Block[T]) ScanItems(ctx context.Context, limit *int32, lastKey map[string]types.AttributeValue) (Page[T], error)
  • func (b *Block[T]) Shutdown(_ context.Context) error
• type Option
  • func WithAWSConfig(cfg aws.Config) Option
  • func WithEndpoint(endpoint string) Option
  • func WithPartitionKey(pk string) Option
  • func WithProfile(profile string) Option
  • func WithRegion(region string) Option
  • func WithSortKey(sk string) Option
  • func WithTable(name string) Option
• type Page
• type QueryInput

Types

type Block

type Block[T any] struct {
	// contains filtered or unexported fields
}

Block is a typed DynamoDB integration block.

T is the Go struct that maps to a DynamoDB item via the `dynamodbav` struct tag. All CRUD operations are strongly typed over T, eliminating manual marshalling.

func New

func New[T any](name string, opts ...Option) *Block[T]

New creates a new DynamoDB Block with the given name and options.

block := dynamodb.New[User]("users",
    dynamodb.WithRegion("us-east-1"),
    dynamodb.WithTable("users-prod"),
    dynamodb.WithPartitionKey("id"),
)

func (*Block[T]) DeleteItem

func (b *Block[T]) DeleteItem(ctx context.Context, partitionKeyValue, sortKeyValue any) error

DeleteItem removes a single item by its primary key. sortKeyValue is ignored when the table has no sort key.

func (*Block[T]) GetItem

func (b *Block[T]) GetItem(ctx context.Context, partitionKeyValue, sortKeyValue any) (T, error)

GetItem retrieves a single item by its primary key. sortKeyValue is ignored when the table has no sort key (WithSortKey was not set). Returns core.ErrItemNotFound when the item does not exist.

func (*Block[T]) Init

func (b *Block[T]) Init(ctx context.Context) error

Init implements core.Block. It resolves the AWS config and creates the DynamoDB client. A custom endpoint is applied here if WithEndpoint was set.

func (*Block[T]) Name

func (b *Block[T]) Name() string

Name implements core.Block.

func (*Block[T]) PutItem

func (b *Block[T]) PutItem(ctx context.Context, item T) error

PutItem marshals item into a DynamoDB AttributeValue map and writes it to the configured table. It performs a full replace if the key already exists.

func (*Block[T]) QueryItems

func (b *Block[T]) QueryItems(ctx context.Context, in QueryInput) (Page[T], error)

QueryItems executes a DynamoDB Query and returns a paginated Page[T]. Use QueryInput.LastEvaluatedKey from a previous Page to fetch the next page.

func (*Block[T]) ScanItems

func (b *Block[T]) ScanItems(ctx context.Context, limit *int32, lastKey map[string]types.AttributeValue) (Page[T], error)

ScanItems performs a full table scan with optional pagination. Prefer QueryItems for production workloads; scans read every item.

func (*Block[T]) Shutdown

func (b *Block[T]) Shutdown(_ context.Context) error

Shutdown implements core.Block. The DynamoDB SDK v2 client requires no explicit teardown, but the method is present for interface compliance.

type Option

type Option func(*blockConfig)

Option configures a DynamoDB Block.

func WithAWSConfig

func WithAWSConfig(cfg aws.Config) Option

WithAWSConfig injects a pre-built aws.Config, bypassing automatic resolution.

func WithEndpoint

func WithEndpoint(endpoint string) Option

WithEndpoint overrides the DynamoDB endpoint (e.g. "http://localhost:8000" for DynamoDB Local or LocalStack).

func WithPartitionKey

func WithPartitionKey(pk string) Option

WithPartitionKey sets the attribute name of the table's partition key.

func WithProfile

func WithProfile(profile string) Option

WithProfile selects a named AWS credentials profile.

func WithRegion

func WithRegion(region string) Option

WithRegion sets the AWS region used to resolve credentials and endpoints.

func WithSortKey

func WithSortKey(sk string) Option

WithSortKey sets the attribute name of the table's sort key. Omit this option for single-key tables.

func WithTable

func WithTable(name string) Option

WithTable sets the DynamoDB table name.

type Page

type Page[T any] struct {
	Items            []T
	LastEvaluatedKey map[string]types.AttributeValue
	Count            int32
	ScannedCount     int32
}

Page is a paginated result set.

type QueryInput

type QueryInput struct {
	// KeyConditionExpression is required (e.g. "id = :pk AND begins_with(sk, :prefix)").
	KeyConditionExpression string
	// ExpressionAttributeNames maps placeholder tokens to actual attribute names.
	ExpressionAttributeNames map[string]string
	// ExpressionAttributeValues maps value placeholders to AttributeValues.
	ExpressionAttributeValues map[string]types.AttributeValue
	// FilterExpression is an optional server-side filter applied after the query.
	FilterExpression string
	// IndexName targets a Global or Local Secondary Index instead of the base table.
	IndexName string
	// Limit caps the number of items evaluated (not returned) per call.
	Limit *int32
	// ScanIndexForward controls sort order; nil defaults to ascending.
	ScanIndexForward *bool
	// LastEvaluatedKey is the pagination token returned by the previous call.
	LastEvaluatedKey map[string]types.AttributeValue
}

QueryInput parametrises a DynamoDB Query operation.