Data Storage

Navigate to System > Data Storage to see where Koios keeps tag history and to move it to the new history store.

Tag history is every reading Koios records for trends, exports, the tag history chart and the models that read past values. Earlier versions kept it in a separate time-series database, called the original store on this page. Koios 1.3 can keep it in the configuration database instead, called the new history store.

A new install records to the new history store from the start, and the page says there is nothing to move. An install upgraded from an earlier version keeps recording to the original store until you move its history. Nothing moves on its own: you start the move, and you decide when to switch over.

Moving tag history

The move has four steps, shown across the top of the Tag history panel. Each takes effect within about ten seconds, without restarting anything, and data collection carries on throughout.

Step	What happens	Trends, exports and models read	What you can do
Copy	Koios copies every reading to the new history store in the background, newest first. New readings go to both stores.	The original store	Stop
Check	Koios compares the two stores tag by tag and copies again any tag whose history differs.	The original store	Stop
Switch	You switch reading to the new history store. Both stores are still written.	The new history store	Switch back, or Finalize
Finalize	The original store is no longer written.	The new history store	Nothing; the move is done

1. Start copying

Before the move starts, the panel shows how much free disk the copy needs and how much there is. Start the move with the panel's start button and confirm.

While the copy runs, the panel shows how far back it has reached as a share of all your history, an estimate of the time left, and how many readings it has copied. The estimate assumes the pace so far holds, so it settles once the copy has been running for a while.

2. Let the check finish

When the copy reaches the oldest reading, Koios waits a few minutes for the newest readings to settle, then checks the two stores against each other. A tag whose history differs is copied again, up to five times. Once both stores match, the panel says up to when they were checked, and the switch becomes available.

3. Switch

Switching makes trends, exports and models read from the new history store. Both stores are still written, so switching back loses nothing: anything the original store missed while you were switched is copied back to it. Stay switched for as long as you need to confirm that trends and exports look right.

4. Finalize

Finalizing stops writing the original store and ends the move. What the original store held stays on disk as it was.

Finalizing cannot be undone

After you finalize, there is no switching back, and tag history recorded from then on is only in the new history store. Going back to a version before 1.3 afterwards loses that history. See Going back to an earlier version.

To finalize, type the confirmation word the dialog asks for.

Stopping a move

Before you switch, you can stop the move. The copy is discarded, the new history store is emptied, and tag history stays in the original store, which has every reading. You can start again later.

Disk space

The copy needs free disk on the configuration database's volume while it runs. The page works it out from the size of your tag history before you start: about 85% of the original store's history, for the copy, plus a margin of a quarter of that or 2 GiB, whichever is larger.

Three things enforce it:

The page disables starting when there is not enough free disk, and says how much is needed.
The server checks again when you start, and refuses the move if the copy would not fit.
The copy itself pauses if free disk drops below 2 GiB while it runs, and carries on once there is room again.

The original store keeps its history after the move, so plan for both copies being on disk.

When something goes wrong

If a step cannot complete, for example because free disk ran low, the panel shows what happened and Koios tries again every five minutes. Data collection and trends are unaffected; they keep using the store they were using.

A check that still finds differences after five copies of a tag names how many tags differ and one of them, and keeps trying. Stopping the move and starting again is always safe before you switch.

Backups

A Full backup carries tag history from both stores, so it can be restored at any step. While both stores hold history, a Full backup takes longer and needs more room. See Backup & Restore.

Going back to an earlier version

Going back to a version before 1.3 restores the configuration database as it was before the upgrade, and that version reads the original store. See Upgrading Koios.

Before you finalize, the original store has every reading, so no history is lost.
After you finalize, readings recorded since are only in the new history store, so going back loses them.

Permissions

Moving tag history needs its own permission, under System Administration. Administrator has it, and so does any role that could manage history retention when this version first started. Without it, the page shows the move and its progress with its buttons disabled. See Roles & Permissions.

License notice

The new history store uses TimescaleDB, which is licensed under the Timescale License (TSL). The TSL applies to your use of it. Read the license at github.com/timescale/timescaledb.

Data Retention System Health