minidyn

README

minidyn

Amazon DynamoDB testing library written in Go.

Goals

• Make local testing for DynamoDB as accurate as possible.
• Run DynamoDB tests in a CI without external dependencies.
• Identify errors caused by DynamoDB restrictions.

Usage

In-memory client (existing)

Create the dynamodb client:

client := minidyn.NewClient()

Define the tables and indexes schemas,you can use the SDKs methods to create tables.

client.CreateTable(&dynamodb.CreateTableInput{
  TableName: aws.String("pokemons"),
  AttributeDefinitions: []*dynamodb.AttributeDefinition{
    {
      AttributeName: aws.String("id"),
      AttributeType: aws.String("S"),
    },
  },
  BillingMode: aws.String("PAY_PER_REQUEST"),
  KeySchema: []*dynamodb.KeySchemaElement{
    {
      AttributeName: aws.String("id"),
      KeyType:       aws.String("HASH"),
    },
  },
})

Or you can use the AddTable and AddIndex method helper.

err := client.AddTable("pokemons", "id", "primary_type")
if err != nil {
  return err
}

err = client.AddIndex("pokemons", "type_index", "primary_type", "")
if err != nil {
  return err
}

NOTE these methods only support string attributes.

HTTP server mode (new)

You can now run minidyn as an HTTP server compatible with the DynamoDB JSON API. This is handy for using httptest.NewServer and real AWS SDK clients without swapping implementations.

import (
  "net/http/httptest"

  miniserver "github.com/truora/minidyn/server"
  "github.com/aws/aws-sdk-go-v2/aws"
  "github.com/aws/aws-sdk-go-v2/config"
  "github.com/aws/aws-sdk-go-v2/service/dynamodb"
)

srv := httptest.NewServer(miniserver.NewServer())
defer srv.Close()

cfg, _ := config.LoadDefaultConfig(ctx,
  config.WithEndpointResolverWithOptions(
    aws.EndpointResolverWithOptionsFunc(func(service, region string, _ ...interface{}) (aws.Endpoint, error) {
      return aws.Endpoint{URL: srv.URL, PartitionID: "aws", SigningRegion: "us-east-1"}, nil
    })),
)
ddb := dynamodb.NewFromConfig(cfg)

// use ddb as usual: CreateTable, PutItem, Query, etc.

Supported operations in HTTP mode include CreateTable, DescribeTable, UpdateTable, DeleteTable, PutItem, GetItem, UpdateItem, DeleteItem, Query, Scan, and BatchWriteItem.

Language interpreter

This library has an interpreter implementation for the DynamoDB Expressions.

Conditional Expressions

Types

Name	Type	Short	Supported?
Number	scalar	N	y
String	scalar	S	y
Binary	scalar	B	y
Bool	scalar	BOOL	y
Null	scalar	NULL	y
List	document	L	y
Map	document	M	y
StringSet	set	SS	y
NumberSet	set	NS	y
BinarySet	set	BS	y

Expressions

	Syntax	Supported?
operand comparator operand	= <> < <= > and >=	y
operand BETWEEN operand AND operand	N,S,B	y
operand IN ( operand (',' operand (, ...) ))		y
function	attribute_exists, attribute_not_exists, attribute_type, begins_with, contains, size	y
condition AND condition		y
condition OR condition		y
NOT condition		y

Update Expressions

Expressions

	Syntax	Supported?
SET	SET action [, action] ...	y
REMOVE	REMOVE action [, action] ...	y
ADD	ADD action [, action] ...	y
DELETE	DELETE action [, action] ...	y
function	list_append, if_not_exists	y

Developer notes

Regenerating HTTP request structs

The HTTP server uses generated JSON input shapes in server/requests.go so we can cleanly unmarshal DynamoDB JSON without the SDK’s AttributeValue interfaces. If you update DynamoDB inputs or need to refresh these shapes, run:

go run ./tools/generate_requests

This will rewrite server/requests.go based on the AWS SDK v2 DynamoDB input types, replacing AttributeValue interfaces with the concrete JSON-friendly AttributeValue defined in server/types.go.

E2E tests (minidyn vs DynamoDB Local)

The e2e package runs the same AWS SDK v2 calls against minidyn (httptest + server.NewServer) and DynamoDB Local in Docker (testcontainers-go), then compares results.

Prerequisites: a working Docker engine (docker info must succeed), since DynamoDB Local is started as amazon/dynamodb-local.

From the repository root:

go test ./e2e/... -v

If Docker is unavailable, those tests skip after docker info fails (so the comparison against DynamoDB Local is not run).

Install and run amazon/dynamodb-local yourself

To run the same official image outside of the Go tests (for manual checks or any AWS SDK client):

docker pull amazon/dynamodb-local:latest
docker run --rm -p 8000:8000 amazon/dynamodb-local:latest

DynamoDB Local listens on port 8000. Point your client at http://localhost:8000 with a real region (for example us-east-1) and any credentials; signing still applies, but the local server does not validate them.

What to do when the interpreter does not work properly?

When it happens you can override the intepretation using like this:

client.ActivateNativeInterpreter()

client.GetNativeInterpreter().AddUpdater(table, "SET secondary_type = :secondary_type", func(item map[string]*dynamodb.AttributeValue, updates map[string]*dynamodb.AttributeValue) {
   item["secondary_type"] = updates[":secondary_type"]
})

Note: Please, report us the issue with the interpreter through https://github.com/truora/minidyn/issues

License

The MIT License