dynode

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

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"
  });

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
• Create Table
• List Tables
• Describe Table
• updateTable
• Put Item
• Update Item
• Get Item
• Delete Item
• Query
• Scan
• Batch Get Item

Auth

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

  dynode.auth({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);

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);

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);

Tests

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

  $ make test

Author: Ryan Fitzgerald

License: Apache 2.0