node package manager


DynamoDB client for node.js


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

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

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.

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.

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