Skip to content


Subversion checkout URL

You can clone with
Download ZIP
An Amazon AWS SimpleDB library for Node.js that is user-friendly and fault-tolerant
JavaScript Shell
Tree: 7af6821181

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.



The latest version of aws-lib is required. will get the new version of aws-lib in a few days. In the meantime:

npm install simpledb

git clone git://
npm install aws-lib/


A user-friendly fault-tolerant library for Amazon AWS SimpleDB access. The core SimpleDB actions are mapped to functions:

var simpledb = require('simpledb')
var sdb      = new simpledb.SimpleDB({keyid:'YOUR_AWS_KEY_ID',secret:'YOUR_AWS_SECRET_KEY'})

sdb.createDomain( 'yourdomain', function( error ) {

  sdb.putItem('yourdomain', 'item1', {attr1:'one', attr2:'two'}, function( error ) {

    sdb.getItem('yourdomain', 'item1', function( error, result ) {
      console.log( 'attr1 = '+result.attr1 )
      console.log( 'attr2 = '+result.attr2 )

Any given SimpleDB request has a non-trivial chance of failing. This library implements the exponential back-off retry algorithm as recommended in the SimpleDB developer guide.

This library depends on the excellent aws-lib module:

Key Features:

  • simple API
  • fully configurable
  • detailed logging
  • all request attributes can be overridden
  • fully tested

Core Functions:

  • createDomain ("CreateDomain")
  • domainMetadata ("DomainMetadata")
  • listDomains ("ListDomains")
  • deleteDomain ("DeleteDomain")
  • putItem ("PutAttributes")
  • batchPutItem ("BatchPutAttributes")
  • getItem ("GetAttributes")
  • deleteItem ("DeleteAttributes")
  • select ("Select")
  • request (any action)

This is version 0.0.1 so there's probably still some wierdness - use at your risk. Secure connections are not supported on node 0.3.x.


npm install simpledb

And in your code:

var simpledb = require('simpledb')

Or clone the git repository: git clone git://


This module uses the node.js-style callback convention. All functions take a callback function as their last argument. This callback function should accept three arguments:

callback( error, result, meta )

Where error is an object ({Code:'...',Message:'...'}) describing any errors that occured. If the function was successful then error is null.

So, you check if error is null to see if you can continue working:

sdb.listDomains( functions( error, result, meta ) {
  if( error ) {
    console.log('listDomains failed: '+error.Message )
  else {
    // do stuff with result, an array of domain names

The result parameter contains the results of a successful action and what the result parameter is depends on the action. It could be a string, an array or an object.

The meta parameter contains a description of the request, including the underlying details from Amazon. Take a look with:

console.log( JSON.stringify(meta) )


Where possible, the SimpleDB naming style is preserved: CamelCaseBaby. Names of functions and their parameters also mostly match SimpleDB.

The simpledb.SimpleDB wrapper options (maxtry, secure, etc) are not directly related to Amazon, and so have their own names.

It is sometimes necessary to embed meta-directives into the Amazon query or result objects. These non-Amazon attributes always begin with the $ character, but are in CamelCase. For example: $AsArrays.

This wrapper is based on the REST API. I looked at the SOAP API but... yeah. No X.509 for you. Yet.


For the API examples, assume the following lines of code at the top of your source code file:

var simpledb = require('simpledb')

var sdb = new simpledb.SimpleDB(

This gives you the standard wrapper, with a basic debugger that prints to STDOUT.

You should really also read the Amazon SimpleDB documentation so that you understand how SimpleDB works:

As a get-out-of-jail, you can provide request attribute overrides. You supply these in an optional override argument just before the callback argument. You can use an override on any of the SimpleDB action wrapper functions.

sdb.getItem('domain','itemname', {ConsistentRead:'false'} ,function(err,res,meta){ ... })

In the above code, {ConsistentRead:"false"} is the optional override argument.


var sdb = new simpledb.SimpleDB( options, logger )

Create a new SimpleDB wrapper. The options argument sets general options for the requests. The logger argument receives logging events so that you can debug and/or record SimpleDB interactions.

options: required

  • keyid: (required), your Amazon AWS Key ID
  • secret: (required), your Amazon Secret Key

For further options, see the section on options below

logger: optional

See the section on logging below


Create a domain. A domain is like a SQL table, sort of.

  if( !err ) {

Where <domain> is the name of your domain.


Get some statistics about your domain, such as a count of items and how much storage it is using (you pay Amazon for this!).

   console.log('Mmm, floor pie! '+JSON.stringify(res) )

Where <domain> is the name of your domain.


Returns a list of your domain names as an array of strings. Restricted to the specified SimpleDB host ( See the simpledb.SimpleDB options to change this.

   console.log('You hear that? That's market bacon hitting the pan: '+JSON.stringify(res) )


Delete a domain. Cannot be undone!

  if( !err ) {
    console.log('God made the world, but we made the field.')

Where <domain> is the name of your domain.


Store an item in SimpleDB.

    console.log("Memories, you're talking about memories: "+JSON.stringify(res)) 

Where <itemname> is the unique name of your item, and <attr>:"<value>" are the attribute-value pairs for your item. The value must be either a string or an array of strings.

If you want to use conditional puts, you'll need to add some override values:

    console.log("Nobody expects the spanish inquistion! "+JSON.stringify(res)) 

sdb.batchPutItem( domain, items, override, callback )

Store multiple items in the same request. This is more efficient. The items argument is an array of item objects. Each item object must have a $ItemName meta-attribute that specifies the name of the item.

    { $ItemName:'<itemname1>', <attr>:'<value>', ...}, 
    { $ItemName:'<itemname2>', <attr>:'<value>', ...}
    console.log("And what was your ownership share diluted down to?"+JSON.stringify(res)) 

sdb.getItem( domain, itemname, override, callback )

Get an item from SimpleDB using the item's unique name. The values of the item's attributes are returned as strings. You can provide an $AsArrays meta-directive in the override argument. When true, all attribute values are returned as arrays. As SimpleDb is schemaless, it is not possible to know in advance if an attribute is multi-valued. In the default case, {$AsArrays:false}, multiple values are returned as string, with the value list comma-separated.

sdb.getItem('<domain>','<itemname>',function( error , result, meta ){
  console.log("Those are good burgers, Walter: "+JSON.stringify(res)) 

sdb.getItem('<domain>','<itemname>',{$AsArrays:true},function( error, result, meta ){
  console.log("I've been watching television so much the shows are starting to run together: "+JSON.stringify(res)) 

By default, simpledb uses consistent reads. For improved performance, if this is suitable for your application, you can set the consistent option to false when creating simpledb.SimpleDB. Or you can set it on a case-by-case basis, using an override: {ConsistentRead:"false"}

deleteItem( domain, itemname, attrs, override, callback )

Delete an item from SimpleDB. The attrs argument is an optional array of attribute names. If not present, the item is completely removed. If present, only the specified attributes are removed. If all the attributes of an item are removed, then it will also be completely deleted.

sdb.deleteItem('<domain>','<itemname>',function( error, result, meta ){
  console.log("Well, Ted, like I said the last time: it won't happen again: "+JSON.stringify(res)) 

sdb.deleteItem('<domain>','<itemname>',[ '<attr>', ... ]function( error, result, meta ){
  console.log("I felt like destroying something beautiful. "+JSON.stringify(res)) 

select( query, override, callback )

Perform a SELECT-style query on a SimpleDB domain. The syntax is almost-but-not-quite SQL. You should read the Amazon documentation:

The results are returned as an array of items. Each item contains an $ItemName meta-attribute providing you with the name of the item.

If you need to handle NextToken you'll need to do this manually with the override argument. You can get the NextToken from the meta parameter to your callback."select * from <domain> where <attribute> = '<value>'",function( error, result, meta ){
  console.log("I'll get you, my pretty, and your little dog too! "+JSON.stringify(res)) 


Make a direct request to SimpleDB. You're on your own! Again, read Unlike the other functions above, the request function is not a SimpleDB action wrapper. Use it when the wrapper functions have painted themselves into a corner.

  function( error, result, meta ){
    console.log("Gotta keep 'em separated: "+JSON.stringify(res)) 

Where <action> is the SimpleDB action, such as GetItem, and <attribute>:"<value>" are the SimpleDB REST request attribute pairs.


The aws-lib client object. Use this to send raw requests. Go hardcore.


Replace this with your own implementation to change the handling of SimpleDB responses. Most useful is to modify the response in some way and then call the original function. Also good for testing.

This example counts the number of requests made:

var resultcount = 0    

var orighandle = sdb.handle
sdb.handle = function(start,action,query,tryIndex,response,stop,callback){
  res.$ResultCount = resultcount++

The parameters are:

  • start: Date object, start time of request
  • action: string, name of SimpleDB action
  • query: full SimpleDB query
  • tryIndex: number of tries attempted, up to maxtry
  • response: result from SimpleDB
  • stop: stop(true|false), function to stop retries in case of errors
  • callback: action-specific callback, as provided by functions like getItem, putItem, etc.


The additional options that can be given to simpledb.SimpleDB are:

  • secure: (optional, default=false), if true, use HTTPS
  • consistent: (optional, default=true), if true, ask for consistent reads
  • test: (optional, default=false), if true, don't actually send anything to SimpleDB
  • host: (optional,, SimpleDB host
  • path: (optional, default=/), SimpleDB path
  • version: optional), default=2009-04-15, SimpleDB API version
  • maxtry: (optional, default=4), maximum number of retries when SimpleDB fails
  • delaymin: (optional, default=0), minimum delay in milliseconds
  • delayscale: (optional, default=100), delay multiplier, in milliseconds
  • randomdelay: (optional, default=true), apply a random delay multiplier between 0 and 1
  • expbase: (optional, default=4), exponent base, for the formula that calculates delay time when SimpleDB fails


You can provide a logger callback when you are creating the simpledb.SimpleDB object to get notifications of request processing events. A simple logger that prints to STDOUT is provided by simpledb.debuglogger:

var sdb = new simpledb.SimpleDB( {...}, simpledb.debuglogger )

The logger callback accepts the following arguments: logger( type, date, ... )

  • type: string, one of create, request, handle, error, status
  • date: a Date object
  • ...: remaining arguments depend on type

For type=create, fired when the simpledb.SimpleDB object is created, the arguments are:

  • opts: options object
  • awsopts: aws-lib options

For type=request, fired just before a request is made to SimpleDB, the arguments are:

  • start: Date object, start time of request
  • action: string, name of SimpleDB action
  • query: full SimpleDB query

For type=handle, fired after each response from SimpleDB, the arguments are:

  • start: Date object, start time of request
  • action: string, name of SimpleDB action
  • query: full SimpleDB query
  • tryIndex: number of tries attempted, up to maxtry
  • response: result from SimpleDB

For type=error, fired after any response with an error, the arguments are:

  • err: the error that occurred, an object like {Code:'...',Message:'...'}, where Code is the Amazon error code
  • res: the result
  • meta: the request meta data

For type=status, fired after each retry, the arguments are:

  • done: true if request has finally succeeded
  • tryIndex: count of attempts
  • last: true if this was the last attempt
  • delay: delay in milliseconds until this attempt
  • err: any error that occurred


The unit tests use expresso:

npm install expresso
npm install eyes

To configure your keys, edit the test/keys.js file. The tests are in test/simpledb.test.js

Amazon AWS SimpleDB

Here's some more information on SimpleDB:

Amazon AWS SimpleDB Developer Guide

Hacking around with real time charts

Chartaca Hit Chart

Something went wrong with that request. Please try again.