Amazon DynamoDB Persistence

• Introduction
• Features
• Installation
  • Setting up Amazon account
  • Openhab configuration
• Details
  • Tables created by the addon
  • Caveats
  • Pricing
• Disclaimer

Introduction

This service allows you to persist state updates using the Amazon DynamoDB database. Also query functionality is fully supported. Users are recommended to familiarize with AWS Pricing before using this plugin.

This plugin was first introduced in openHAB 1.9.0.

Features

General:

• Writing/reading information to relational database systems.
• Database Table Name configurable
• Automatic creation of tables

Installation

1. Set-up Amazon account as described below (see Setting up Amazon account)
2. For installation of this persistence bundle, please follow the same steps as if you would install a binding.
3. Place a persistence file called dynamodb.persist in the ${openhab.home}/configuration/persistence folder. This has the standard format as described in Persistence.
4. Configure openhab.cfg (see Openhab configuration below)

Setting up Amazon account

1. Sign up for Amazon AWS
2. Select the AWS region in the AWS console using these instructions. Note the region identifier in the url (e.g. https://eu-west-1.console.aws.amazon.com/console/home?region=eu-west-1 means that region id is eu-west-1)
3. Create user for openhab with IAM
4. Open Services -> IAM -> Users -> Create new Users. Enter openhab to User names, keep Generate an access key for each user checked, and finally click Create.
5. Show User Security Credentials and record the keys displayed
6. Configure user policy to have access for dynamodb
7. Open Services -> IAM -> Policies
8. Check AmazonDynamoDBFullAccess and click Policy actions -> Attach
9. Check the user created in step 2 and click Attach policy

Openhab configuration

Basic configuration

Configure addon using openhab.cfg, for example

dynamodb:accessKey=foo
dynamodb:secretKey=bar
dynamodb:region=eu-west-1

The accessKey and secretKey correspond to credentials shown in IAM when creating the AWS user. Region needs to match the region what was used to create the user.

Alternative configuration using credentials file

Alternatively, instead of specifying accessKey, secretKey, one can configure profilesConfigFile (path to Amazon credentials file) and profile (name of profile to use). For example,

dynamodb:profilesConfigFile=/home/openhab/aws_creds
dynamodb:profile=fooprofile
dynamodb:region=eu-west-1

Example of credentials file (/home/openhab/aws_creds):

[fooprofile]
aws_access_key_id=testAccessKey
aws_secret_access_key=testSecretKey

Please note that the user that runs openhab must have approriate read rights to the credential file. For more details on the Amazon credential file format, see Amazon documentation.

Advanced configuration

Other configuration parameters for the dynamodb addon:

• readCapacityUnits, read capacity for the created tables. Defaults to 1.
• writeCapacityUnits, write capacity for the created tables. Defaults to 1.
• tablePrefix, table prefix used in the name of created tables. Defaults to openhab-.

Refer to amazon documentation on provisioned throughput on details on read/write capacity.

Details

Tables created by the addon

When item is persisted via this addon, a table is created if necessary. Currently the addon will create at most two tables for different item types. The tables will be named <PREFIX><ITEMTYPE>, where <PREFIX> matches the tablePrefix configuration; while the <ITEMTYPE> is either bigdecimal (numeric items) or string (string and complex items).

Each table will have three columns: itemname (item name), timeutc (in ISO 8601 format with millisecond accuracy), and itemstate (either number or string representing item state).

Caveats

• When the tables are created, the read/write capacity is configured according to configuration. However, the addon does not modify the capacity of existing tables. As a workaround you can modify the read/write capacity of existing tables using Amazon console.

Pricing

Please note that there might be charges from Amazon when using this addon to query/store data to DynamoDB. See Amazon DynamoDB pricing pages for more details. Please also note possible Free Tier benefits.

Disclaimer

This addon is provided "AS IS", and the user takes full responsibility of any charges, damage to amazon data.