sails-dynamodb-v1

A waterline based adapter for accessing dynamoDB with SailsJS Version 1+.

Installation

To install this adapter, run:

$ npm install sails-dynamodb-v1

AWS DynamoDB Credentials are required to access the table, so in config/datastores.js configure following keys

adapter = 'sails-dynamodb-v1'
accessKeyId = <your_access_key>
secretAccessKey = <your_secret_key>
region =
url =

If using default datasore your config/datastores.js should look like.

module.exports.datastores = {
  default: {
    adapter: 'sails-dynamodb-v1',
    accessKeyId: ACCESS_KEY,
    secretAccessKey: SECRET_KEY,
    region: REGION,
}
};

If you are using local dynamodb then url parameter must be passed which is translated to enpoint parameter in dynamodb SDK. accessKeyId, secretAccessKey and region can be any random strings but should not be left blank else adpater will throw an error.

module.exports.datastores = {
  default: {
    adapter: 'sails-dynamodb-v1',
    accessKeyId: "somestring",
    secretAccessKey: "someanotherstring",
    region: "local",
    url:"http://localhost:8000"
}
};

Configuring Models

SailsJS creates an archive models by default, it is recommended that you disable it by setting 'archiveModelIdentity' property to false in config/models.js otherwise a table named as archive will be created

And sails appends three default keys as id, createdAt and updatedAt in each and every model you define. If you want to disable those fields they can be removed from 'attributes' key in config/models.js

Types

Since sails from version 1 supports only 4 types i.e string,number,json and boolean, so to accomodate all the types that are supported by DynamoDB we have to use combination of columnType key and type key in models to set attribute's type. Below is the table showing how dynamo's types can be created.

Dynamo Attribute Type	Sails Model
String	type=string
Number	type=number
Map	type=json && columnType=map
List	type=json && columnType=array
StringSet	type=json && columnType=stringSet
NumberSet	type=json && columnType=numberSet
Boolean	type=boolean
Binary/Buffer	type=string && columnType=binary

Defining Indexes

Since sails do not allow any attributes other than those which are hardcoded here in waterline-schema so there was no possibility to add keys which would differentiate the indexes. But they have a description key which was safe to be used for storing user defined values, so this adapter uses description field to specify indexes in the models.

Below is the list of how you will specify differnt indexes in the table.

Dynamo Index	Sails Model
Hash Key	description = 'hash'
Range Key	description = 'range'
Secondary Index	description = 'local-secondary'
Global Secondary Index	description = 'global-secondary'

Please note that primaryKey field must be initialized as your hash key in models file other wise sails will create an addition field **id** in the model which may cause some unexpected behaviour.
Refer to the example below

Global secondary indexes can have a hash key and range key of their own so the attribute on which you will add description as 'global-secondary' will be considered as hash key and you can specify it's range key in description only after ##

Default index names will be ${hashAttribute}_${columnName}_local_index

For example

// In model file Users.js
module.exports = {
    primaryKey:'userId',
    attributes:{
        userId:{
            type:'string',
            description:'hash'
        },
        gender:{
            type:'string',
        },
        country:{
            type:'string',
            description:'global-secondary##gender'
        },
    }

}

In Users.js userid will be the hash key. So we have specified it in primaryKey key.

A global secondary index will be created with hash key as country and it's range key as gender.

Usage

This adapter implements the following methods:

Method	Status	Category
registerDatastore	done	LIFECYCLE
teardown	done	LIFECYCLE
create	done	DML
createEach	done	DML
update	done	DML
destroy	done	DML
find	done	DQL
join	???	DQL
count	Planned	DQL
sum	NO USE	DQL
avg	NO USE	DQL
define	NO USE	DDL
drop	Planned	DDL
setSequence	???	DDL

Things to keep in mind

Use createEach for multiple entries as it uses batchPut which is much efficient.
In find() the adapter figures out on it's own to query table or it's indexes or scan the table based on the attributes present in query passed. All the key attributes(attributes used in any of the index or hashkey or range key) will be used to query in the following order

HashKey+rangekey > HashKey+LSI > GSI > HashKey > Scan

Non key attributes will be passed in FilterKeys.

For more details on how to use these functions visit Models & ORM in the docs for more information about using models, datastores, and adapters in your app/microservice.

Questions?

See Extending Sails > Adapters > Custom Adapters in the Sails documentation, or check out recommended support options.

License

This sails-dynamodb-v1 adapter is available under the MIT license.

As for Waterline and the Sails framework? They're free and open-source under the MIT License.

AmitPhulera/sails-dynamodb-v1