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
.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.
Download DynamoDB Local for free using one of these links:
DynamoDB Local supports the Java Runtime Engine (JRE) version 6.x or newer; it will not run on older JRE versions.
After 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 directory where you
DynamoDBLocal.jar, and enter the following
java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDb
The DynamoDB Local command line accepts the following options:
value — Enable CORS support
comma-separated "allow" list of specific domains. The default setting for
-cors is an asterisk (*), which allows public
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
-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
-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
--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.
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
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,
-port , type this command:
java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar
-sharedDb — DynamoDB Local will use a single database file,
instead of using separate files for each credential and region. If you
-sharedDb, all DynamoDB Local clients will interact with
the same set of tables regardless of their region and credential
DynamoDB Local will process incoming requests until you stop it. To stop DynamoDB Local, type Ctrl+C in the command prompt window.
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 (
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' => '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.
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
-dbPath parameter so that DynamoDB Local will be able to
find its database file.
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.
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.