3.0 KiB
| layout | title |
|---|---|
| documentation | JsonDB Storage |
{% include base.html %}
JsonDB Storage
JsonDB provides a system database for storage of configuration data. All configuration data stored into the system through the REST interface that is used by the user interfaces will be stored into the JsonDB. JsonDB provides a high performance, human readable data store that is primarily meant for system use but can be edited manually, or stored in a version control system such as Git.
Technical Overview
The system stores different data into separate tables. JsonDB maps these tables into separate files - in this way each file contains a different type of data (eg. Things, Items, Links). The system also keeps a number of backups in a backup folder. Each time a file is updated, the current version will be moved to the backup folder and timestamped so that the system can retain the most recent files. By default the last 5 copies of each file are retained. When the system loads data from the file system, should it find that a file is corrupted it will attempt to open the most recent backup - it will try each backup in turn until a file is correctly read, or the number of files is reached.
To improve performance and reduce disk use all file writes are deferred for a few hundred milliseconds. This ensures that if there are multiple updates of the database in a short time, the system will only write these updates to the file system after the group of updates completes. If the system gets into a loop such that it is continually updating configuration information in the database, JsonDB will write a file every minute. These timers can be configured by the user along with the number of backup files retained.
It is worth noting that data is only read from the file system when the table is first created - this is normally on system startup. After this the data is retained in memory and only written to file when there are changes.
Manual Editing
Data is stored in a "pretty" format to make it more human readable, and is sorted so ordering is not random (important when a version control system is used). It is therefore editable by advanced users who might want to do a search and replace on item names etc.
If you manually edit the file you must take responsibility for ensuring it is correctly formatted. A Json format checker (such as jsonlin.com) can be used to check the format and this should ensure that the file can be correctly read. It doesn't however ensure that the correct format is used - users wanting to edit a specific table are advised to first configure the system with the UI and then use the format generated by the UI as a template for subsequent additions and changes. Most data stored in the database is written in a way that should be understandable by someone with good knowledge of the system.
As stated above, the files are only read during system startup - therefore if you change a file you will need to stop openHAB, make your changes and restart the system for the changes to take effect.
Example file -: