Add automated database backup and retention

Author: RayJr2

CMakeLists.txt

@@ -66,6 +66,12 @@ qt_add_executable(BrickSuite
     src/services/ReferenceDataSeeder.h
     src/services/database/DatabaseStatusService.h
     src/services/database/DatabaseStatusService.cpp
+    src/services/database/AutomaticBackupPolicy.h
+    src/services/database/AutomaticBackupPolicy.cpp
+    src/services/database/AutomaticBackupService.h
+    src/services/database/AutomaticBackupService.cpp
+    src/services/database/AutomaticBackupRetention.h
+    src/services/database/AutomaticBackupRetention.cpp
     src/services/Logger.h
     src/services/Updater.h
     src/services/Updater.cpp
@@ -353,6 +359,34 @@ target_link_libraries(BrickSuite PRIVATE
 include(CTest)
 
 if(BUILD_TESTING)
+    qt_add_executable(AutomaticBackupPolicyTest EXCLUDE_FROM_ALL
+        tests/AutomaticBackupPolicyTest.cpp
+        src/services/database/AutomaticBackupPolicy.h
+        src/services/database/AutomaticBackupPolicy.cpp
+        src/services/database/AutomaticBackupRetention.h
+        src/services/database/AutomaticBackupRetention.cpp
+    )
+    target_link_libraries(AutomaticBackupPolicyTest PRIVATE Qt6::Core)
+    add_test(NAME AutomaticBackupPolicy COMMAND AutomaticBackupPolicyTest)
+
+    qt_add_executable(AutomaticBackupServiceTest EXCLUDE_FROM_ALL
+        tests/AutomaticBackupServiceTest.cpp
+        src/database/DatabaseManager.h src/database/DatabaseManager.cpp
+        src/database/DatabaseSchema.h src/database/DatabaseSchema.cpp
+        src/settings/UserSettings.h src/settings/UserSettings.cpp
+        src/services/CredentialStore.h src/services/CredentialStore.cpp
+        src/services/database/AutomaticBackupPolicy.h
+        src/services/database/AutomaticBackupPolicy.cpp
+        src/services/database/AutomaticBackupService.h
+        src/services/database/AutomaticBackupService.cpp
+        src/services/database/DatabaseStatusService.h
+        src/services/database/DatabaseStatusService.cpp
+        src/services/database/AutomaticBackupRetention.h
+        src/services/database/AutomaticBackupRetention.cpp
+    )
+    target_link_libraries(AutomaticBackupServiceTest PRIVATE Qt6::Core Qt6::Sql)
+    add_test(NAME AutomaticBackupService COMMAND AutomaticBackupServiceTest)
+
     qt_add_executable(DatabaseStatusServiceTest EXCLUDE_FROM_ALL
         tests/DatabaseStatusServiceTest.cpp
         src/services/database/DatabaseStatusService.h

resources/help/settings.html

@@ -22,6 +22,7 @@ <h1>Settings</h1>
 Application Settings
   Startup preferences
   Appearance
+  Automatic database backup policy and status
   API provider configuration
 </pre>
 
@@ -52,6 +53,51 @@ <h2>Appearance</h2>
 data. Most screenshots in this Help system use Dark theme, so colors may differ when another
 theme is selected.</p>
 
+<h2>Database Backup</h2>
+
+<p>The <b>Database Backup</b> page configures BrickSuite-managed automatic backups. Automatic
+backups are disabled by default. Choose a <b>Backup root</b>, a supported hourly/daily frequency, and how many
+automatic backups to retain, then enable scheduling when you are ready.</p>
+
+<p>BrickSuite appends a folder for the current database schema automatically. For example, a
+backup root ending in <code>BrickSuite/database</code> currently stores automatic backups under
+<code>BrickSuite/database/v29</code>. When a later BrickSuite release uses schema 30, new backups
+will go to <code>v30</code>; BrickSuite does not move or delete the previous <code>v29</code>
+folder.</p>
+
+<p>Automatic filenames use a UTC timestamp, such as
+<code>BrickSuite_AutoBackup_v29_2026-09-03_142530.db</code>. Settings displays backup and due
+times in your local time.</p>
+
+<p><b>Backup Now</b> runs the same automatic pipeline immediately, even when scheduling is
+disabled or a failed scheduled attempt is still within its retry interval. BrickSuite creates a
+read-only health check of the live database first. The automatic pipeline proceeds only when the
+full integrity check is healthy and the foreign-key check has no violations. It then creates a
+SQLite snapshot, verifies database integrity and the current schema version, publishes the final
+automatic filename, and only then applies retention.</p>
+
+<p>If the live database fails either pre-backup health check, BrickSuite skips the automatic
+backup and preserves every existing backup. If a check cannot complete because the database is
+busy, locked, or unavailable, the attempt is deferred without treating the database as corrupt.
+Use <b>Tools → Database Status &amp; Integrity</b> for detailed diagnostics. The manual
+<b>File → Backup Database</b> command remains available as an explicit preservation workflow.</p>
+
+<p>Frequency choices are 1, 4, 8, or 16 hours; 1 or 2 days; and 7 days. The default is
+<b>Every 1 day</b>. After a failed scheduled attempt, retry eligibility is the shorter of the
+configured interval or six hours, with a one-hour minimum. Backup Now bypasses that retry gate.</p>
+
+<div class="note"><b>Retention is deliberately narrow.</b> It applies only to recognized
+BrickSuite automatic backups in the current schema-version folder. It never removes manual
+backups, pre-restore safety backups, unrecognized files, or backups from earlier schema versions.</div>
+
+<p>If an explicitly configured destination is unavailable or not writable, BrickSuite reports
+the failure and keeps that destination unchanged. Scheduled failures do not interrupt normal use,
+and another scheduled attempt is bounded to avoid repeated retry and log noise. Existing verified
+backups remain untouched when creation or verification fails.</p>
+
+<p><b>File → Backup Database</b> remains a separate manual workflow: you choose its filename and
+destination, and automatic retention never applies to it.</p>
+
 <h2>APIs</h2>
 
 <img class="screenshot" src="images/settings_apis_overview.png"

src/app/Application.cpp

@@ -25,6 +25,7 @@
 
 #include "../database/DatabaseManager.h"
 #include "../services/ReferenceDataSeeder.h"
+#include "../services/database/AutomaticBackupService.h"
 #include "../ui/MainWindow.h"
 
 #include <QDebug>
@@ -61,8 +62,12 @@ bool Application::initialize()
     m_workspaceContext = std::make_unique<WorkspaceContext>();
 
     m_mainWindow = std::make_unique<MainWindow>(*m_workspaceContext);
+    m_automaticBackupService = std::make_unique<AutomaticBackupService>();
+    m_mainWindow->setAutomaticBackupService(m_automaticBackupService.get());
     m_mainWindow->show();
 
+    m_automaticBackupService->start();
+
     return true;
 }
 

src/app/Application.h

@@ -27,6 +27,7 @@
 class MainWindow;
 class QWidget;
 class WorkspaceContext;
+class AutomaticBackupService;
 
 class Application
 {
@@ -40,4 +41,5 @@ class Application
 private:
     std::unique_ptr<WorkspaceContext> m_workspaceContext;
     std::unique_ptr<MainWindow> m_mainWindow;
+    std::unique_ptr<AutomaticBackupService> m_automaticBackupService;
 };

src/database/DatabaseManager.cpp

@@ -29,10 +29,28 @@
 #include <QFile>
 #include <QFileInfo>
 #include <QSqlError>
+#include <QRecursiveMutex>
 #include <QStandardPaths>
 #include <QUuid>
 #include <qsqlquery.h>
 
+namespace {
+QRecursiveMutex& maintenanceMutex()
+{
+    static QRecursiveMutex mutex;
+    return mutex;
+}
+
+class AdoptedMaintenanceLock
+{
+public:
+    explicit AdoptedMaintenanceLock(QRecursiveMutex& mutex) : m_mutex(mutex) {}
+    ~AdoptedMaintenanceLock() { m_mutex.unlock(); }
+private:
+    QRecursiveMutex& m_mutex;
+};
+}
+
 DatabaseManager& DatabaseManager::instance()
 {
     static DatabaseManager instance;
@@ -108,17 +126,39 @@ QSqlDatabase DatabaseManager::database() const
 }
 
 bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMessage)
+{
+    if (!maintenanceMutex().tryLock()) {
+        const QString message = "Another database maintenance operation is already running.";
+        if (errorMessage) *errorMessage = message;
+        qWarning() << "Database backup rejected:" << message;
+        return false;
+    }
+    AdoptedMaintenanceLock lock(maintenanceMutex());
+    return backupDatabaseUnlocked(backupPath, errorMessage);
+}
+
+bool DatabaseManager::backupDatabaseUnlocked(const QString& backupPath, QString* errorMessage)
+{
+    return createSnapshot(m_database, backupPath, errorMessage);
+}
+
+bool DatabaseManager::createSnapshot(QSqlDatabase database, const QString& backupPath,
+                                     QString* errorMessage, BackupFailure* failure)
 {
     auto setError = [errorMessage](const QString& message) {
         if (errorMessage)
             *errorMessage = message;
     };
 
-    if (!m_database.isOpen()) {
+    if (failure)
+        *failure = BackupFailure::None;
+
+    if (!database.isOpen()) {
         const QString message = "The BrickSuite database is not open.";
         setError(message);
         qWarning() << "Database backup rejected:" << message;
 
+        if (failure) *failure = BackupFailure::Source;
         return false;
     }
 
@@ -128,7 +168,7 @@ bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMe
 
     if (trimmedPath.isEmpty()) {
         setError("No backup file was selected.");
-
+        if (failure) *failure = BackupFailure::Destination;
         return false;
     }
 
@@ -145,6 +185,7 @@ bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMe
                          .arg(backupDirectory.absolutePath()));
             qCritical() << "Database backup failed:" << message;
 
+            if (failure) *failure = BackupFailure::Destination;
             return false;
         }
     }
@@ -165,6 +206,7 @@ bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMe
                              "backup file:\n%1")
                          .arg(temporaryPath));
 
+            if (failure) *failure = BackupFailure::Destination;
             return false;
         }
     }
@@ -176,7 +218,7 @@ bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMe
     //
     escapedTemporaryPath.replace("'", "''");
 
-    QSqlQuery query(m_database);
+    QSqlQuery query(database);
 
     const QString sql = QString("VACUUM INTO '%1'").arg(escapedTemporaryPath);
 
@@ -188,6 +230,11 @@ bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMe
             QString("Unable to create the database backup.\n\n%1").arg(message));
         qCritical() << "Database backup VACUUM INTO failed:" << message;
 
+        if (failure) {
+            const QString lower = message.toLower();
+            *failure = lower.contains("busy") || lower.contains("locked")
+                           ? BackupFailure::Busy : BackupFailure::Snapshot;
+        }
         return false;
     }
 
@@ -198,6 +245,7 @@ bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMe
                        "the temporary backup file was not created."
                     << "TemporaryPath:" << temporaryPath;
 
+        if (failure) *failure = BackupFailure::Snapshot;
         return false;
     }
 
@@ -213,6 +261,7 @@ bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMe
                              "existing destination file could not be replaced:\n%1")
                          .arg(trimmedPath));
 
+            if (failure) *failure = BackupFailure::Destination;
             return false;
         }
     }
@@ -224,6 +273,7 @@ bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMe
                          "but it could not be renamed to:\n%1")
                      .arg(trimmedPath));
 
+        if (failure) *failure = BackupFailure::Destination;
         return false;
     }
 
@@ -233,6 +283,11 @@ bool DatabaseManager::backupDatabase(const QString& backupPath, QString* errorMe
 }
 
 bool DatabaseManager::verifyDatabaseBackup(const QString& backupPath, QString* errorMessage) const
+{
+    return verifyBackup(backupPath, errorMessage);
+}
+
+bool DatabaseManager::verifyBackup(const QString& backupPath, QString* errorMessage)
 {
     auto setError = [errorMessage](const QString& message) {
         if (errorMessage)
@@ -336,6 +391,58 @@ bool DatabaseManager::verifyDatabaseBackup(const QString& backupPath, QString* e
     return true;
 }
 
+DatabaseManager::VerifiedBackupResult DatabaseManager::createVerifiedBackup(
+    const QString& sourceDatabasePath, const QString& backupPath)
+{
+    VerifiedBackupResult result;
+    result.backupPath = backupPath;
+
+    if (!maintenanceMutex().tryLock()) {
+        result.failure = BackupFailure::Busy;
+        result.errorMessage = "Another database maintenance operation is already running.";
+        return result;
+    }
+    AdoptedMaintenanceLock lock(maintenanceMutex());
+
+    const QString connectionName = QString("BrickSuiteAutomaticBackup_%1")
+                                       .arg(QUuid::createUuid().toString(QUuid::WithoutBraces));
+    const QString pendingPath = backupPath + ".pending."
+                                + QUuid::createUuid().toString(QUuid::WithoutBraces);
+    {
+        QSqlDatabase source = QSqlDatabase::addDatabase("QSQLITE", connectionName);
+        source.setDatabaseName(sourceDatabasePath);
+        source.setConnectOptions("QSQLITE_OPEN_READONLY");
+        if (!source.open()) {
+            result.failure = BackupFailure::Source;
+            result.errorMessage = QString("Unable to open the BrickSuite database for backup.\n\n%1")
+                                      .arg(source.lastError().text());
+        } else if (createSnapshot(source, pendingPath, &result.errorMessage, &result.failure)) {
+            source.close();
+            QString verificationError;
+            if (verifyBackup(pendingPath, &verificationError)) {
+                if (QFile::rename(pendingPath, backupPath)) {
+                    result.success = true;
+                    result.failure = BackupFailure::None;
+                } else {
+                    result.failure = BackupFailure::Destination;
+                    result.errorMessage = QString("The verified backup could not be published as: %1")
+                                              .arg(backupPath);
+                    QFile::remove(pendingPath);
+                }
+            } else {
+                result.failure = BackupFailure::Verification;
+                result.errorMessage = verificationError;
+                if (!QFile::remove(pendingPath))
+                    QFile::rename(pendingPath, pendingPath + ".unverified");
+            }
+        }
+        source.close();
+    }
+    QSqlDatabase::removeDatabase(connectionName);
+    QFile::remove(pendingPath + ".tmp");
+    return result;
+}
+
 QString DatabaseManager::databasePath() const
 {
     const QString dataPath = QStandardPaths::writableLocation(QStandardPaths::AppLocalDataLocation);
@@ -350,6 +457,14 @@ bool DatabaseManager::restoreDatabase(const QString& backupPath, QString* errorM
             *errorMessage = message;
     };
 
+    if (!maintenanceMutex().tryLock()) {
+        const QString message = "Another database maintenance operation is already running.";
+        setError(message);
+        qWarning() << "Database restore rejected:" << message;
+        return false;
+    }
+    AdoptedMaintenanceLock lock(maintenanceMutex());
+
     const QString trimmedBackupPath = backupPath.trimmed();
 
     qInfo() << "Database restore requested:" << trimmedBackupPath;
@@ -546,4 +661,4 @@ bool DatabaseManager::restoreDatabase(const QString& backupPath, QString* errorM
     qInfo() << "Pre-restore safety backup:" << safetyBackupPath;
 
     return true;
-}
+}