Backups, restore and updates

Backups

Chemistbook backs itself up. Every hour it looks at when the last good backup was made, and writes one when that was 20 hours ago or more, so a PC that is off at night still gets one within the hour of coming on. Back up now, on Comply → Compliance → Backups, writes one at once.

Each backup is a copy of the whole database, taken while the shop goes on selling, into C:\ProgramData\Chemistbook\backups. Before it counts, the copy is opened on its own and must pass SQLite's integrity check and hold every record saved before it began; a copy that fails either is deleted and the run is reported as failed. The note on each run says how far the records go: Records up to audit row 2126 and stock row 1709; checked whole.

• Encrypted with the backup passphrase from the install: the file ends in .cbk. Without a passphrase the file is the plain database, .db, and the Backups screen says so.
• Copied off the PC to the off-site folder from the install, a USB drive or a folder a sync client takes to the cloud. When the folder is not there, the copy waits and is tried again after 5, 15 and 30 minutes and then every hour. It counts only when the copy reads back the same as the file on the PC.
• Kept: the newest 14 on the PC, and any not yet copied off it. Nothing is ever deleted from the off-site folder.

The passphrase and the off-site folder are in the settings file, C:\ProgramData\Chemistbook\settings\chemistbook.yaml, under otcms: backups: as passphrase and offsite-dir. To change either, edit the file as an administrator and restart the service (see Mail and text messages). A new passphrase applies to the backups written after; the old ones still need the old passphrase.

Once a day, at 07:35 or in the first hour the PC is on after that and never after 21:35, a check raises a reminder and tells the owners if the last backup failed or the last good one is more than 28 hours old.

Putting a backup back

A backup is turned back into a database file by the restore command that comes with Chemistbook. It writes a new file and never writes over one, then checks it: SQLite's integrity check, both hash chains of the record walked from the first row, and the seal of what it holds printed.

In PowerShell, run as administrator:

$cb = "$env:ProgramFiles\Chemistbook"
& "$cb\runtime\bin\java.exe" --enable-native-access=ALL-UNNAMED -cp "$cb\app\chemistbook.jar" `
  "-Dloader.main=com.otcms.api.backup.BackupRestoreCli" org.springframework.boot.loader.launch.PropertiesLauncher `
  "E:\Chemistbook backups\chemistbook-2026-10-09-020252-030.cbk" "$env:TEMP\restored.db"

It asks for the passphrase. What it says when all is well:

Restored chemistbook-2026-10-09-020252-030.cbk to C:\Users\…\Temp\restored.db.
The file checks whole.
audit trail (audit_event): 2126 rows, whole; last row 2126
stock ledger (inventory_movement): 1709 rows, whole; last row 1709
Seal of these records: 2126.1709-84a3df48d230

With the wrong passphrase it says The passphrase is wrong, or the backup is damaged. and writes nothing. A damaged file or a broken chain is named.

To put it in place of the shop's records:

1. Stop the service: in Services, Chemistbook, Stop.
2. Move C:\ProgramData\Chemistbook\data\chemistbook.db aside, and any chemistbook.db-wal and chemistbook.db-shm beside it. Keep them: they hold what was done since the backup.
3. Copy the restored file to C:\ProgramData\Chemistbook\data\chemistbook.db.
4. Start the service, sign in, and check the last sales and the stock.

Everything comes back as it was at the time of the backup: users, catalogue, batches, sales, the audit trail. Sales made after it are not in it; they have to be entered again from the receipts.

On a new PC, install Chemistbook first, then do the same.

Try it once a quarter

A backup that has never been restored is a hope. Every three months, and after every update, restore the newest backup from the USB drive into a scratch file as above, and keep what it says with the licence folder: the records it found whole, and their seal.

Updates

Nothing changes on the PC until someone changes it: Chemistbook does not look for updates and does not download anything. An update is a new installer, run as an administrator when the owner decides. It:

1. stops the service;
2. copies the shop's records to C:\ProgramData\Chemistbook\before-update\chemistbook.db, replacing the copy from the update before, and changes nothing at all if it cannot;
3. replaces the program in C:\Program Files\Chemistbook, and keeps the records, the backups and the settings;
4. starts the service, which brings the records up to the new version as it starts.

It asks nothing: the settings from the first install stay. Then sign in, make a sale and void it, print a receipt, open yesterday's figures, and press Back up now.

Check the installer before running it: compare its SHA-256 (Get-FileHash in PowerShell) with the one published with it.

Going back

If the new version will not start, or is wrong in a way the shop cannot work around:

1. Stop the service.
2. Move data\chemistbook.db aside and keep it: it holds what was sold since the update.
3. Copy before-update\chemistbook.db to data\chemistbook.db.
4. Run the previous installer.
5. Sign in and check the last sales and the stock look as they did before the update, then press Back up now.

Records made after the update are not in the copy from before it; they have to be entered again. Going back without step 3 is not safe: the new version may have changed the records in ways the old one does not expect.