Database Maintenance

The Database Maintenance page in the Tagnet Admin Console provides four self-service operations for keeping your SQLite database healthy: Backup, Restore, Integrity Check, and Compact. These tools are especially useful after large retention purges, before and after upgrades, and as part of a routine maintenance schedule.

Note: Database Maintenance only applies to SQLite deployments. If Tagnet is configured to use SQL Server, the page shows a "Managed by your database administrator" notice and none of the four operations are available. Your DBA handles backup, restore, and maintenance through SQL Server's own tooling.

Before you start

Database Maintenance requires the Admin Console to run as administrator. If you open the page without elevation, you will see a Restart as administrator button. Click it; the console relaunches elevated via UAC and returns you to the Database Maintenance page automatically.

The page header shows a summary of your current install: database provider, database file path, current database size, Tagnet service state, and free space on the data volume. This summary refreshes after each operation so you can see the effect immediately.

Only one maintenance operation can run at a time. While an operation is in progress, all four Run buttons are disabled across the page. Each card shows its own inline progress bar and result panel, so you do not need to scroll elsewhere to find the status of a completed operation.

Backup

Use Backup to create a point-in-time copy of your database before upgrades, configuration changes, or on a regular schedule.

What it does

Tagnet stops the Tagnet Windows service, copies the database to the destination file, and then restarts the service. Stopping the service first ensures the snapshot is consistent. An online copy taken while Tagnet is writing can restart many times as pages change, which on a busy system with active RFID readers can extend the operation significantly.

Important: The default backup destination is on the same volume as the live database: C:\ProgramData\Stratum Global\Tagnet\Backups\tagnet-yyyyMMdd-HHmmssZ.db (UTC timestamp in the filename). A same-volume backup does not protect you from disk failure. Move backup files off-host (to a network share, cloud storage, or backup appliance) for real disaster recovery.

How to run a backup

1. Open Database Maintenance (elevated).
2. In the Backup card, confirm or change the Destination path. Click Browse… to open a file save dialog, or click Use default to regenerate the timestamped default path.
3. Click Take backup.

The progress panel shows the copy step by step. When complete, the result panel confirms the file path and size written. The destination path automatically resets to a new timestamped name after each successful backup so a repeat click does not overwrite the previous file.

If backup fails

Symptom	Likely cause	Fix
"Could not stop the Tagnet service for backup"	The service is in a pending state	Stop the service from the Services page (or services.msc), then retry
"Destination volume has N bytes free; backup needs at least N"	Not enough disk space	Free space on the destination volume or choose a different destination path
"WARNING: Tagnet service did not restart cleanly"	Service failed to restart after backup completed	Start the service from the Services page (or services.msc); the backup file itself is valid

Restore

Use Restore to roll the database back to a previously taken backup. This is a destructive operation. The current live database is replaced.

What it does

Tagnet validates the backup file, stages a copy of it alongside the live database, stops the Tagnet Windows service, swaps the staged copy into place as the new live database, and restarts the service. Before swapping, Tagnet moves the previous live database aside as a rollback artifact named app.db.pre-restore-yyyyMMdd-HHmmssZ in the same directory as the live database. This file is your one-step undo if the restored database turns out to be wrong or the service does not start cleanly.

Tagnet validates the backup before committing to the swap:

• The file must be a valid SQLite database.
• The backup's schema version must not be older than the live database's schema version. Restoring an older-schema backup when the live database has had migrations applied can cause forward-only migrations to re-run against a regressed snapshot. If you need to restore a backup that predates a migration, contact your Tagnet support contact to review the implications first.

Important: Restore replaces the live database. All inventory records, scan events, workflows, and configuration written after the backup was taken will be lost. Verify you are selecting the correct file before proceeding.

How to run a restore

1. Open Database Maintenance (elevated).
2. In the Restore card (styled with a warning border), confirm or change the Source path. If you ran a backup from this page, the most recent backup in the default Backups folder is pre-filled automatically. Click Browse… to select a different file.
3. Type RESTORE (all caps) into the confirmation box. The Restore database button enables only when the phrase matches exactly.
4. Click Restore database.

The progress panel walks through validation, staging, service stop, file swap, and service start. When complete, the result panel shows the source path and the path of the rollback artifact (the previous live database that was moved aside).

If restore fails

Symptom	Likely cause	Fix
"Selected file is not a valid SQLite database"	Wrong file chosen, or file is corrupt	Verify the file path and select a valid .db backup
"Backup is at migration X; live database is at Y"	Backup predates a schema migration	Restore an equal or newer backup, or contact support to review the older-schema scenario
"Could not stop the Tagnet service"	Service stuck in a pending state	Stop the service from the Services page (or services.msc), then retry
"Restore swapped successfully, but the Tagnet service failed to start"	Restored DB may have issues, or a transient service error	The result panel shows the rollback artifact path. Check the Tagnet logs at C:\ProgramData\Stratum Global\Tagnet\logs. To revert: stop the TagNet service, rename app.db to something else, delete app.db-wal and app.db-shm if they are present, rename the .pre-restore-... file back to app.db, then start the service. The -wal and -shm files belong to the database you renamed away; left in place, they would be applied to the restored file on the next start

Integrity Check

Use Integrity Check to verify the internal consistency of the database. Run this after an unexpected shutdown, if you suspect disk errors, or before taking a backup you intend to archive.

Quick vs. Deep

Select the check depth using the radio buttons on the card:

Option	What it checks	Typical duration
Quick (default)	Page-level structure and common corruption indicators	Seconds
Deep	Full B-tree walk across all tables and indexes; catches more subtle issues	Minutes on databases larger than a few hundred MB

Tagnet does not stop the service for an integrity check. The check opens the database read-only and has no impact on normal operation.

How to run an integrity check

1. Open Database Maintenance (elevated).
2. In the Integrity Check card, select Quick or Deep.
3. Click Run integrity check.

The result panel reports pass or fail. If the check fails, the first issues found are listed directly in the result panel so you can see what SQLite reported without opening a log file.

If the check fails

A failed integrity check indicates database corruption. Do not ignore it. Recommended steps:

1. Stop writing new data (stop the Tagnet service via services.msc) to prevent further divergence.
2. Restore from the most recent known-good backup using the Restore card above.
3. If no clean backup is available, contact your Tagnet support contact; partial data recovery may be possible.

Compact

Use Compact to reclaim disk space after large deletions. When rows are deleted, the freed pages are marked reusable but remain in the file; only a rewrite of the database removes them. The retention job does this rewrite itself at the end of a run when it is worth it: at least a quarter of the file (and at least 64 MB) was already reclaimable when the run started, and the data volume has about twice the database size free for the rewrite's working copies. Space the run frees itself is judged on the next run, because day-to-day ingest normally reuses it and the file does not grow; after a one-time cleanup, such as shortening a retention window, the file is compacted the following night. Otherwise the run's detail page records why it skipped. Compact is for the other cases: a one-off cleanup, a file where the free space never crosses that threshold, or a volume that was too full for the job to rewrite the file safely.

Tip: Take a backup before running Compact. Compact rewrites the entire database file and needs roughly as much free disk space as the current database size to do so.

What it does

Tagnet stops the Tagnet Windows service so Compact can hold an exclusive write lock cleanly, runs the database compaction, and then restarts the service. The result panel reports the size before and after, so you can see exactly how much space was reclaimed.

How to run Compact

1. Open Database Maintenance (elevated).
2. In the Compact card, click Compact database.

The operation can take several minutes on large databases. The progress panel stays visible for the duration. When complete, the install summary header updates to reflect the new database size.

If Compact fails

Symptom	Likely cause	Fix
"Data volume has N bytes free; VACUUM needs roughly N"	Not enough free space on the data volume	Free space on the data volume; Compact needs approximately the current database size as working space
"VACUUM failed"	SQLite error during rewrite	Run an Integrity Check first; if the database is corrupt, restore from backup before trying again
"WARNING: Tagnet service did not restart cleanly"	Service failed to restart after Compact completed	Start the service from the Services page (or services.msc); the compacted database is valid

Pre-migration backups

Some Tagnet upgrades change the database schema. On SQLite, the Tagnet service takes its own safety copy of the database before it applies those changes, every time, with no action on your part. The copy is written to the same Backups folder as manual backups:

C:\ProgramData\Stratum Global\Tagnet\Backups\pre-migration-<from>-to-<to>-yyyyMMdd-HHmmssZ.db

<from> and <to> are the schema versions the upgrade moved between, so the file name tells you which upgrade it belongs to. The copy is taken while the service is starting, before any request is served; on a large database this can add a minute or two to the first start after an upgrade, and the service shows as Running in services.msc for the duration.

Tagnet keeps the copies for the last three upgrades and removes older ones. To keep more or fewer, set Database:PreMigrationBackupsToKeep in appsettings.Production.json (see Administration).

The copy needs free space on the data volume equal to the current database size. If there is not enough, the service does not start and the log names the shortfall (Windows retries the start twice, a minute apart, before leaving the service stopped); free space and start the service again. The schema change has not run at that point, so nothing needs to be undone.

If you stop the service while the copy or the schema changes are running, it stays in the Stopping state until they have finished, then stops. Let it finish rather than ending the process: a schema change that is cut short has to be recovered from the copy.

The installer waits on its progress page for the copy and the schema changes to finish before it completes (see Upgrading from an existing installation), so a restart prompt from Windows cannot arrive while they are running. If you start the service by hand after an upgrade instead, the service writes its progress to .initialization.json in the data folder (state is Running, then Completed or Failed with the reason; phase says which step it is in: Checking, Copying, Migrating or Seeding), which is the quickest way to tell whether an upgrade is still running. A restart that cuts a schema change short is survivable, the service resumes from the last completed change when it starts again, but it is avoidable.

Rolling back an upgrade

When the installer's own database step fails, the installer rolls the upgrade back for you, copy included (see Upgrading from an existing installation). The steps below are for rolling back an upgrade that completed, or one that was interrupted by a restart.

Rolling back means returning to the previous Tagnet version and the pre-migration copy together. Restoring the copy under the new version only leads the service to migrate it again on the next start.

1. Uninstall the current Tagnet version and install the previous version's MSI. The installer refuses to install an older version over a newer one, which is why the uninstall comes first. Your data folder and appsettings.Production.json are preserved.
2. If the service ran as a Windows account or gMSA, set it again on the Service Account page. Uninstalling removes the service registration, so the reinstalled service runs as LocalService until you do.
3. Open Database Maintenance (elevated) and, in the Restore card, click Browse… to select the pre-migration-... file for the upgrade you are undoing. The pre-filled path only considers manual backups. Pick the copy whose <from> is the schema version the previous Tagnet version ran. If the upgrade was interrupted and resumed (a restart during the schema changes), there is a second, later copy taken partway through; that one is not a rollback point for the previous version, so choose the earlier file.
4. Tick Allow older schema. The live database is still at the newer schema, so Restore refuses the older copy without it.
5. Type RESTORE and click Restore database. The service restarts on the previous version with the previous schema.

Anything recorded between the upgrade and the rollback is lost, the same as with any restore.

Backup file locations

By default, backups created from this page are stored at:

C:\ProgramData\Stratum Global\Tagnet\Backups\tagnet-yyyyMMdd-HHmmssZ.db

Pre-migration copies taken automatically before an upgrade are stored in the same folder as pre-migration-<from>-to-<to>-yyyyMMdd-HHmmssZ.db (see Pre-migration backups).

Rollback artifacts created during a Restore are stored next to the live database:

C:\ProgramData\Stratum Global\Tagnet\data\app.db.pre-restore-yyyyMMdd-HHmmssZ

Both paths use UTC timestamps. You can safely delete old rollback artifacts and superseded backups once you have confirmed the current database is healthy. Do not delete the most recent backup until you have taken a new one.

Related

• SQL Server Setup: configure Tagnet to use SQL Server instead of SQLite