db(core,pool,sqlite,examples): stabilize public API, make pool/tx movable, add SQLite skeleton and examples

- Simplify Statement::bind public API (int-safe overloads)
- Make PooledConn movable to support Transaction move semantics
- Harden ConnectionPool lifecycle (RAII-safe release)
- Prepare SQLite driver structure (headers + src)
- Extend Database config handling for multiple engines
- Add examples/ with prepared queries and migrations usage
- Keep design explicit, SQL-first, anti-ORM by construction

Author: GaspardKirira

CMakeLists.txt

@@ -34,6 +34,7 @@ option(VIX_DB_REQUIRE_POSTGRES  "Fail if Postgres requested but not found"   OFF
 # Redis is not SQL, but useful for caching / sessions / queue (future)
 option(VIX_DB_USE_REDIS         "Enable Redis client (future)"               OFF)
 option(VIX_DB_REQUIRE_REDIS     "Fail if Redis requested but not found"      OFF)
+option(VIX_BUILD_EXAMPLES       "Build examples for Vix modules" OFF)
 
 # ------------------------------------------------------------------------------
 # Language / PIC
@@ -364,6 +365,13 @@ if (VIX_DB_HAS_REDIS)
   endif()
 endif()
 
+# ------------------------------------------------------------------------------
+# Examples
+# ------------------------------------------------------------------------------
+if (VIX_DB_BUILD_EXAMPLES)
+  add_subdirectory(examples)
+endif()
+
 # ------------------------------------------------------------------------------
 # Install / export via umbrella export-set "VixTargets"
 # ------------------------------------------------------------------------------

examples/CMakeLists.txt

@@ -0,0 +1,17 @@
+option(VIX_DB_BUILD_EXAMPLES "Build Vix DB examples" OFF)
+
+if (VIX_DB_BUILD_EXAMPLES)
+  function(vix_db_example name)
+    add_executable(vix_db_example_${name} ${name}.cpp)
+    target_link_libraries(vix_db_example_${name}
+      PRIVATE
+        vix::db
+    )
+    target_compile_features(vix_db_example_${name} PRIVATE cxx_std_20)
+  endfunction()
+
+  vix_db_example(basic_connect)
+  vix_db_example(prepared_query)
+  vix_db_example(transaction)
+  vix_db_example(migrations)
+endif()

examples/README.md

@@ -0,0 +1,26 @@
+#include <vix/db/db.hpp>
+#include <iostream>
+
+using namespace vix::db;
+
+int main()
+{
+  DbConfig cfg;
+  cfg.engine = Engine::MySQL;
+  cfg.mysql.host = "tcp://127.0.0.1:3306";
+  cfg.mysql.user = "root";
+  cfg.mysql.password = "";
+  cfg.mysql.database = "vixdb";
+
+  Database db(cfg);
+
+  auto conn = db.pool().acquire();
+  if (!conn->ping())
+  {
+    std::cerr << "DB ping failed\n";
+    return 1;
+  }
+
+  std::cout << "DB connected successfully\n";
+  return 0;
+}

examples/basic_connect.cpp

@@ -0,0 +1,100 @@
+#include <vix/db/db.hpp>
+
+#include <iostream>
+#include <filesystem>
+#include <string>
+
+using namespace vix::db;
+
+static DbConfig make_mysql_cfg()
+{
+  DbConfig cfg;
+  cfg.engine = Engine::MySQL;
+  cfg.mysql.host = "tcp://127.0.0.1:3306";
+  cfg.mysql.user = "root";
+  cfg.mysql.password = "";
+  cfg.mysql.database = "vixdb";
+  cfg.mysql.pool.min = 1;
+  cfg.mysql.pool.max = 4;
+  return cfg;
+}
+
+// ------------------------------
+// 1) Code-based migration example
+// ------------------------------
+class CreateUsersTable final : public Migration
+{
+public:
+  std::string id() const override { return "2026-01-22-create-users"; }
+
+  void up(Connection &c) override
+  {
+    auto st = c.prepare(
+        "CREATE TABLE IF NOT EXISTS users ("
+        "  id BIGINT PRIMARY KEY AUTO_INCREMENT,"
+        "  name VARCHAR(255) NOT NULL,"
+        "  age INT NOT NULL"
+        ");");
+    st->exec();
+  }
+
+  void down(Connection &c) override
+  {
+    auto st = c.prepare("DROP TABLE IF EXISTS users;");
+    st->exec();
+  }
+};
+
+static void run_code_migrations(Database &db)
+{
+  std::cout << "[migrations] running code migrations...\n";
+
+  Transaction tx(db.pool());
+
+  CreateUsersTable m1;
+  MigrationsRunner runner(tx.conn());
+  runner.add(&m1);
+  runner.runAll();
+
+  tx.commit();
+  std::cout << "[migrations] done (code)\n";
+}
+
+// ------------------------------
+// 2) File-based migration example
+// ------------------------------
+static void run_file_migrations(Database &db, std::filesystem::path dir)
+{
+  std::cout << "[migrations] running file migrations from: " << dir.string() << "\n";
+
+  Transaction tx(db.pool());
+
+  FileMigrationsRunner runner(tx.conn(), std::move(dir));
+  runner.setTable("schema_migrations"); // optional (default already)
+  runner.applyAll();
+
+  tx.commit();
+  std::cout << "[migrations] done (files)\n";
+}
+
+int main()
+{
+  try
+  {
+    Database db(make_mysql_cfg());
+
+    // 1) Code migrations
+    run_code_migrations(db);
+
+    // 2) File migrations (expects ./migrations/*.up.sql and *.down.sql)
+    run_file_migrations(db, std::filesystem::path{"migrations"});
+
+    std::cout << "OK\n";
+    return 0;
+  }
+  catch (const std::exception &e)
+  {
+    std::cerr << "ERROR: " << e.what() << "\n";
+    return 1;
+  }
+}

examples/migrations.cpp

@@ -0,0 +1,32 @@
+#include <vix/db/db.hpp>
+#include <iostream>
+
+using namespace vix::db;
+
+int main()
+{
+  DbConfig cfg;
+  cfg.engine = Engine::MySQL;
+  cfg.mysql.host = "tcp://127.0.0.1:3306";
+  cfg.mysql.user = "root";
+  cfg.mysql.password = "";
+  cfg.mysql.database = "vixdb";
+  cfg.mysql.pool.min = 1;
+  cfg.mysql.pool.max = 8;
+
+  Database db(cfg);
+
+  auto conn = db.pool().acquire();
+  auto st = conn->prepare("SELECT id, name FROM users WHERE age > ?");
+
+  st->bind(1, 18);
+  // or: st->bind(1, std::int64_t{18});
+  // or: st->bind(1, i64(18));
+
+  auto rs = st->query();
+  while (rs->next())
+  {
+    const auto &row = rs->row();
+    std::cout << row.getInt64(0) << " " << row.getString(1) << "\n";
+  }
+}

examples/prepared_query.cpp

@@ -0,0 +1,66 @@
+#include <vix/db/db.hpp>
+#include <iostream>
+
+int main()
+{
+  vix::db::DbConfig cfg;
+  cfg.engine = vix::db::Engine::MySQL;
+  cfg.mysql.host = "tcp://127.0.0.1:3306";
+  cfg.mysql.user = "root";
+  cfg.mysql.password = "";
+  cfg.mysql.database = "vixdb";
+  cfg.mysql.pool.min = 1;
+  cfg.mysql.pool.max = 8;
+
+  vix::db::Database db(cfg);
+
+  try
+  {
+    // 2) Transaction RAII
+    vix::db::Transaction tx(db.pool());
+
+    // Create table (demo)
+    tx.conn().prepare(
+                 "CREATE TABLE IF NOT EXISTS users ("
+                 "  id BIGINT PRIMARY KEY AUTO_INCREMENT,"
+                 "  name VARCHAR(255) NOT NULL,"
+                 "  age INT NOT NULL"
+                 ")")
+        ->exec();
+
+    // Insert 1 row
+    {
+      auto st = tx.conn().prepare("INSERT INTO users (name, age) VALUES (?, ?)");
+      st->bind(1, std::string("Alice"));
+      st->bind(2, static_cast<std::int64_t>(20)); // int -> i64
+      st->exec();
+    }
+
+    // Query
+    {
+      auto st = tx.conn().prepare("SELECT id, name, age FROM users WHERE age >= ?");
+      st->bind(1, static_cast<std::int64_t>(18));
+      auto rs = st->query();
+
+      while (rs->next())
+      {
+        const auto &row = rs->row();
+        std::cout
+            << row.getInt64(0) << " "
+            << row.getString(1) << " "
+            << row.getInt64(2) << "\n";
+      }
+    }
+
+    // 3) Commit
+    tx.commit();
+    std::cout << "Committed.\n";
+  }
+  catch (const std::exception &e)
+  {
+    std::cerr << "DB error: " << e.what() << "\n";
+    return 1;
+  }
+
+  return 0;
+}

examples/transaction.cpp

@@ -31,17 +31,17 @@ namespace vix::db
 
   struct MySQLConfig
   {
-    std::string host;     // ex: "tcp://127.0.0.1:3306"
-    std::string user;     // ex: "root"
-    std::string password; // ex: ""
-    std::string database; // ex: "vixdb"
-    PoolConfig pool{};    // min/max connections
+    std::string host;
+    std::string user;
+    std::string password;
+    std::string database;
+    PoolConfig pool{};
   };
 
   struct SQLiteConfig
   {
-    std::string path;  // ex: "vix_orm.db"
-    PoolConfig pool{}; // reuse PoolConfig
+    std::string path;
+    PoolConfig pool{};
   };
 
   struct DbConfig
@@ -51,24 +51,23 @@ namespace vix::db
     SQLiteConfig sqlite{};
   };
 
-  ConnectionFactory make_mysql_factory(const MySQLConfig &cfg);
-
   DbConfig make_db_config_from_vix_config(const vix::config::Config &cfg);
 
   class Database
   {
   public:
     explicit Database(const DbConfig &cfg);
+
     Engine engine() const noexcept { return cfg_.engine; }
     const DbConfig &config() const noexcept { return cfg_; }
+
     ConnectionPool &pool() noexcept { return pool_; }
     const ConnectionPool &pool() const noexcept { return pool_; }
 
   private:
     DbConfig cfg_;
     ConnectionPool pool_;
   };
-
 } // namespace vix::db
 
-#endif // VIX_DB_DATABASE_HPP
+#endif

include/vix/db/Database.hpp

@@ -29,18 +29,30 @@ namespace vix::db
       pooled_.get().begin();
     }
 
-    ~Transaction()
+    ~Transaction() noexcept
     {
-      if (active_)
-        try
-        {
-          pooled_.get().rollback();
-        }
-        catch (...)
-        {
-        }
+      if (!active_)
+        return;
+      try
+      {
+        pooled_.get().rollback();
+      }
+      catch (...)
+      {
+      }
     }
 
+    Transaction(const Transaction &) = delete;
+    Transaction &operator=(const Transaction &) = delete;
+
+    Transaction(Transaction &&other) noexcept
+        : pooled_(std::move(other.pooled_)), active_(other.active_)
+    {
+      other.active_ = false;
+    }
+
+    Transaction &operator=(Transaction &&) = delete;
+
     void commit()
     {
       pooled_.get().commit();
@@ -55,6 +67,7 @@ namespace vix::db
 
     Connection &conn() { return pooled_.get(); }
   };
+
 } // namespace vix::db
 
 #endif // VIX_DB_TRANSACTION_HPP

include/vix/db/Transaction.hpp

@@ -28,12 +28,18 @@ namespace vix::db
   {
     virtual ~Statement() = default;
     virtual void bind(std::size_t idx, const DbValue &v) = 0;
+
+    void bind(std::size_t idx, int v) { bind(idx, static_cast<std::int64_t>(v)); }
+    void bind(std::size_t idx, unsigned v) { bind(idx, static_cast<std::int64_t>(v)); }
     void bind(std::size_t idx, std::int64_t v) { bind(idx, i64(v)); }
+    void bind(std::size_t idx, std::uint64_t v) { bind(idx, static_cast<std::int64_t>(v)); }
     void bind(std::size_t idx, double v) { bind(idx, f64(v)); }
     void bind(std::size_t idx, bool v) { bind(idx, b(v)); }
     void bind(std::size_t idx, std::string v) { bind(idx, str(std::move(v))); }
-    void bind(std::size_t idx, std::string_view v) { bind(idx, std::string(v)); }
+    void bind(std::size_t idx, const char *v) { bind(idx, str(std::string(v ? v : ""))); }
+
     void bindNull(std::size_t idx) { bind(idx, null()); }
+
     virtual std::unique_ptr<ResultSet> query() = 0;
     virtual std::uint64_t exec() = 0;
   };