Registry database

Starting from the version 3.4, EVA ICS uses structured document database as the primary storage of all configurations. In EVA ICS it is called “document registry system” or just “registry”.

Contents

• Registry database

  • Technology

  • Reasons

  • Configuration

  • Maintenance

  • Structure

  • SDK

Technology

EVA ICS uses YEDB as the structured database. YEDB is fast, easy to repair and crash-free.

Registry server is started with “/opt/eva/sbin/registry-control start” and MUST be always online. When YEDB is upgraded, all EVA ICS components should be stopped (vendor-provided upgrade scripts stop everything automatically).

Registry can be managed with “eva-registry”, “eva registry manage” and “sbin/eva-registry-cli” command-line tools.

Reasons

Why EVA ICS has been switched to the registry database, instead of using simple “ini” and “json” files:

• Crash-free storage of configurations, inventory and data objects;

• easy management with command line tools and API;

• strict data schemas;

• unification;

• easy-to-use SDK.

Configuration

YEDB configuration is defined in “etc/eva_config”.

#SYSTEM_NAME=nodename
#YEDB_REGISTRY_DIR=/opt/eva/runtime/registry
#YEDB_SOCKET=/opt/eva/var/registry.sock
#YEDB_SERVER_ENABLED=1
#YEDB_TIMEOUT=5
#YEDB_AUTO_BAK=10
# Extend this if required (replace hostname with the node name)
#YEDB_SKIP_BAK=eva3/hostname/state
#YEDB_WORKERS=2
#YEDB_CACHE_SIZE=10000
#YEDB_STRICT_SCHEMA=1
# seconds to wait until the complete registry startup. increase for large setups
# (the registry checks itself after crashes, which may take longer)
#YEDB_MAX_START_WAIT=5
#YEDB_SUPERVISORD_PROGRAM=eva-registry
#YEDB_USER=
# set to 1 to enable verbose startup
#VERBOSE_STARTUP=
# controller startup timeout
#STARTUP_TIMEOUT=90

It is also possible to use a single registry database for different EVA ICS nodes. if “YEDB_SERVER_ENABLED” is set to “0”, the server is not stared/stopped locally.

Warning

It is highly recommended to keep strict data schema (enabled by default).

If configuration file is not created, EVA ICS starts and uses registry server with the default settings.

Maintenance

When deploying / undeploying lots of items, old registry keys are not deleted but moved to the database trash. It is a good idea to clean it from time to time with “eva-registry purge” or “registry_safe_purge” API method.

“.trash” folder can also be used to restore keys deleted by accident.

When key data is changed, the server keeps its 10 backup copies by default, which can be also used to restore data if necessary.

To list deleted and backup copies, use “ls -a” command of “eva-registry” tool.

All data is stored in “runtime/registry” directory, which should not be accessed directly, unless data loss occur.

Structure

Each EVA ICS node creates registry key “eva3/<SYSTEM_NAME>”, all data is being stored in its sub-keys.

A strict schema “.schema/eva3/<SYSTEM_NAME>” is created for all data keys, except “userdata” key, which (as well as its subkeys) can contain any fields.

Keys can be edited with “eva-registry” and “eva-registry-cli” CLI tools.

Key	user-editable	Description
config/common/mailer	yes	mailer configuration
config/watchdog	yes	controller watchdog
config/venv	yes	venv configuration
config/<controller>/main	yes	primary controller configuration
config/<controller>/apikeys/<key>	yes	static API keys
config/<controller>/service	may	startup configuration
config/<controller>/plugins/<plugin>	yes	plugin configuration
config/uc/datapullers/<datapuller>	may	datapuller configuration
config/uc/drivers	not rec.	UC drivers
config/uc/defaults	yes	item defaults
config/lm/defaults	yes	item defaults
config/inventory	not rec.	inventory key (EVA ICS items)
config/data	forbidden	system objects
config/userdata	yes	any user-defined data

SDK

eva.registry module provides functions for registry management. All functions set key prefix (“eva3/<SYSTEM_NAME>/”) automatically.

The module can be imported and used in plugins, LM PLC macros or anywhere else. When imported by 3rd-party scripts with EVA ICS “lib” directory added to the import path, the module automatically initializes itself with the proper system name and connection settings from “eva_config” file.

eva.registry.config_get(key, **kwargs)

Get key as configuration object

eva.registry.get_subkeys(key)

Get keys recursive as a dict

eva.registry.key_as_dict(key, **kwargs)

Work with key as with a dict

with key_as_dict(key): …

eva.registry.key_decrement(key)

Decrement key value

eva.registry.key_delete(key)

Delete key

eva.registry.key_delete_field(key, field, **kwargs)

Delete key field

eva.registry.key_delete_recursive(key)

Delete keys recursive

eva.registry.key_get(key, default=<class 'KeyError'>)

Get key

eva.registry.key_get_field(key, field, default=<class 'KeyError'>)

Get key field

eva.registry.key_get_recursive(key)

Get keys recursive as [(key, value)] list

eva.registry.key_import(key, fh)

Import key from stream or file

eva.registry.key_increment(key)

Increment key value

eva.registry.key_set(key, value, **kwargs)

Set key

eva.registry.key_set_field(key, field, value, **kwargs)

Set key field

eva.registry.safe_purge()

Purge database, keep broken keys

Module variables:

• SYSTEM_NAME name of the current node

• db YEDB Python object, can be used e.g. to manipulate keys without auto-prefixing.

It is also possible to work with registry server using the official API and clients. See https://yedb.bma.ai/ for more details.