Running DynamoDB on Your Computer
DynamoDB is available as a free, downloadable client-side application that you can run on your own computer. This edition of DynamoDB lets you write applications that use the DynamoDB API, but without actually using the Amazon DynamoDB web service. Instead, the database is self-contained on your computer. When your application creates a table or modifies data, those changes are written to the DynamoDB database on your system. This lets you save on provisioned throughput, data storage, and data transfer fees. In addition, you do not need to have an Internet connection in order to develop applications.
The downloadable version of DynamoDB is ideal for development and testing purposes. When you are ready to deploy your application in production, you simply redirect it to the Amazon DynamoDB web service, without having to modify your application code.
Downloading and Running DynamoDB
The downloadable version of DynamoDB is implemented 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 on your computer:
Download DynamoDB for free using one of these links:
The downloadable version of DynamoDB may be available in repositories such as Homebrew, yum and APT, but it is not guaranteed to be the latest version. To make sure you have the latest version, use one of the links shown above.
DynamoDB on your computer requires 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 on your computer, 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 command line accepts the following options:
-corsis an asterisk (*), which allows public access.
value— The directory where DynamoDB 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
-delayTransientStatuses— Causes DynamoDB to introduce delays for certain operations. DynamoDB 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 simulate the behavior of the Amazon DynamoDB web service 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.
-inMemory— DynamoDB; will run in memory, instead of using a database file. When you stop DynamoDB;, none of the data will be saved. Note that you cannot specify both
-optimizeDbBeforeStartup— Optimizes the underlying database tables before starting up DynamoDB on your computer. You must also specify
-dbPathwhen you use this parameter.
value— The port number that DynamoDB will use to communicate with your application. If you do not specify this option, the default port is
DynamoDB uses port 8000 by default. If port 8000 is unavailable, this command will throw an exception. You can use the
-portoption to specify a different port number. For a complete list of DynamoDB runtime options, including
-port, type this command:
java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -help
-sharedDb— DynamoDB will use a single database file, instead of using separate files for each credential and region. If you specify
-sharedDb, all DynamoDB clients will interact with the same set of tables regardless of their region and credential configuration.
You will see occasional diagnostic messages in the window where DynamoDB is running. DynamoDB will process incoming requests until you stop it. To stop DynamoDB, type Ctrl+C in the command prompt window.
Setting the Endpoint
To run an application against DynamoDB on your computer, you will need to modify your client object
so that it can find the endpoint for DynamoDB. 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
client = new AmazonDynamoDBClient(credentials); client.setEndpoint("http://localhost:8000");
var config = new AmazonDynamoDBConfig(); config.ServiceURL = "http://localhost:8000"; client = new AmazonDynamoDBClient(config);
$sdk = new Aws\Sdk([ 'region' => 'us-west-2', 'version' => 'latest', 'endpoint' => 'http://localhost:8000' ]); $dynamodb = $sdk->createDynamoDb();
Except for the endpoint, applications that run with DynamoDB on your system should also work with the Amazon DynamoDB web service. However, you should be aware of the following:
If you use the
-sharedDboption, DynamoDB creates a single database file named shared-local-instance.db. Every program that connects to DynamoDB 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
-inMemoryoption, DynamoDB 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.
If you use the
-optimizeDbBeforeStartupoption, you must also specify the
-dbPathparameter so that DynamoDB will be able to find its database file.
The AWS SDKs for DynamoDB require that your application configuration specify an access key value and an AWS region value. Unless you are using the
-inMemoryoption, DynamoDB uses these values to name the local database file.
Although these do not have to be valid AWS values in order to run locally, you may find it useful to use valid values so that you can later run your code in the cloud simply by changing the endpoint you are using.
Differences Between DynamoDB Running Locally and the Amazon DynamoDB Web Service
The downloadable version of DynamoDB attempts to emulate the Amazon DynamoDB web service as closely as possible. However, it does differ from the Amazon DynamoDB service in the following ways:
Regions and distinct AWS accounts are not supported at the client level.
Provisioned throughput settings are ignored, 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
UpdateTableas many times as you like per day; however, any changes to provisioned throughput values are ignored.
The speed of read and write operations on table data are limited only by the speed of your computer.
DeleteTableoperations occur immediately, and table state is always ACTIVE.
UpdateTableoperations that only change the provisioned throughput settings on tables and/or global secondary indexes will occur immediately. If an
UpdateTableoperation 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 are eventually consistent. However, due to the speed of DynamoDB running on your computer, most reads will actually appear to be strongly consistent.
Consumed capacity units are not tracked. In API responses, nulls are returned instead of capacity units.
Item collection metrics are not tracked; nor are 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 web service enforces this limit, and so does the downloadable version of DynamoDB. However, when querying an index, the DynamoDB service only calculates the size of the projected key and attributes. By contrast, the downloadable version of DynamoDB calculates the size of the entire item.
If you are leveraging DynamoDB Streams, the rate at which shards are created might differ: In the DynamoDB web service, shard creation behavior is partially influenced by table partition activity; however, when you run DynamoDB locally, there is no table partitioning. In either case, shards are ephemeral, so your application should not be dependent on shard behavior.