db(migrations): implement schema diff-based makemigrations tool

- Add MakeMigrations pipeline (schema diff → up/down SQL)
- Introduce JSON schema loading and snapshot handling
- Generate deterministic, timestamped migration files
- Wire migrator CLI with DB drivers (MySQL supported)
- Expose migration, diff, sql and schema APIs publicly
- Make migrator tool buildable via VIX_DB_BUILD_TOOLS

Author: GaspardKirira

CMakeLists.txt

@@ -18,7 +18,9 @@ include(GNUInstallDirs)
 # ------------------------------------------------------------------------------
 option(VIX_DB_BUILD_TESTS       "Build unit tests for Vix DB"                 OFF)
 option(VIX_DB_BUILD_EXAMPLES    "Build examples for Vix DB"                  OFF)
-option(VIX_DB_BUILD_TOOLS       "Build DB CLI tools (migrator)"              OFF)
+if (DEFINED VIX_UMBRELLA_BUILD)
+  set(VIX_DB_BUILD_TOOLS ON CACHE BOOL "Build DB CLI tools (migrator)" FORCE)
+endif()
 
 # SQL engines (drivers)
 option(VIX_DB_USE_MYSQL         "Enable MySQL Connector/C++ driver"          ON)
@@ -222,6 +224,9 @@ set(VIX_DB_SOURCES
   src/mig/MigrationsRunner.cpp
   src/mig/FileMigrationsRunner.cpp
   src/Sha256.cpp
+  src/schema/Json.cpp
+  src/mig/diff/Diff.cpp
+  src/mig/sql/MySqlGenerator.cpp
 )
 
 # MySQL driver sources
@@ -261,6 +266,7 @@ if (VIX_DB_BUILD_TOOLS)
   target_sources(vix_db_migrator PRIVATE
     ${CMAKE_CURRENT_SOURCE_DIR}/tools/migrator/main.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/tools/migrator/MigratorCLI.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/tools/migrator/MakeMigrations.cpp
   )
 
   target_link_libraries(vix_db_migrator PRIVATE vix::db)

include/vix/db/mig/diff/Diff.hpp

@@ -0,0 +1,17 @@
+#ifndef VIX_DB_MIG_DIFF_DIFF_HPP
+#define VIX_DB_MIG_DIFF_DIFF_HPP
+
+#include <vix/db/mig/diff/Op.hpp>
+#include <vix/db/schema/Schema.hpp>
+
+#include <vector>
+
+namespace vix::db::mig::diff
+{
+  // MVP: only supports create/drop table, add/drop column, create/drop index
+  std::vector<Op> diff_or_throw(const vix::db::schema::Schema &from,
+                                const vix::db::schema::Schema &to);
+
+} // namespace vix::db::mig::diff
+
+#endif

include/vix/db/mig/diff/Op.hpp

@@ -0,0 +1,54 @@
+#ifndef VIX_DB_MIG_DIFF_OP_HPP
+#define VIX_DB_MIG_DIFF_OP_HPP
+
+#include <vix/db/schema/Schema.hpp>
+
+#include <string>
+#include <variant>
+#include <vector>
+
+namespace vix::db::mig::diff
+{
+  using vix::db::schema::Column;
+  using vix::db::schema::Index;
+  using vix::db::schema::Table;
+
+  struct CreateTable
+  {
+    Table table;
+  };
+
+  struct DropTable
+  {
+    Table table; // keep full table for down
+  };
+
+  struct AddColumn
+  {
+    std::string table;
+    Column column;
+  };
+
+  struct DropColumn
+  {
+    std::string table;
+    Column column; // keep full def so down can re-add
+  };
+
+  struct CreateIndex
+  {
+    std::string table;
+    Index index;
+  };
+
+  struct DropIndex
+  {
+    std::string table;
+    Index index; // keep def for down (recreate)
+  };
+
+  using Op = std::variant<CreateTable, DropTable, AddColumn, DropColumn, CreateIndex, DropIndex>;
+
+} // namespace vix::db::mig::diff
+
+#endif

include/vix/db/mig/sql/MySqlGenerator.hpp

@@ -0,0 +1,16 @@
+#ifndef VIX_DB_MIG_SQL_MYSQL_GENERATOR_HPP
+#define VIX_DB_MIG_SQL_MYSQL_GENERATOR_HPP
+
+#include <vix/db/mig/diff/Op.hpp>
+
+#include <string>
+#include <vector>
+
+namespace vix::db::mig::sql
+{
+  std::string to_mysql_up(const std::vector<vix::db::mig::diff::Op> &ops);
+  std::string to_mysql_down(const std::vector<vix::db::mig::diff::Op> &ops);
+
+} // namespace vix::db::mig::sql
+
+#endif

include/vix/db/schema/Json.hpp

@@ -0,0 +1,16 @@
+#ifndef VIX_DB_SCHEMA_JSON_HPP
+#define VIX_DB_SCHEMA_JSON_HPP
+
+#include <vix/db/schema/Schema.hpp>
+
+#include <string>
+
+namespace vix::db::schema
+{
+  // Serialize/deserialize schema snapshot (nlohmann/json)
+  std::string to_json_string(const Schema &s, bool pretty = true);
+  Schema from_json_string_or_throw(const std::string &json);
+
+} // namespace vix::db::schema
+
+#endif

include/vix/db/schema/Schema.hpp

@@ -0,0 +1,88 @@
+#ifndef VIX_DB_SCHEMA_SCHEMA_HPP
+#define VIX_DB_SCHEMA_SCHEMA_HPP
+
+#include <vix/db/schema/Types.hpp>
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace vix::db::schema
+{
+  struct Column
+  {
+    std::string name;
+    Type type;
+
+    bool nullable = true;
+    bool primary_key = false;
+    bool auto_increment = false;
+    bool unique = false;
+
+    std::optional<DefaultValue> def;
+  };
+
+  struct Index
+  {
+    std::string name;
+    std::vector<std::string> columns;
+    bool unique = false;
+  };
+
+  struct Table
+  {
+    std::string name;
+    std::vector<Column> columns;
+    std::vector<Index> indexes;
+
+    const Column *findColumn(const std::string &n) const
+    {
+      for (const auto &c : columns)
+        if (c.name == n)
+          return &c;
+      return nullptr;
+    }
+
+    Column *findColumn(const std::string &n)
+    {
+      for (auto &c : columns)
+        if (c.name == n)
+          return &c;
+      return nullptr;
+    }
+
+    const Index *findIndex(const std::string &n) const
+    {
+      for (const auto &i : indexes)
+        if (i.name == n)
+          return &i;
+      return nullptr;
+    }
+  };
+
+  struct Schema
+  {
+    std::vector<Table> tables;
+
+    const Table *findTable(const std::string &n) const
+    {
+      for (const auto &t : tables)
+        if (t.name == n)
+          return &t;
+      return nullptr;
+    }
+
+    Table *findTable(const std::string &n)
+    {
+      for (auto &t : tables)
+        if (t.name == n)
+          return &t;
+      return nullptr;
+    }
+  };
+
+} // namespace vix::db::schema
+
+#endif

include/vix/db/schema/Types.hpp

@@ -0,0 +1,55 @@
+#ifndef VIX_DB_SCHEMA_TYPES_HPP
+#define VIX_DB_SCHEMA_TYPES_HPP
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace vix::db::schema
+{
+  enum class Dialect
+  {
+    MySQL,
+    SQLite
+  };
+
+  enum class BaseType
+  {
+    Int,
+    BigInt,
+    Double,
+    Bool,
+    VarChar,
+    Text,
+    DateTime
+  };
+
+  struct Type
+  {
+    BaseType base{};
+    std::optional<std::uint32_t> size; // for VARCHAR(n)
+
+    static Type Int() { return {BaseType::Int, std::nullopt}; }
+    static Type BigInt() { return {BaseType::BigInt, std::nullopt}; }
+    static Type Double() { return {BaseType::Double, std::nullopt}; }
+    static Type Bool() { return {BaseType::Bool, std::nullopt}; }
+    static Type Text() { return {BaseType::Text, std::nullopt}; }
+    static Type DateTime() { return {BaseType::DateTime, std::nullopt}; }
+
+    static Type VarChar(std::uint32_t n) { return {BaseType::VarChar, n}; }
+
+    bool operator==(const Type &o) const { return base == o.base && size == o.size; }
+    bool operator!=(const Type &o) const { return !(*this == o); }
+  };
+
+  struct DefaultValue
+  {
+    // Keep as raw SQL literal for MVP ("0", "'text'", "CURRENT_TIMESTAMP")
+    std::string sql_literal;
+  };
+
+} // namespace vix::db::schema
+
+#endif

src/mig/diff/Diff.cpp

@@ -0,0 +1,79 @@
+#include <vix/db/mig/diff/Diff.hpp>
+
+#include <stdexcept>
+#include <unordered_map>
+
+namespace vix::db::mig::diff
+{
+  using vix::db::schema::Schema;
+  using vix::db::schema::Table;
+
+  static std::unordered_map<std::string, const Table *> map_tables(const Schema &s)
+  {
+    std::unordered_map<std::string, const Table *> m;
+    m.reserve(s.tables.size());
+    for (const auto &t : s.tables)
+      m.emplace(t.name, &t);
+    return m;
+  }
+
+  std::vector<Op> diff_or_throw(const Schema &from, const Schema &to)
+  {
+    std::vector<Op> ops;
+
+    auto A = map_tables(from);
+    auto B = map_tables(to);
+
+    // 1) Drop tables missing in 'to'
+    for (const auto &[name, ta] : A)
+    {
+      if (!B.count(name))
+        ops.push_back(DropTable{*ta});
+    }
+
+    // 2) Create tables new in 'to'
+    for (const auto &[name, tb] : B)
+    {
+      if (!A.count(name))
+      {
+        ops.push_back(CreateTable{*tb});
+        continue;
+      }
+
+      // 3) Same table: diff columns + indexes
+      const auto *oldT = A.at(name);
+      const auto *newT = tb;
+
+      // Columns: drops
+      for (const auto &c_old : oldT->columns)
+      {
+        if (!newT->findColumn(c_old.name))
+          ops.push_back(DropColumn{name, c_old});
+      }
+
+      // Columns: adds
+      for (const auto &c_new : newT->columns)
+      {
+        if (!oldT->findColumn(c_new.name))
+          ops.push_back(AddColumn{name, c_new});
+      }
+
+      // Indexes: drops
+      for (const auto &i_old : oldT->indexes)
+      {
+        if (!newT->findIndex(i_old.name))
+          ops.push_back(DropIndex{name, i_old});
+      }
+
+      // Indexes: adds
+      for (const auto &i_new : newT->indexes)
+      {
+        if (!oldT->findIndex(i_new.name))
+          ops.push_back(CreateIndex{name, i_new});
+      }
+    }
+
+    return ops;
+  }
+
+} // namespace vix::db::mig::diff