DynamoDB Local Test Tool Integration for Eclipse

We’re excited to announce that the AWS Toolkit for Eclipse now includes integration with the Amazon DynamoDB Local Test Tool. The DynamoDB Local Test Tool allows you to develop and test your application against a DynamoDB-compatible database running locally — no Internet connectivity or credit card required. When your application is ready for prime time, all you need to do is update the endpoint given to your AmazonDynamoDBClient. Neato!

With the DynamoDB Local Test Tool integrated into the AWS Toolkit for Eclipse, using it is easier than ever. Make sure you have a recent version of the Amazon DynamoDB Management plugin (v201311261154 or later) installed and follow along below!

Installing DynamoDB Local

First, head to the Eclipse preferences and make sure you have a JavaSE-1.7 compatible JRE installed. If not, you’ll need to install one and configure Eclipse to know where it is.

Then, head to the new DynamoDB Local Test Tool preference page, where you can specify a directory to install the DynamoDB Local Test Tool and a default TCP port for it to bind to.

The page also lists versions of the DynamoDB Local Test Tool available for installation. There are currently two: the original version (2013-09-12) and a newer version (2013-12-12) which includes support for Global Seconday Indexes. When the DynamoDB team releases future versions of the test tool, they will also show up in this list. Select the latest version and hit the Install button that’s above the list of versions; the DynamoDB Local Test Tool will be downloaded and installed in the directory you specified.

Starting DynamoDB Local

Once the test tool is installed, pop open the AWS Explorer view and switch it to the Local (localhost) region. This psuedo-region represents test tool services running locally on your machine.

For now, you’ll see a single Amazon DynamoDB node representing the DynamoDB Local Test Tool. Right-click this node and select Start DynamoDB Local.

This will bring up a wizard allowing you to pick which version of the DynamoDB Local Test Tool to launch, and the port to which it should bind. Pick the version you just installed, give it a port (if you didn’t specify a default earlier), and hit Finish. A console window will be opened that should print out a few lines similar to the below when the DynamoDB Local Test Tool finishes initializing itself:

Using DynamoDB Local

You can now use the DynamoDB Management features of the toolkit to create tables in your local DynamoDB instance, load some data into them, and perform test queries against your tables.

To write code against DynamoDB Local, simply set your client’s endpoint and region appropriately:

// The secret key doesn't need to be valid, DynamoDB Local doesn't care.
AWSCredentials credentials = new BasicAWSCredentials(yourAccessKeyId, "bogus");
AmazonDynamoDBClient client = new AmazonDynamoDBClient(credentials);

// Make sure you use the same port as you configured DynamoDB Local to bind to.
client.setEndpoint("http://localhost:8000");

// Sign requests for the "local" region to read data written by the toolkit.
client.setSignerRegionOverride("local");

And away you go! As mentioned above, DynamoDB Local doesn’t care if your credentials are valid, but it DOES create separate local databases for each unique access key ID sent to it, and for each region you say you’re authenticating to. If you have configured the Toolkit with a real set of AWS credentials, you’ll want to use the same access key ID when programmatically interacting with DynamoDBLocal so you read from and write to the same local database. Since the Toolkit uses the "local" region to authenticate to DynamoDBLocal, you’ll also want to override your client to authenticate to the "local" region as well.

Conclusion

DynamoDB Local is a great way to play around with the DynamoDB API locally while you’re first learning how to use it, and it’s also a great way to integration-test your code even if you’re working without a reliable Internet connection. Now that the AWS Toolkit for Eclipse makes it easy to install and use, you should definitely check it out!

Already using DynamoDB Local or the new Eclipse integration? Let us know how you like it and how we can make it even better in the comments!