Skip to content

Select Persistence Driver

Calin Crisan edited this page Apr 30, 2021 · 3 revisions

About

qToggleServer can store data using one of the various available persistence drivers, which correspond to different underlying technologies, ranging from simple JSON files to database servers. Choosing one particular persistence driver is an important matter and should be done based on the way the qToggleServer setup will be used.

Available Drivers

Please consult qtoggleserver.conf for details on how to configure a specific driver. The following drivers are available to be used with qToggleServer:

JSON

Use the JSON driver when you run a small qToggleServer setup that:

  • doesn't activate as a master device (or works with just a few slave devices)
  • doesn't record history
  • has a relatively small number of ports (below let's say 100)

This driver has no external dependencies and is used by default. It will use a simple JSON file.

Redis

Use the Redis driver when:

  • you have the possibility to install and connect to a Redis server
  • you run a relatively larger qToggleServer setup with possibly many slave devices and/or ports
  • you don't need to record history

You'll need to set up a Redis server as well as installing the redis Python package (pip install redis).

MongoDB

The MongoDB driver is suitable for systems that:

  • work with possibly many slave devices and/or ports
  • have the possibility to connect to a MongoDB server
  • need to record history

You'll need to set up a MongoDB server as well as installing the pymongo Python package (pip install pymongo).

PostgreSQL

The PostgreSQL driver is suitable for systems that:

  • work with possibly many slave devices and/or ports
  • have the possibility to connect to a PostgreSQL server
  • need to record history

You'll need to set up a PostgreSQL server as well as installing the asyncpg Python package (pip install asyncpg).

Change Procedure

Changing the driver can be as easy as updating the persist section in your qtoggleserver.conf, as needed, followed by a restart. But given that you're changing the persistence mechanism, as soon as your system will start with the new driver, you will end up with an emtpy, default setup (i.e. no slave devices, no virtual ports, no particular port or device configuration).

If you want to preserve your configuration between persistence driver changes, you'll need to do a backup/restore operation. Here are the steps required to change the persistence driver:

  1. Use the Settings section of your qToggleServer app to download a backup of your configuration; make sure to check all available backup options, except for System Configuration, as it represents the contents of your qtoggleserver.conf. You'll get a JSON file containing all the available backup information.

  2. Stop qToggleServer (the stop command depends on the way you installed qToggleServer).

  3. Install any dependencies required by the persistence driver you have chosen. Ensure your database server is properly configured and running, if applicable.

  4. Open your qtoggleserver.conf and look for the persist section; configure your desired driver as indicated here. The configuration file location depends on the way you run qToggleServer.

  5. Start qToggleServer (again, the start command depends on the way you installed qToggleServer).

  6. Use the Settings section of your qToggleServer app to upload the restore file generated at step (1); make sure to check all available backup options, except for System Configuration (if it happens to be present), as it represents the contents of your qtoggleserver.conf, which you don't want to restore.

  7. Restart your system (not necessary if you were able to check the Reboot option at the previous step).

You should have your old configuration available on the new persistence mechanism. Keep in mind though that there are some limitations that can't be currently overcome:

  • device passwords cannot be backed-up/restored so you'll basically have to reenter them (doesn't apply to slave devices)
  • there's no way to backup/restore historical data, even if both former and current drivers support history API