DynamoDB client for node.js


This library has been deprecated.

Please use Amazon's SDK for node.js instead.


Build Status

This is a node.js binding for the DynamoDB service provided by Amazon Web Services. It aims to abstract DynamoDB's implementation (request signing, session tokens, pagination), but not its tradeoffs/philosophy, by providing two APIs:


var dynamo = require("dynamo")
  , client = dynamo.createClient()
  , db = client.get("us-east-1")

// High-level API

  .query({id: "123", date: {">=": new Date - 6000 }})
  .get("id", "date", "name")
  .fetch(function(err, data){ ... })

// Same call, using low-level API

  TableName: "myTable",
  HashKeyValue: {S: "123"},
  RangeKeyValue: {
    ComparisonOperator: "LE",
    AttributeValueList: [{N: "1329912311806"}]
  AttributesToGet: ["id", "date", "name"],
  ScanIndexForward: false
}, function(err, data){ ... })


This library has no dependencies, and can be installed from npm:

npm install dynamo


dynamo = require("dynamo")

This module exposes the createClient method, which is the preferred way to interact with dynamo.

client = dynamo.createClient([credentials])

Returns a client instance attached to the account specified by the given credentials. The credentials can be specified as an object with accessKeyId and secretAccessKey members such as the following:

client = dynamo.createClient({
  accessKeyId: "...",    // your access key id
  secretAccessKey: "..." // your secret access key

You can also omit these credentials by storing them in the environment under which the current process is running, as AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

If neither of the above are provided, an error will be thrown.

db = client.get(regionName)

Returns a database in the selected region. Currently, DynamoDB supports the following regions:

  • us-east-1
  • us-west-1
  • us-west-2
  • ap-northeast-1
  • ap-southeast-1
  • eu-west-1

Once you have a database instance, you can use either of the provided APIs:

High-level API (blue pill)

The primary purpose of this library is to abstract away the often bizzare API design decisions of DynamoDB, into a composable and intuitive interface based on Database, Table, Item, Batch, Query, and Scan objects.

See the wiki for more information.

Low-level API (red pill)

All of the original DynamoDB operations are provided as methods on database instances. You won't need to use them unless you want to sacrifice a clean interdace for more control, and don't mind learning Amazon's JSON format.

See the wiki for more information.


Testing for dynamo is handled using continuous integration against a real DynamoDB instance, under credentials limited to Travis CI.

If you'd like to run the test stuie with your own credentials, make sure they're set using the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, and then run the tests:

npm test

The test suite creates three tables called DYNAMO_TEST_TABLE_1, DYNAMO_TEST_TABLE_2, and 'DYNAMO_TEST_TABLE_3` before the tests are run, and then deletes them once the tests are done. Note that you will need to delete them manually in the event that the tests fail.

To do

  • Factor out tests into integration tests and unit tests
  • Make all callbacks optional, returning an event emitter no callback given
  • Add method to specify Limit and ExclusiveStartKey



Copyright (c) 2012 Jed Schmidt. See LICENSE.txt for details.

Send any questions or comments here.