node.js client for working with Amazon's DynamoDB service.
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.
$ curl http://npmjs.org/install.sh | sh $ [sudo] npm install dynodeDynode 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.
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.
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);If you would prefer to manage your own client, potentially with different auth params:
var client = new (dynode.Client)({
accessKeyId: "AWSAccessKey", secretAccessKey: "SecretAccessKey"
});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"
});Callbacks return (error, [results], meta) where results are the returned data and meta is the extra information returned by DynamoDB
- 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
Before you can perform any operations on DynamoDB you need to provide your Amazon credentials.
dynode.auth({accessKeyId: "AWSAccessKey", secretAccessKey: "SecretAccessKey"});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'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"});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);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);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));Updates the provisioned throughput for the given table. For more info see here
dynode.updateTable("ExampleTable", {read: 15, write: 10}, console.log);Deletes a table and all of its items. For more info see here
dynode.deleteTable("ExampleTable", console.log);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);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);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);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);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);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);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);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);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);All tests are written with mocha and should be run with make:
$ make test