feat(cli): add database migrate and backup commands

Author: GaspardKirira

include/vix/cli/commands/db/DbBackup.hpp

@@ -0,0 +1,42 @@
+/**
+ *
+ *  @file DbBackup.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2026, Gaspard Kirira.  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ */
+#ifndef VIX_DB_BACKUP_HPP
+#define VIX_DB_BACKUP_HPP
+
+#include <vix/cli/commands/db/DbTypes.hpp>
+
+namespace vix::commands::db::backup
+{
+  /**
+   * @brief Create a SQLite database backup.
+   *
+   * This function creates a timestamped backup copy of the configured
+   * SQLite database file. If SQLite WAL and SHM files are present, they
+   * are copied beside the database backup as well.
+   *
+   * Current MVP behavior:
+   * - supports SQLite only
+   * - requires the database file to exist
+   * - creates the backups directory if missing
+   * - copies `.db`, `.db-wal`, and `.db-shm` when present
+   *
+   * @param cfg Effective database configuration.
+   * @param options Runtime database options.
+   * @return Process exit code.
+   */
+  int create_backup(
+      const DbConfig &cfg,
+      const DbOptions &options);
+}
+
+#endif

include/vix/cli/commands/db/DbMigrator.hpp

@@ -0,0 +1,41 @@
+/**
+ *
+ *  @file DbMigrator.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2026, Gaspard Kirira.  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ */
+#ifndef VIX_DB_MIGRATOR_HPP
+#define VIX_DB_MIGRATOR_HPP
+
+#include <vix/cli/commands/db/DbTypes.hpp>
+
+namespace vix::commands::db::migrator
+{
+  /**
+   * @brief Apply pending database migrations.
+   *
+   * This function applies file-based SQL migrations from the configured
+   * migrations directory.
+   *
+   * Current MVP behavior:
+   * - supports SQLite only
+   * - requires the storage directory to exist
+   * - requires the migrations directory to exist
+   * - creates the SQLite database file if it does not exist yet
+   *
+   * @param cfg Effective database configuration.
+   * @param options Runtime database options.
+   * @return Process exit code.
+   */
+  int migrate(
+      const DbConfig &cfg,
+      const DbOptions &options);
+}
+
+#endif

src/commands/DbCommand.cpp

@@ -11,8 +11,10 @@
  *  Vix.cpp
  */
 #include <vix/cli/commands/DbCommand.hpp>
+#include <vix/cli/commands/db/DbBackup.hpp>
 #include <vix/cli/commands/db/DbChecker.hpp>
 #include <vix/cli/commands/db/DbConfig.hpp>
+#include <vix/cli/commands/db/DbMigrator.hpp>
 #include <vix/cli/commands/db/DbOutput.hpp>
 #include <vix/cli/commands/db/DbTypes.hpp>
 
@@ -155,33 +157,47 @@ namespace vix::commands
       return 1;
     }
 
-    if (action != "status")
+    const db::DbConfig cfg =
+        db::apply_db_options(
+            db::load_db_config(),
+            options);
+
+    if (action == "status")
     {
-      db::output::error(
-          std::cerr,
-          "unknown db action: " + action);
+      const db::DbCheckResult result =
+          db::checker::check_status(cfg);
 
-      db::output::fix(
-          std::cerr,
-          "vix db --help");
+      db::output::print_status(
+          std::cout,
+          result,
+          options);
 
-      return 1;
+      return exit_code_for_status(result.status);
     }
 
-    const db::DbConfig cfg =
-        db::apply_db_options(
-            db::load_db_config(),
-            options);
+    if (action == "migrate")
+    {
+      return db::migrator::migrate(
+          cfg,
+          options);
+    }
+
+    if (action == "backup")
+    {
+      return db::backup::create_backup(
+          cfg,
+          options);
+    }
 
-    const db::DbCheckResult result =
-        db::checker::check_status(cfg);
+    db::output::error(
+        std::cerr,
+        "unknown db action: " + action);
 
-    db::output::print_status(
-        std::cout,
-        result,
-        options);
+    db::output::fix(
+        std::cerr,
+        "vix db --help");
 
-    return exit_code_for_status(result.status);
+    return 1;
   }
 
   int DbCommand::help()
@@ -190,7 +206,9 @@ namespace vix::commands
         << "Usage:\n"
         << "  vix db [action] [options]\n\n"
         << "Actions:\n"
-        << "  status      Inspect SQLite database and storage status\n\n"
+        << "  status      Inspect SQLite database and storage status\n"
+        << "  migrate     Apply pending file-based SQL migrations\n"
+        << "  backup      Create a SQLite database backup\n\n"
         << "Options:\n"
         << "  --json      Print supported output as JSON\n"
         << "  --verbose   Show verbose diagnostic output\n"
@@ -199,7 +217,9 @@ namespace vix::commands
         << "Examples:\n"
         << "  vix db\n"
         << "  vix db status\n"
-        << "  vix db status --json\n\n"
+        << "  vix db status --json\n"
+        << "  vix db migrate\n"
+        << "  vix db backup\n\n"
         << "Config:\n"
         << "  database.engine\n"
         << "  database.sqlite.path\n"

src/commands/db/DbBackup.cpp

@@ -0,0 +1,191 @@
+/**
+ *
+ *  @file DbBackup.cpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2026, Gaspard Kirira.  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ */
+#include <vix/cli/commands/db/DbBackup.hpp>
+#include <vix/cli/commands/db/DbOutput.hpp>
+#include <vix/cli/util/Ui.hpp>
+
+#include <chrono>
+#include <ctime>
+#include <exception>
+#include <filesystem>
+#include <iomanip>
+#include <iostream>
+#include <sstream>
+#include <string>
+
+namespace fs = std::filesystem;
+
+namespace vix::commands::db::backup
+{
+  namespace
+  {
+    std::string timestamp()
+    {
+      using namespace std::chrono;
+
+      const auto now = system_clock::now();
+      const std::time_t t = system_clock::to_time_t(now);
+
+      std::tm tm{};
+
+#if defined(_WIN32)
+      localtime_s(&tm, &t);
+#else
+      localtime_r(&t, &tm);
+#endif
+
+      std::ostringstream out;
+      out << std::put_time(&tm, "%Y%m%d-%H%M%S");
+      return out.str();
+    }
+
+    fs::path backup_database_path(
+        const DbConfig &cfg,
+        const std::string &stamp)
+    {
+      const std::string stem =
+          cfg.databasePath.stem().string().empty()
+              ? cfg.appName
+              : cfg.databasePath.stem().string();
+
+      const std::string ext =
+          cfg.databasePath.extension().string().empty()
+              ? ".db"
+              : cfg.databasePath.extension().string();
+
+      return fs::path("backups") / (stem + "-" + stamp + ext);
+    }
+
+    bool is_sqlite(const DbConfig &cfg)
+    {
+      return cfg.engine == DbEngine::SQLite;
+    }
+
+    bool copy_if_present(
+        const fs::path &from,
+        const fs::path &to)
+    {
+      if (!fs::exists(from) || !fs::is_regular_file(from))
+        return false;
+
+      fs::copy_file(
+          from,
+          to,
+          fs::copy_options::overwrite_existing);
+
+      return true;
+    }
+
+    fs::path sidecar_backup_path(
+        const fs::path &backupPath,
+        const std::string &suffix)
+    {
+      return fs::path(backupPath.string() + suffix);
+    }
+  }
+
+  int create_backup(
+      const DbConfig &cfg,
+      const DbOptions &options)
+  {
+    (void)options;
+
+    if (!is_sqlite(cfg))
+    {
+      output::error(
+          std::cerr,
+          "vix db backup currently supports SQLite only.");
+
+      output::fix(
+          std::cerr,
+          "set database.engine to sqlite before using vix db backup");
+
+      return 1;
+    }
+
+    if (!fs::exists(cfg.databasePath) ||
+        !fs::is_regular_file(cfg.databasePath))
+    {
+      output::error(
+          std::cerr,
+          "database file not found: " + cfg.databasePath.string());
+
+      output::fix(
+          std::cerr,
+          "run vix db migrate or create the database before backing it up");
+
+      return 1;
+    }
+
+    try
+    {
+      const fs::path backupDir = "backups";
+      fs::create_directories(backupDir);
+
+      const std::string stamp = timestamp();
+      const fs::path backupPath =
+          backup_database_path(cfg, stamp);
+
+      fs::copy_file(
+          cfg.databasePath,
+          backupPath,
+          fs::copy_options::overwrite_existing);
+
+      const bool copiedWal =
+          copy_if_present(
+              cfg.walPath,
+              sidecar_backup_path(backupPath, "-wal"));
+
+      const bool copiedShm =
+          copy_if_present(
+              cfg.shmPath,
+              sidecar_backup_path(backupPath, "-shm"));
+
+      output::step(std::cout, "Database Backup");
+
+      vix::cli::util::kv(
+          std::cout,
+          "Database",
+          cfg.databasePath.string());
+
+      vix::cli::util::kv(
+          std::cout,
+          "Backup",
+          backupPath.string());
+
+      vix::cli::util::kv(
+          std::cout,
+          "WAL copied",
+          copiedWal ? "yes" : "no");
+
+      vix::cli::util::kv(
+          std::cout,
+          "SHM copied",
+          copiedShm ? "yes" : "no");
+
+      output::ok(
+          std::cout,
+          "database backup created");
+
+      return 0;
+    }
+    catch (const std::exception &e)
+    {
+      output::error(
+          std::cerr,
+          "backup failed: " + std::string(e.what()));
+
+      return 1;
+    }
+  }
+}