README.md

DynamoDBDOWN

A LevelDOWN API implementation on Amazon DynamoDB.

This is a drop-in replacement for LevelDOWN that uses Amazon DynamoDB for storage. It can be used as a backend for LevelUP rather than an actual LevelDB store.

As of version 0.7, LevelUP allows you to pass a db option when you create a new instance. This will override the default LevelDOWN store with a LevelDOWN API compatible object. DynamoDBDOWN conforms exactly to the LevelDOWN API, but performs operations against a DynamoDB database.

Usage Example

const levelup = require('levelup')
const DynamoDBDOWN = require('dynamodbdown')

const dynamoDBOptions = {
  region: 'eu-west-1',
  secretAccessKey: 'abc',
  accessKeyId: '123'
}

const options = {
  db: DynamoDBDOWN,
  dynamodb: dynamoDBOptions // required AWS configuration
}

const db = levelup('tableName', options)

db.put('some string', 'LevelUP string')
db.put('some binary', new Buffer('LevelUP buffer'))

const dbReadStream = db.createReadStream()

dbReadStream.on('data', console.log)
dbReadStream.on('close', () => { console.log('read stream closed') })

When running the above example, you should get the following console output:

{ key: 'some binary', value: 'LevelUP buffer' }
{ key: 'some string', value: 'LevelUP string' }
read stream closed

Hash Keys

In DynamoDB, keys consist of two parts: a hash key and a range key. To achieve LevelDB-like behaviour, all keys in a database instance are given the same hash key. That means that you can't do range queries over keys with different hash keys.

The default hash key is !. You can specify it by putting a $ in the location argument. The $ separates the table name from the hash key.

Example

const levelup = require('levelup')
const DynamoDBDOWN = require('dynamodbdown')

const dynamoDBOptions = {
  region: 'eu-west-1',
  secretAccessKey: 'abc',
  accessKeyId: '123'
}

const options = {
  db: DynamoDBDOWN,
  dynamodb: dynamoDBOptions // required AWS configuration
}

const db = levelup('tableName$hashKey', options)

db.put('some key', 'some value', => err {
  // the DynamoDB object would now look like this:
  // {
  //   hkey: 'hashKey',
  //   rkey: 'some key',
  //   value: 'some value'
  // }
})

If you are fine with sharing capacity units across multiple database instances or applications, you can reuse a table by specifying the same table name, but different hash keys.

Table Creation

If the table doesn't exist, DynamoDBDOWN will try to create a table. You can specify the read/write throughput. If not specified, it will default to 1/1. If the table already exists, the specified throughput will have no effect. Throughput can be changed for tables that already exist by using the DynamoDB API or the AWS Console.

See LevelUP options for more information.

Example

const levelup = require('levelup')
const DynamoDBDOWN = require('dynamodbdown')

const dynamoDBOptions = {
  region: 'eu-west-1',
  secretAccessKey: 'abc',
  accessKeyId: '123',
  ProvisionedThroughput: { // capacity can be specified; defaults to 1/1:
    ReadCapacityUnits: 1,
    WriteCapacityUnits: 1
  }
}

const options = {
  db: DynamoDBDOWN,
  dynamodb: dynamoDBOptions // required AWS configuration
}

const db = levelup('tableName', options)

Table Name Encoding

DynamoDBDOWN encodes table names in hexadecimal if you set the dynamodb.hexEncodeTableName option to true. This can be useful if you'd like pass location parameter values to levelup that aren't compatible with DynamoDB's restrictions on table names (see here).

Example

const levelup = require('levelup')
const DynamoDBDOWN = require('dynamodbdown')

const dynamoDBOptions = {
  region: 'eu-west-1',
  secretAccessKey: 'abc',
  accessKeyId: '123',
  hexEncodeTableName: true
}

const options = {
  db: DynamoDBDOWN,
  dynamodb: dynamoDBOptions // required AWS configuration
}

const db = levelup('tableName', options) // the DynamoDB table name will
                                         // be '7461626c654e616d65'

Changelog

See here.

Acknowledgments

DynamoDBDOWN has been heavily inspired by:

• DynamoDOWN by David Guttman
• dynamo-down by Jed Schmidt.

LICENSE

Copyright 2016 Klaus Trainer

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.