Key-Value DB

Description

ezvpn-db-key-value is a container acting as a key-value store with:

  • in-memory key-store database
  • real-time notification on value change
  • scheduled MQTT notifications

With ezvpn-db-key-value you can:

  • set a key to hold a value.
  • get the value of key.
  • notify the MQTT broker upon a change of value of any key value
  • notify the MQTT broker periodically of the current key values

Key-Value DB is usually written by EXCH programs and provides a convenient in-memory store and an automatic notification infrastructure.

How to use it

ezvpn-db-key-value is a Docker container image pre-configured for communication with ezvpn-mqtt. In case you need to use it with your MQTT broker, see the section regarding customization below.

If used with ezvpn-mqtt, only one environment variable must be provided: DB_CFG.

DB_CFG is a string representing a JSON object, describing the Key-Value DB configuration, addresses, schedules, subscription.

This below is an example that:

  • upon each incoming write, send the value only if the new value is different from the cached one
  • send the value of setpoint and temp inside every 10s
  • send the value of pressureevery 10 minutes at second 0
{
    "publishOnChange": true,
    "schedules": [
        {
            "every": "10s",
            "addresses": ["setpoint", "temp inside"]
        },
        {
            "cron": "0 */10 * * * *",
            "addresses": ["pressure"]
        }
    ]
}

Mapping configuration (DB_CFG)

The JSON has two objects and one array field:

{
    "publishOnValue": <true or false>,
    "publishOnChange": <true or false>,
    "schedules": []
}

publishOnChange and publishOnValue define the behavior of the real time notifications; when a new value is written to any key, the MQTT internal broker is immediately notified of the change based on the value of publishOnChange and publishOnValue.

schedules defined the behavior of periodical notifications.

  • publishOnValue: is a boolean property. If true, upon each incoming write, the new value, even if equal to the previous one, is sent to the MQTT broker. If true, the value of publishOnChange is not used. Defaults to false.
  • publishOnChange: is a boolean property. If true, upon each incoming write, the value is sent to the MQTT broker only if different from the cached value. Not used if publishOnValue is true. Defaults to false.
  • if neither one is defined, real-time notifications are disabled.
  • schedules: contains a list of scheduled MQTT notifications set.

Schedules

schedules represents a list of periodical notifications on the key-value store. The schedules field is optional.

If schedules is not defined, the container is just a key-value store with notification.

Each schedule has its independent execution frequency and it can span over different addresses.

This is the structure of a schedule object:

{
    "every": "<frequency>",
    "cron": "<frequency time>",
    "timezone": "<timezone>",
    "addresses": [<addresses list>]
}

The notification frequency is specified using the alternative every or cron syntax.

every or cron cannot both be defined in the same schedule definition.

  • every: can be supplied in : human readable time format

  • cron: can be supplied in : cron time format

  • timezone: an optional timezone, see the list, to use for the cron expression. If not defined UTC is used.

  • addresses: is an array of addresses names, in string format. The addresses name are automatically defined. Required.

How to write values

You can write to the key-value store sending mqtt messages to fld/db-key-value/w/<measure name>.

The value of the MQTT messages will be stored in the key <measure name>.

You can also send values

  • using the standard EXCH MQTT statements (e.g. writeField "db-key-value" "myMeasure" 123.45).
  • forwarding messages through other containers (MQTT to MQTT, MQTT Broker)
  • publishing directly messages from your custom container (e.g. from the command line: mosquitto_pub -t 'fld/db-key-value/w/pressure' -m '123')

Examples of use

Minimal configuration (only key-value store)

You can define a minimal configuration as an empty object. In this case, you are using the container as an in-memory database. Notifications are disabled.

{}

Publish the last values received every 10 minutes (band throttling)

An EXCH program might write some pressure values, received from a PLC with high frequency, as tenths of bar and converted to bar and psi.

The Key-Value DB is publishing the last stored values, in bar and psi, every 10 minutes

EXCH Program
${_v} = ${_v} / 10
writeField "db-key-value" "barPressure" ${_v}
writeField "db-key-value" "psiPressure" call(bar_to_psi, ${_v})
DB_CFG
{
    "schedules": [
        {
            "cron": "0 */10 * * * *",
            "timezone": "America/Phoenix",
            "addresses": ["barPressure", "psiPressure"]
        }
    ]
}

Environment variables

When you start the ezvpn-db-key-value image, you can adjust the instance's configuration by passing one or more environment variables to the docker run command.

  • DB_CFG: Key-Value mapping description, as documented above. Required.
  • MQTT_HOST: ip address / host name of the MQTT broker. Defaults to 127.0.0.1 (In IOhubTM the variable is set to ezpn-mqtt value)
  • MQTT_PORT: MQTT broker port. Defaults to 1883.
  • NO_RETAIN: if true values are sent to MQTT_HOST without the retain flag; defaults to false.

With NO_RETAIN set to false, each client that subscribes to a topic pattern receives the retained message immediately after they subscribe.

The broker stores only one retained message per topic.

Docker container details

Image: us-central1-docker.pkg.dev/ez-shared/iohub/iohub-db-key-value

Supported architecture: amd64

Changelog

v1.0.1
  • Timezone added in cron expression
v1.0.0
  • First Release