Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

AWS Logo
Menu

Run and test DynamoDB applications locally using Docker and Testcontainers

Use the DynamoDB Local Testcontainers module for your Go applications!

dynamodbgolangdatabasedockertesting
Abhishek Gupta
Amazon Employee
Published Feb 7, 2024
Comments
1

Did you know you could run DynamoDB locally?

DynamoDB Local is a version of Amazon DynamoDB that you can run locally as a Docker container (or other forms).
It's super easy to get started:
More on the --endpoint-url soon

Hello Testcontainers!

This is a good start. But DynamoDB Local is a great fit for Testcontainers which "is an open source framework for providing throwaway, lightweight instances of databases, message brokers, web browsers, or just about anything that can run in a Docker container."
It supports multiple languages (including Go!) and databases (also messaging infrastructure etc.) - All you need is Docker. Testcontainers for Go makes it simple to programmatically create and clean up container-based dependencies for automated integration/smoke tests. You can define test dependencies as code, run tests and delete the containers once done.
Testcontainers has the concept of modules that are "preconfigured implementations of various dependencies that make writing your tests even easier"
Testcontainers modules
Testcontainers modules
Having a piece of infrastructure supported as a Testcontainer module provides a seamless, plug-and-play experience. The same applies to DynamoDB Local, and that's where Testcontainers module for DynamoDB Local comes in! It allows you to easily run/test your Go based DynamoDB applications locally using Docker.

Getting started with the Testcontainers module for DynamoDB Local

Super easy!
Go ahead and use the sample code in the project README.
To summarize, it consists of three simple steps:
  1. Start the DynamoDB Local Docker container - dynamodblocal.RunContainer(ctx)
  2. Gets the client handle for the DynamoDB (local) instance - dynamodbLocalContainer.GetDynamoDBClient(context.Background())
  3. Uses the client handle to execute operations. In this case - create a table, add an item, query that item.
  4. Terminate it at the end of the program (typically register it using defer) - dynamodbLocalContainer.Terminate(ctx)

Module options

The following configuration parameters are supported:
  • WithTelemetryDisabled - When specified, DynamoDB local will not send any telemetry.
  • WithSharedDB - If you use this option, DynamoDB creates a shared database file in which data is stored. This is useful if you want to persist data for e.g. between successive test executions.
To use WithSharedDB, here is a common workflow:
  1. Start container and get client handle
  2. Create table, add data and query it
  3. Re-start container
  4. Query same data (again) - Should be there
And here is how you might go about it (error handling and logging omitted):
To use these options together:
The Testcontainers documentation is pretty good in terms of detailing how to write an extension/module. But I had to deal with a specific nuance - related to DynamoDB Local.

DynamoDB Endpoint Resolution

Contrary to the DynamoDB service, in order to access DynamoDB Local (with the SDK, AWS CLI etc.), you must specify a local endpoint - http://<your_host>:<service_port>. Most commonly, this is what you would use: http://locahost:8000
The endpoint resolution process has changed since AWS SDK for Go v2 - I had to do some digging to figure it out. You can read up in the SDK documentation, but the short version is that you to specify a custom endpoint resolver. In this case, all it take is to retrieve the docker container host and port.
Here is the implementation - this is used in the module as well.

This was fun!

Like I mentioned, Testcontainers has excellent documentation which was helpful as I had to wrap my head around how to support -sharedDb flag (using WithSharedDB). The solution was easy (ultimately), but the Reusable container section was the one which turned on the lightbulb for me!
I would highly recommend reading up on Differences between downloadable DynamoDB and the DynamoDB web service.
If you find this project interesting/helpful, don't hesitate to ⭐️ it and share it with your colleagues. Happy Building!
 

Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.

Comments
1

1 Comment