DynaMaestro was developed to provide an easier way to access a DynamoDB. A lot of the functions use chaining methods to hide away the AWS specific ideology.
npm install dynamaestro
Connnects to the database with supplied credentials and region.
Arguments
credentials- an object with AWS credentialsregion- the region string you would like to use
Example
var dynamaestro = require("dynamaestro");
var config = {
credentials: {
"accessKeyId" : "XXXXXXXXXXXXXXXXX",
"secretAccessKey" : "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
region : "us-west-1"
};
var ddb = new dynamaestro(config);putItem() is a chained function with table(), item(), and execute() chains.
putItem() is used to create a single item from an object. This function will
handle all of the types currently(as of January 2015) available for AWS.
Chained Methods
table(tableName)- tableName - the name of the table that you'd like to scan
item(item)- item - the item object you would like to place on the table
allowOverwrite()- by default, putItem will not overwrite an item as it is better to update, but this override will allow you to use putItem like update.
execute(callback)- callback - returned function with
errorandresponse
- callback - returned function with
Example
var now = new Date();
var testItem = {
user : "username",
created : now.getTime(),
item_id : uuid.v4()
};
ddb.putItem()
.table("testing3")
.item(testItem)
.execute(function(error, response) {
////handle(error, response);
});batchWriteItems() is a chained function with table(), put(), del(), where(), and execute(). batchWriteItems() is used to create and delete multiple items in one call.
Chained Methods
table(tableName)- tableName - the name of the table that you'd like to get an item from.
put(item)- item - the item object that you would like to put on the table.
del()- No arguments, must be followed by one
.where(...)for HASH, and another.where(...)for a HASH AND RANGE.
- No arguments, must be followed by one
where(key, value, nextHash)- key - the key you would like to get
- value - the value of that key
- nextHash - (true | false) Lets the function know to move on to another HASH or HASH/RANGE set.
execute(callback)- callback - function with
errorandresponse
- callback - function with
Example
var now = new Date();
var testItem = {
user: "username",
item_id: "1234-b34c-998e",
created: now.getTime()
};
ddb.batchWriteItems()
.table("tableOne")
.delete()
.where("user", "bob")
.where("item_id", "e313659e-c8ce-4e0c-8fc7-bf01fe514c05")
.delete()
.where("user", "boudrd", true)
.where("item_id", "1fe8a751-7324-4642-8df9-d3a8a4595639")
.put(testItem)
.table("tableTwo")
.put(testItem)
.execute(function(error, response) {
//handle(error, response);
});getItem() is a chained function with table(), where(), select(), and
execute() chains. getItem() is used get a specific item based off a HASH key,
and optionally a RANGE key.
Chained Methods
table(tableName)- tableName - the name of the table that you'd like to get an item from.
where(key, value)- key - the key you would like to get query by
- value - the value of that key
select(atrributes)- attributes - Optional: array of attributes you would like returned
execute(callback)- callback - function with
errorandresponse
- callback - function with
Examples
by HASH & RANGE:
ddb.getItem()
.table("testing2")
.where("user", "boudrd")
.where("item_id", "592c7ec9-4835-4c88-9b5f-c09fe11ebf97")
.execute(function(error, response) {
//handle(error, response);
});by HASH only:
ddb.getItem()
.table("testing2")
.where("item_id", "592c7ec9-4835-4c88-9b5f-c09fe11ebf97")
.execute(function(error, response) {
//handle(error, response);
});batchGetItems() is a chained function with table(), where(), select(), and
execute() chains. getItem() is used get a specific item based off a HASH key,
and optionally a RANGE key.
Chained Methods
table(tableName)- tableName - the name of the table that you'd like to scan
where(key, value, nextHash)- key - the key you would like to get query by
- value - the value of that key
- nextHash - (true | false) Lets the function know to move on to another HASH or HASH/RANGE set.
select(atrributes)- attributes - Optional: array of attributes you would like returned
execute(callback)- callback - function with
errorandresponse
- callback - function with
Example
ddb.batchGetItems()
.table("table1")
.where("user", "username")
.where("item_id", "018654bf-2a10-4b08-918c-f21b0ca3c204")
.where("user", "username", true)
.where("item_id", "23bb7b66-1801-4164-83c0-2a8259261905")
.select(["user", "item_id"])
.table("table2")
.where("user", "username")
.where("item_id", "1211f8fe-2567-44b6-83f0-f82650376a89")
.execute(function(error, response) {
//handle(error, response);
});query() is a chained function with table(), globalIndex(), where(),
select(), and execute() chains. query() is used get a group of items based off
a HASH key. You can also specify a global index to query off a different index.
Chained Methods
table(tableName)- tableName - the name of the table that you'd like to scan
globalIndex(indexName)- indexName - optional: name of the global index you would like to query
where(key, operator, value)- key - the key you would like to get query by
- operator - the comparison operator that you would like to compare the
key and value.
- Available Operators: EQ | NE | IN | LE | LT | GE | GT | BETWEEN | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH
- Note: not all attributes available all the time
- value - the value of that key
select(atrributes)- attributes - optional: array of attributes you would like returned
execute(callback)- callback - function with
errorandresponse
- callback - function with
Examples
Standard query off HASH:
ddb.query()
.table("testing3")
.where("user", "EQ", "username")
.execute(function(error, response) {
//handle(error, response);
});Global Index query:
ddb.query()
.table("testing3")
.globalIndex("indexName")
.where("user", "EQ", "username")
.where("created", "BETWEEN", ["1422048000000","1422049000000"])
.execute(function(error, response) {
//handle(error, response);
});Scan is a chained function with table(), select(), and execute() chains. Scan
is used get the items of an entire database. Better to avoid using scan wherever
possible, and to use query instead.
Chained Methods
table(tableName)- tableName - the name of the table that you'd like to scan
select(atrributes)- attributes - Optional: array of attributes you would like returned
execute(callback)- callback - function with
errorandresponse
- callback - function with
Example
ddb.scan()
.table("testing2")
.select(["user","item_id"])
.execute(function(error, response) {
//handle(error, response);
});updateItem() is a chained function with table(), where(), put(),
increment(), delete(), and execute() chains. updateItem() is used to update
a specific item. You can put new keys, put existing keys, increment
numbers and delete existing keys.
Chained Methods
table(tableName)- tableName - the name of the table that you'd like to scan
where(key, value)- key - the key you would like to get query by
- value - the value of that key
put(key, value)- key - the key you would like to update
- value - the value of that key
increment(key, value)- key - the key you would like to increment
- value - the value that you would like to increment key by
delete(key)- key - the key you would like to delete
execute(callback)- callback - function with
errorandresponse
- callback - function with
Examples
by HASH only:
ddb.updateItem()
.table("testing3")
.where("id", "someId")
.put("updated", now.getTime())
.put("good", "stuff")
.increment("numberOfThings", 50)
.delete("someKey")
.execute(function(error, response) {
//handle(error, response);
});by HASH & RANGE:
ddb.updateItem()
.table("testing3")
.where("user", "username")
.where("item_id", "uniqueID")
.put("updated", now.getTime())
.put("good", "stuff")
.increment("numberOfThings", 50)
.delete("someKey")
.execute(function(error, response) {
//handle(error, response);
});deleteItem() is a chained function with table(), where(), and execute().
deleteItem() is used to delete a specific item.
Chained Methods
table(tableName)- tableName - the name of the table that you'd like to scan
where(key, value)- key - the key you would like to delete an item in
- value - the value of that key
execute(callback)- callback - function with
errorandresponse
- callback - function with
Examples
by HASH only:
ddb.deleteItem()
.table("testing3")
.where("id", "someId")
.execute(function(error, response) {
//handle(error, response);
});by HASH & RANGE:
ddb.deleteItem()
.table("testing3")
.where("user", "username")
.where("item_id", "9d3063b8-2822-4bc7-a3ca-9af2ba8f1032")
.execute(function(error, response) {
//handle(error, response);
});createTable() is a chained function with table(), key(), provision(), and execute(). createTable() is used to programatically create a table.
Chained Methods
table(tableName)- tableName - the name of the table that you'd like to create
key(type, value, keyType, indexType, indexName)- type - (string | number)
- value - name of the key
- keyType - (hash | range) Hash keys are mandatory, Range keys are optional.
- indexType - optional: (global | local)
- indexName - optional: Name of global or local index
provision(readCapacity, writeCapacity, indexType, indexName)- readCapacity - Provisioned throughput capacity you want to reserve for reads.
- writeCapacity - Provisioned throughput capacity you want to reserve for writes.
- indexType - optional: (global | local)
- indexName - optional: Name of global or local index
execute(callback)- callback - function returned with
errorandresponse
- callback - function returned with
Example
ddb.createTable()
.table("tableName")
.key("string", "user", "hash")
.key("string", "itemId", "range")
.provision(5,5)
.key("string", "user", "hash", "global", "byUserByDate")
.key("string", "created", "range", "global", "byUserByDate")
.provision(10, 10, "global", "byUserByDate")
.key("string", "user", "hash", "local", "byUserByCount")
.key("string", "count", "range", "local", "byUserByCount")
.provision(5, 5)
.execute(function(error, response) {
//handle(error, response);
});listTables() will return an array of table names.
Arguments
callback- returned function witherrorandresponse
Example
ddb.listTables(function(error, response) {
//handle(error, response);
});describeTable() is used to gather data about a table. Great for helping to
determine IF a table exists. If you need to create a table, you can check to
see if the table exists before you create it.
Arguments
tableName- name of the table you want more information aboutcallback- returned function witherrorandresponse
Example
ddb.describeTable("testing3", function(error, response) {
if(error && error.code === "ResourceNotFoundException") {
// table doesn't exist
} else {
// table does exist
}
});deleteTable() is used to delete a table.
Arguments
tableName- name of the table you would like to deletecallback- returned function witherrorandresponse
Example
ddb.deleteTable("tableName", function(error, response) {
//handle(error, response);
});whenTableExists() is used to determine when (NOT IF) a table exists. This is useful
to wait to do something to a table that you've just created. The function
polls your database 20 times, checking every 25 seconds to see if the table exists
yet.
Arguments
tableName- name of the table you are waiting for to existcallback- returned function witherrorandresponse
Example
ddb.whenTableExists("testing3", function(error, response) {
//handle(error, response);
});whenTableDoesntExist() is used to determine when (NOT IF) a table no longer exists. This
is useful to wait to do something to a table that you've just deleted. The function
polls your database 20 times, checking every 25 seconds to see if the table still
exists.
Arguments
tableName- name of the table you are waiting for to not existcallback- returned function witherrorandresponse
Example
ddb.whenTableDoesntExist("testing3", function(error, response) {
//handle(error, response);
});