dynode

node.js client for working with Amazon's DynamoDB service.

Urgent

A bug was discovered generating aws request starting on or over the 10th month of the year. This causes all requests to fail starting on October 1st, more information can be found here. Version 0.6.1 has been released fixing this issue. Anyone currently running 0.6.0 should upgrade immediately.

Installation

Installing npm (node package manager)

  $ curl http://npmjs.org/install.sh | sh

Installing dynode

  $ [sudo] npm install dynode

Motivation

Dynode is designed to be a simple and easy way to work with Amazon's DynamoDB service. Amazon's http api is complicated and non obvious how to interact with it. This client aims to offer a simplified more obvious way of working with DynamoDB, but without getting in your way or limiting what you can do with DynamoDB.

Usage

There are two different ways to use dynode: directly via the default dynamoDB client, or by instantiating your own client. The former is merely intended to be a convenient shared client to use throughout your application if you so choose.

Using the Default DynamoDB Client

The default client is accessible through the dynode module directly. Any method that you could call on an instance of a client is available on the default client:

  var dynode = require('dynode');
  // When using the default client you must first give it auth credentials
  dynode.auth({accessKeyId: "AWSAccessKey", secretAccessKey: "SecretAccessKey"});

  dynode.createTable("NewTable", console.log);
  dynode.listTables(console.log);

Instantiating your own DynamoDB Client

If you would prefer to manage your own client, potentially with different auth params:

  var client = new (dynode.Client)({
    accessKeyId: "AWSAccessKey", secretAccessKey: "SecretAccessKey"
  });

Region support

dynode supports all available DynamoDB regions. By default dynode will connect to the us-east-1 region. To connect to a different region pass in the region option when creating a client, for example:

  // connect to the US West (Northern California) Region
  var client = new (dynode.Client)({
    region: "us-west-1"
    accessKeyId: "AWSAccessKey", 
    secretAccessKey: "SecretAccessKey"
  });

The default client can also connect to any region

  // connect to the Asia Pacific (Tokyo) Region
  dynode.auth({
    region: "ap-northeast-1"
    accessKeyId: "AWSAccessKey", 
    secretAccessKey: "SecretAccessKey"
  });

Callback Signature

Callbacks return (error, [results], meta) where results are the returned data and meta is the extra information returned by DynamoDB

API Documentation

• Auth
• Table Name Prefix
• HTTPS
• Create Table
• List Tables
• Describe Table
• updateTable
• deleteTable
• Put Item
• Update Item
• Get Item
• Delete Item
• Query
• Scan
• Batch Get Item
• Batch Write Item
• Truncate

Auth

Before you can perform any operations on DynamoDB you need to provide your Amazon credentials.

  dynode.auth({accessKeyId: "AWSAccessKey", secretAccessKey: "SecretAccessKey"});

Table Name Prefix

dynode client takes an optional tableNamePrefix in order to support running in different environments such as dev, testing, production

  var client = new (dynode.Client)({
    accessKeyId: "AWSAccessKey", secretAccessKey: "SecretAccessKey", tableNamePrefix: "Dev_"
  });

Now all operations will be performed against tables starting with that prefix, for example

  client.createTable("NewTable", console.log); // will create table named 'Dev_NewTable'

HTTPS

To use HTTPS for connecting to DynamoDB pass in the https option, by default dynode will use HTTP

  dynode.auth({https: true, accessKeyId: "AWSAccessKey", secretAccessKey: "SecretAccessKey"});

Create Table

The CreateTable operation adds a new table to your account. For more info see here

By default createTable will create the given table with a primary key of id : String, a read capacity of 10 and write capacity of 5.

  dynode.createTable("ExampleTable", console.log);

createTable accepts an options hash to override any of the table creation defaults.

  var opts = {read: 20, write: 25, hash: {name: String}, range: {age: Number}};
  dynode.createTable("ExampleTable", opts, console.log);

List Tables

Returns an array of all the tables associated with the current account. For more info see here

By default listTables will list all of your DynamoDB tables.

  dynode.listTables(console.log);

You can also pass in options to filter which tables to list. See Amazon's docs for more info

  dynode.listTables({Limit: 3, ExclusiveStartTableName: "ExampleTable"}, console.log);

Describe Table

Returns information about the table, including the current status of the table, the primary key schema and when the table was created. For more info see here

  dynode.describeTable("ExampleTable", function (error, info));

Update Table

Updates the provisioned throughput for the given table. For more info see here

  dynode.updateTable("ExampleTable", {read: 15, write: 10}, console.log);

Delete Table

Deletes a table and all of its items. For more info see here

  dynode.deleteTable("ExampleTable", console.log);

Put Item

Creates a new item, or replaces an old item with a new item (including all the attributes). For more info see here

  dynode.putItem("ExampleTable", {name : "Foo", age: 80, baz : ["a", "b", "c"], nums: [1,2,3]}, console.log);

You can also pass in any option that Amazon accepts.

  var item = {name : "Bob"};
  var options = {ReturnValues:"ReturnValuesConstant", Expected :{"age":{"Value": {"N":"42"},{"Exists":Boolean}}}};

  dynode.putItem("ExampleTable", item, options, console.log);

Update Item

Edits an existing item's attributes. For more info see here

By default all operations will be a PUT, which will add or replace the attribute with the new value.

  dynode.updateItem("ExampleTable", "ItemHashKey", {name: "Ryan"}, console.log);

updateItem also accepts a key object to specify which item to update.

  dynode.updateItem("ExampleTable", {hash: "Key", range: 22}, {name: "Ryan"}, console.log);

Perform specific action to perform for the given update

  var updates = {nums: {'delete' : [5]}, age: {add: 2}};

  dynode.updateItem("ExampleTable", "ItemsHashKey", updates, console.log);

Delete the attribute from an existing item

  var updates = {age: {'Action' : 'DELETE'}};

  dynode.updateItem("ExampleTable", "ItemsHashKey", updates, console.log);

DynamoDB doesn't allow empty strings or empty sets updateItem will delete attributes when passing in null, empty string, or empty array

  var updates = {age: null, nums: [], fullname: ''};

  dynode.updateItem("ExampleTable", "ItemsHashKey", updates, console.log);

updateItem accepts options which lets you pass in any option that Amazon accepts.

  var opts = {ReturnValues : "ReturnValuesConstant", Expected :{"status":{"Value":{"S":"offline"}}}};

  dynode.updateItem("ExampleTable", "TheKey", {name: "Ryan"}, opts, console.log);

Get Item

The getItem operation returns a set of Attributes for an item that matches the primary key. For more info see here

  dynode.getItem("ExampleTable", "TheHashKey", console.log);

getItem also accepts a key object to specify which item to get.

  dynode.getItem("ExampleTable", {hash: "TheHashKey", range: 123}, console.log);

getItem accepts any option that Amazon accepts.

  var opts = {AttributesToGet: ["status","friends"], ConsistentRead : true};

  dynode.getItem("ExampleTable", "TheHashKey", opts, console.log);

Delete Item

Deletes a single item in a table by primary key. For more info see here

  dynode.deleteItem("ExampleTable", "TheHashKey", console.log);

deleteItem also accepts a key object to specify which item to delete.

  dynode.deleteItem("ExampleTable", {hash: "TheHashKey", range: 123}, console.log);

deleteItem accepts any option that Amazon accepts.

  var opts = {ReturnValues : "ALL_OLD"};

  dynode.deleteItem("ExampleTable", "TheHashKey", opts, console.log);

Query

A Query operation gets the values of one or more items and their attributes by primary key. For more info see here

  dynode.query("ExampleTable", "TheHashKey", console.log);

query accepts any option that Amazon accepts.

  var opts = {RangeKeyCondition: {AttributeValueList :[{"N":"AttributeValue2"}],"ComparisonOperator":"GT"}};

  dynode.query("ExampleTable", "TheHashKey", opts, console.log);

Scan

The Scan operation returns one or more items and its attributes by performing a full scan of a table. For more info see here

  dynode.scan("ExampleTable", console.log);

scan accepts any option that Amazon accepts.

  var opts = {
    Limit: 5,
    ScanFilter : {"AttributeName1":{"AttributeValueList":[{"S":"AttributeValue"}],"ComparisonOperator":"EQ"}},
    AttributesToGet : ["AttributeName1", "AttributeName2", "AttributeName3"]
  };

  dynode.scan("ExampleTable", opts, console.log);

Batch Get Item

The BatchGetItem operation returns the attributes for multiple items from multiple tables using their primary keys. For more info see here

  var query = {
    "ExampleTable": {keys:[{hash: "someKey"}, {hash: "someKey2"}]},
    "AnotherTable": {keys:[{hash: "anotherKey", range: 123}]}
  }

  dynode.batchGetItem(query, console.log);

batchGetItem accepts any option that Amazon accepts.

  var filter = {
    "ExampleTable": {keys:[{hash: "someKey"}], AttributesToGet :["name", "age"]},
    "AnotherTable": {keys:[{hash: "anotherKey", range: 123}], AttributesToGet :["brand", "price"]}
  }

  dynode.batchGetItem(filter, console.log);

Batch Write Item

The BatchWriteItem operation This operation enables you to put or delete several items across multiple tables in a single API call. For more info see here

  var writes = {
    "BatchTable": [
      {put : {id : "foo", name: "bar"}},
      {del : "hash-key"}
    ],
    "AnotherTable": [
      {del : {hash: "somekey", range: "foo"}},
      {del : {hash: "another key", range: "moar foo"}}
    ]
  };

  dynode.batchWriteItem(writes, console.log);

Truncate

The Truncate operation will scan all items currently in the given table and remove them one by one. This has the potential to use up your write capacity, so use this call with care. note - This api is not provided directly by DynamoDB.

  var options = {
    throughputPercent : 0.5 // attempt to only consume 50% of write capacity, defaults to 100%
  };

  dynode.truncate("ExampleTable", options, console.log);

Tests

All tests are written with mocha and should be run with make:

  $ make test

Author: Ryan Fitzgerald

License: Apache 2.0