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.


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 Java archive (.jar file), and will run on Windows, Mac, or Linux computers.


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:

  • -cors value — Enable CORS support (cross-origin resource sharing) for JavaScript. You must provide a comma-separated "allow" list of specific domains. You can also use an asterisk (*) to allow 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.

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


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.


client = new AmazonDynamoDBClient(credentials);


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


$client = DynamoDbClient::factory(array(
    'profile' => 'default',
    'region' => 'us-west-2', #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.

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

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


    Each database file represents a separate set of data, so if you change the access key or region it creates a new database without the data stored in previous data files.

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

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