Amazon DynamoDB
Developer Guide (API Version 2012-08-10)
Did this page help you?  Yes | No |  Tell us about it...
« 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.

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.

Note

DynamoDB Local also includes the JavaScript Shell, an interactive browser-based interface for DynamoDB Local. To learn more about the JavaScript Shell, see JavaScript Shell for DynamoDB Local.

Downloading and Running DynamoDB Local

DynamoDB Local is available as an executable .jar file. It will run on Windows, Linux, Mac OS X, and other platforms that support Java. Follow the steps in this procedure to download and run DynamoDB Local.

  1. Download DynamoDB Local for free using one of these links:

    Important

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

  2. After you have downloaded the archive to your computer, extract the contents and copy the extracted directory to a location of your choice.

  3. To start DynamoDB Local, open a command prompt window, navigate to the directory where you extracted DynamoDBLocal.jar, and enter the following command:

    java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb

    The DynamoDB Local command line accepts the following options:

    • -cors value — Enable CORS support (cross-origin resource sharing) for JavaScript. You must provide a comma-separated "allow" list of specific domains. The default setting for -cors is an asterisk (*), which allows public access.

    • -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. Note that you cannot specify both --dbPath and --inMemory at once.

    • -delayTransientStatuses — Causes DynamoDB Local to introduce delays for certain operations. DynamoDB Local can perform some tasks almost instantaneously, such as create/update/delete operations on tables and indexes; however, the actual DynamoDB service requires more time for these tasks. Setting this parameter helps DynamoDB Local simulate the behavior of DynamoDB more closely. (Currently, this parameter introduces delays only for global secondary indexes that are in either CREATING or DELETING status.)

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

    • -inMemory — DynamoDB Local will run in memory, instead of using a database file. When you stop DynamoDB Local, none of the data will be saved. Note that you cannot specify both --dbPath and --inMemory at once.

    • -optimizeDbBeforeStartup — Optimizes the underlying database tables before starting up the DynamoDB Local server. You must also specify -dbPath when you use this parameter.

    • -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.

      Note

      DynamoDB Local uses port 8000 by default. If port 8000 is unavailable, this command will throw an exception. You can use the -port option to specify a different port number. For a complete list of DynamoDB Local runtime options, including -port , type this command:

      java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -help

    • -sharedDb — DynamoDB Local will use a single database file, instead of using separate files for each credential and region. If you specify -sharedDb, all DynamoDB Local clients will interact with the same set of tables regardless of their region and credential configuration.

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

Setting the Endpoint

To run an application with DynamoDB Local, you will need to modify your client object so that it can find the endpoint for DynamoDB Local. 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 setting the endpoint to the default URL for DynamoDB Local (http://localhost:8000).

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' => 'us-west-2', #replace with your desired region
    'endpoint' => 'http://localhost:8000'
));

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

Except for the endpoint, applications that work with DynamoDB Local should also work with the DynamoDB service. However, you should be aware of the following:

  • If you use the -sharedDb option, DynamoDB Local creates a single database file named shared-local-instance.db. Every program that connects to DynamoDB Local will access this file. If you delete the file, you will lose any data you have stored in it.

  • If you omit -sharedDb, the database file will be named myaccesskeyid_region.db, with the AWS access key ID and region as they appear in your application configuration. If you delete the file, you will lose any data you have stored in it.

  • If you use the -inMemory option, DynamoDB Local does not write any database files at all. Instead, all data is written to memory, and the data is not saved when you terminate DynamoDB Local.

  • If you use the -optimizeDbBeforeStartup option, you must also specify the -dbPath parameter so that DynamoDB Local will be able to find its database file.

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.

  • DynamoDB Local does not throttle read or write activity. The speed of read and write operations on table data are limited only by the speed of your computer. CreateTable and DeleteTable operations will occur immediately, and table state is always ACTIVE. UpdateTable operations that only change the provisioned throughput settings on tables and/or global secondary indexes will occur immediately. If an UpdateTable operation creates or deletes any global secondary indexes, then those indexes transition through normal states (such as CREATING and DELETING, respectively) before they become ACTIVE state. The table remains ACTIVE during this time.

  • 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.

  • If you are leveraging DynamoDB Streams, the rate at which shards are created might differ: In DynamoDB, shard creation behavior is partially influenced by table partition activity; however, in DynamoDB Local, there is no table partitioning. In either case, shards are ephemeral, so your application should not be dependent on shard behavior.