Amazon DynamoDB
Developer Guide (API Version 2012-08-10)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

DynamoDB Local

DynamoDB Local is a small client-side database and server that mimics the DynamoDB service. DynamoDB Local enables you to write applications that use the DynamoDB API, without actually manipulating any tables or data in DynamoDB. Instead, all of the API actions are rerouted to DynamoDB Local. When your application creates a table or modifies data, those changes are written to a local database. This lets you save on provisioned throughput, data storage, and data transfer fees.

DynamoDB Local is compatible with the DynamoDB API. When you are ready to deploy your application, you simply redirect it to DynamoDB, without having to modify your application code.

In addition, you do not need to have an Internet connection to use DynamoDB Local. You can develop applications without having to be connected to the network.

Downloading and Running DynamoDB Local

DynamoDB Local is available as an executable Java archive (.jar file), and will run on Windows, Mac, or Linux computers.

Important

DynamoDB Local supports the Java Runtime Engine (JRE) version 6.x or newer; it will not run on older JRE versions.

You can download DynamoDB Local for free using one of these links:

Once you have downloaded the archive to your computer, extract the contents and copy the extracted directory to a location of your choice. To start DynamoDB Local, open a command prompt window, navigate to the downloaded directory where you will find DynamoDBLocal.jar, and enter the following command:

java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar [options]

The DynamoDB Local command line accepts the following options:

  • -help — Prints a usage summary and options for DynamoDB Local .

  • -port value — The port number that DynamoDB Local will use to communicate with your application. If you do not specify this option, the default port is 8000.

  • -dbPath value — The directory where DynamoDB Local will write its database file. If you do not specify this option, the file will be written to the current directory.

  • -inMemory — Instead of using a database file, DynamoDB Local will run in memory. When you stop DynamoDB Local, none of the data will be saved.

Note that you cannot specify both --dbPath and --inMemory at once.

DynamoDB Local will process incoming requests until you stop it. To stop DynamoDB Local, type Ctrl+C in the command prompt window.

Note

If you are using a version of DynamoDB Local that was released prior to December 12, 2013, use this command line instead:

java -Djava.library.path=. -jar DynamoDBLocal.jar

We recommend that you use the download link (see above) to obtain the latest version of DynamoDB Local.

Using DynamoDB Local

To use DynamoDB Local with an application program, you need to configure your client so that it can communicate with the DynamoDB Local endpoint. The way that you do this depends on what programming language and AWS software development kit (SDK) you are using. The following code snippets show examples of how you can do this.

Java

client = new AmazonDynamoDBClient(credentials);
client.setEndpoint("http://localhost:8000"); 

.NET

var config = new AmazonDynamoDBConfig();
config.ServiceURL = "http://localhost:8000";
client = new AmazonDynamoDBClient(config); 

PHP

$client = DynamoDbClient::factory(array(
    'profile' => 'default',
    'region' => Region::US_EAST_1, #replace with your desired region
    'base_url' => 'http://localhost:8000'
));

To verify your setup, modify your client object so that it uses the DynamoDB Local endpoint. When you run your program, you should see diagnostic messages in the window where DynamoDB Local is running, indicating that DynamoDB Local is processing requests from your code.

Usage Notes

In general, application code that uses DynamoDB should run unmodified when used with DynamoDB Local. However, you should be aware of some usage notes:

  • Unless you use the --inMemory option, DynamoDB Local writes a database file to disk. By default, this file is written to the same directory from where you launched DynamoDB Local. (You can specify a different directory using the --dbPath parameter.) The database file is named myaccesskeyid_region.db, with the AWS access key ID and region as they appear in your application configuration. If you delete this database file, you will lose any data you have stored in DynamoDB Local.

  • DynamoDB Local only uses the values for AWS access key ID and region to name the database file, so you can set them to any value you like.

  • DynamoDB Local ignores your AWS secret access key, even though you must still specify this parameter. We recommend that you set it to a dummy string of characters, so that no one will be able to see your secret access key.

Differences Between DynamoDB Local and DynamoDB

DynamoDB Local attempts to emulate the actual DynamoDB service as closely as possible; however, there are several differences:

  • Regions and distinct AWS accounts are not supported at the client level.

  • DynamoDB Local ignores provisioned throughput settings, even though the API requires them. For CreateTable, you can specify any numbers you want for provisioned read and write throughput, even though these numbers will not be used. You can call UpdateTable as many times as you like per day; however, any changes to provisioned throughput values are ignored.

  • DynamoDB Local does not throttle read or write activity. CreateTable, UpdateTable and DeleteTable operations occur immediately, and table state is always ACTIVE. The speed of read and write operations on table data are limited only by the speed of your computer.

  • Read operations in DynamoDB Local are eventually consistent. However, due to the speed of DynamoDB Local, most reads will actually appear to be strongly consistent.

  • DynamoDB Local does not keep track of consumed capacity. In API responses, nulls are returned instead of capacity units.

  • DynamoDB Local does not keep track of item collection metrics; nor does it support item collection sizes. In API responses, nulls are returned instead of item collection metrics.

  • In the DynamoDB API, there is a 1 MB limit on data returned per result set. The DynamoDB service enforces this limit, and so does DynamoDB Local. However, when querying an index, DynamoDB only calculates the size of the projected key and attributes. By contrast, DynamoDB Local calculates the size of the entire item.