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 is available as an executable Java archive (
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
The DynamoDB Local command line accepts the following options:
-help — Prints a usage summary and options for
DynamoDB Local .
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
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
-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
--inMemory at once.
-optimizeDbBeforeStartup — Optimizes the underlying
database tables before starting up the DynamoDB Local server. You must also
-dbPath when you use this parameter.
-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
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.
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); client.setEndpoint("http://localhost:8000");
var config = new AmazonDynamoDBConfig(); config.ServiceURL = "http://localhost:8000"; client = new AmazonDynamoDBClient(config);
$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.
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
If you use the
-optimizeDbBeforeStartup option, you must also
-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.
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
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.
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
DeleteTable operations will occur immediately, and
table state is always ACTIVE.
that only change the provisioned throughput settings on tables and/or
global secondary indexes will occur immediately. If an
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.