feat: add prepared statements, transaction guard, CTE fluent API; remove col<T,I>

Add prepared_statement class wrapping MYSQL_STMT* with type-safe parameter
binding (execute/query), transaction_guard RAII helper with auto-rollback,
and a new CTE fluent API: with(cte(...)).select(...).from(cte_ref{...}).

Remove col<T,I> and col_of (col.hpp deleted), replace ColumnDescriptor
with ColumnFieldType everywhere, inline column_traits calls. Extract
predicates from sql_core.hpp into sql_predicates.hpp.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Pierre-Luc Gagné

CHANGELOG.md

@@ -8,6 +8,26 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- `prepared_statement` — RAII wrapper for MySQL prepared statements (`MYSQL_STMT*`); created via `mysql_connection::prepare(sql)` or `prepare(builder)`; supports type-safe parameter binding via `execute(params...)` and typed result fetching via `query<RowType>(params...)`
+- `transaction_guard` — RAII scoped transaction helper; `transaction_guard::begin(conn)` disables autocommit, destructor auto-rolls-back unless `commit()` is called; also provides explicit `rollback()`
+- CTE fluent API — `with(cte("name", query)).select(...).from(cte_ref{"name"})` and `with(recursive(cte("name", sql))).select(...)` replace the old `with_cte()`/`with_recursive_cte()` builders
+- `sql_predicates.hpp` — predicates, operators, and `col_expr`/`col_ref` extracted from `sql_core.hpp` into their own header for readability
+
+### Changed
+
+- `ColumnDescriptor` concept replaced by `ColumnFieldType` everywhere — the dual-concept system is removed
+- `column_traits<T>` removed — callers now use `T::column_name()` and `T::value_type` directly
+- `qual<Col>` now derives the table name from the tag type via compile-time reflection, replacing the old `col<T,I>` approach
+- `sql_core.hpp` reduced from ~1 035 to ~340 lines via the predicate extraction
+
+### Removed
+
+- `col<Table, Index>` (`col.hpp`) — index-based column descriptor removed; use `tagged_column_field` (or `COLUMN_FIELD` macro) instead
+- `col_of<&T::field>` — member-pointer column alias removed alongside `col<T,I>`
+- `cte_builder`, `with_cte()`, `with_recursive_cte()` — replaced by the new `with(cte(...))` fluent API
+
 ---
 
 ## [4.6.3] – 2026-03-30

README.md

@@ -252,6 +252,56 @@ auto cnt = db.query(count(product{}).where(equal<product::price>(9.99)));
 auto cols = db.query(describe(product{}));
 ```
 
+### CTEs (Common Table Expressions)
+
+```cpp
+// Non-recursive CTE
+auto sql = with(cte("active", select(product::id{}).from(product{}).where(equal<product::price>(9.99))))
+    .select(count_all{})
+    .from(cte_ref{"active"})
+    .build_sql();
+// → WITH active AS (SELECT id FROM product WHERE price = 9.99) SELECT COUNT(*) FROM active
+
+// Multiple CTEs
+auto c1 = cte("expensive", select(product::id{}).from(product{}).where(greater_than<product::price>(100.0)));
+auto c2 = cte("cheap",     select(product::id{}).from(product{}).where(less_than<product::price>(10.0)));
+auto sql = with(c1, c2).select(count_all{}).from(cte_ref{"expensive"}).build_sql();
+
+// Recursive CTE
+auto sql = with(recursive(cte("nums", "SELECT 1 AS n UNION ALL SELECT n+1 FROM nums WHERE n < 10")))
+    .select(count_all{})
+    .from(cte_ref{"nums"})
+    .build_sql();
+// → WITH RECURSIVE nums AS (...) SELECT COUNT(*) FROM nums
+```
+
+### Prepared Statements
+
+```cpp
+// Prepare once, execute many times with different parameters
+auto stmt = db.prepare("SELECT id, code FROM trade WHERE type = ?").value();
+auto stocks = stmt.query<std::tuple<uint32_t, std::string>>(std::string{"Stock"}).value();
+auto bonds  = stmt.query<std::tuple<uint32_t, std::string>>(std::string{"Bond"}).value();
+
+// DML with prepared statements
+auto ins = db.prepare("INSERT INTO trade (code, type) VALUES (?, ?)").value();
+auto affected = ins.execute(std::string{"AAPL"}, std::string{"Stock"}).value();
+auto id = ins.last_insert_id();
+```
+
+### Transaction Guard
+
+```cpp
+// RAII scoped transaction — auto-rollback on destruction if not committed
+{
+    auto guard = transaction_guard::begin(db).value();
+    db.execute(insert_into(product{}).values(row));
+    db.execute(update(product{}).set(product::price{12.99}).where(equal<product::id>(1u)));
+    guard.commit().value();  // explicit commit
+}
+// If commit() is never called, the destructor rolls back automatically.
+```
+
 ### Schema Validation
 
 ```cpp

lib/include/ds_mysql/col.hpp

@@ -108,14 +108,10 @@ struct unwrap_column_field<T> {
 template <typename T>
 using unwrap_column_field_t = typename unwrap_column_field<T>::type;
 
-}  // namespace ds_mysql
-
 // ===================================================================
 // tagged_column_field — tag-struct based column descriptor
 // ===================================================================
 
-namespace ds_mysql {
-
 /**
  * tagged_column_field<Tag, T> — tag-struct based column descriptor.
  *

lib/include/ds_mysql/column_field.hpp

@@ -15,6 +15,7 @@
 
 #include "ds_mysql/metadata.hpp"
 #include "ds_mysql/mysql_connection.hpp"
+#include "ds_mysql/prepared_statement.hpp"
 #include "ds_mysql/sql_dcl.hpp"
 #include "ds_mysql/sql_ddl.hpp"
 #include "ds_mysql/sql_dml.hpp"

lib/include/ds_mysql/ds_mysql.hpp

@@ -19,6 +19,7 @@
 #include "ds_mysql/database_name.hpp"
 #include "ds_mysql/host_name.hpp"
 #include "ds_mysql/port_number.hpp"
+#include "ds_mysql/prepared_statement.hpp"
 #include "ds_mysql/sql_ddl.hpp"
 #include "ds_mysql/sql_dml.hpp"
 #include "ds_mysql/sql_dql.hpp"
@@ -392,6 +393,28 @@ class mysql_connection {
         return out;
     }
 
+    // ---------------------------------------------------------------
+    // Prepared statements
+    // ---------------------------------------------------------------
+
+    // Prepare a SQL string for repeated execution with bound parameters.
+    [[nodiscard]] std::expected<prepared_statement, std::string> prepare(std::string_view sql) const {
+        auto stmt = std::unique_ptr<MYSQL_STMT, prepared_statement::stmt_deleter>(mysql_stmt_init(connection_.get()));
+        if (!stmt) {
+            return std::unexpected(last_error());
+        }
+        if (mysql_stmt_prepare(stmt.get(), sql.data(), static_cast<unsigned long>(sql.size())) != 0) {
+            return std::unexpected(std::string(mysql_stmt_error(stmt.get())));
+        }
+        return prepared_statement{std::move(stmt)};
+    }
+
+    // Prepare a typed query builder for repeated execution.
+    template <SqlBuilder Stmt>
+    [[nodiscard]] std::expected<prepared_statement, std::string> prepare(Stmt const& stmt) const {
+        return prepare(stmt.build_sql());
+    }
+
     // Validate that the C++ table struct T matches the live schema in the database.
     //
     // Runs DESCRIBE <table> and checks:
@@ -598,4 +621,97 @@ class mysql_connection {
     std::unique_ptr<MYSQL, decltype(&mysql_close)> connection_;
 };
 
+// ===================================================================
+// transaction_guard — RAII scoped transaction helper.
+//
+// This is a C++ resource-management utility, not a MySQL semantic.
+// Disables autocommit on construction and automatically rolls back on
+// destruction unless commit() has been called.  Move-only.
+//
+//   {
+//       auto guard = transaction_guard::begin(conn);
+//       if (!guard) { /* handle error */ }
+//       conn.execute(insert_into(t{}).values(row));
+//       auto result = guard->commit();
+//       if (!result) { /* handle commit error */ }
+//   }
+//   // If commit() was never called, destructor rolls back.
+// ===================================================================
+
+class transaction_guard {
+public:
+    transaction_guard(transaction_guard const&) = delete;
+    transaction_guard& operator=(transaction_guard const&) = delete;
+
+    transaction_guard(transaction_guard&& other) noexcept : conn_(other.conn_), committed_(other.committed_) {
+        other.conn_ = nullptr;
+    }
+
+    transaction_guard& operator=(transaction_guard&& other) noexcept {
+        if (this != &other) {
+            if (conn_ && !committed_) {
+                (void)conn_->rollback();
+            }
+            conn_ = other.conn_;
+            committed_ = other.committed_;
+            other.conn_ = nullptr;
+        }
+        return *this;
+    }
+
+    ~transaction_guard() {
+        if (conn_ && !committed_) {
+            (void)conn_->rollback();
+        }
+    }
+
+    // Factory: begin a transaction by disabling autocommit.
+    [[nodiscard]] static std::expected<transaction_guard, std::string> begin(mysql_connection const& conn) {
+        auto result = conn.autocommit(false);
+        if (!result) {
+            return std::unexpected(result.error());
+        }
+        return transaction_guard{&conn};
+    }
+
+    // Commit the transaction and re-enable autocommit.
+    [[nodiscard]] std::expected<void, std::string> commit() {
+        if (!conn_) {
+            return std::unexpected("transaction_guard: no active connection");
+        }
+        auto result = conn_->commit();
+        if (!result) {
+            return std::unexpected(result.error());
+        }
+        committed_ = true;
+        // Re-enable autocommit so the connection returns to its default state.
+        return conn_->autocommit(true);
+    }
+
+    // Explicitly roll back the transaction and re-enable autocommit.
+    [[nodiscard]] std::expected<void, std::string> rollback() {
+        if (!conn_) {
+            return std::unexpected("transaction_guard: no active connection");
+        }
+        auto result = conn_->rollback();
+        if (!result) {
+            return std::unexpected(result.error());
+        }
+        committed_ = true;  // prevent double-rollback in destructor
+        return conn_->autocommit(true);
+    }
+
+    // Check whether commit() has been called.
+    [[nodiscard]] bool is_committed() const noexcept {
+        return committed_;
+    }
+
+private:
+    explicit transaction_guard(mysql_connection const* conn) : conn_(conn) {
+    }
+
+    mysql_connection const* conn_ = nullptr;
+    bool committed_ = false;
+};
+
 }  // namespace ds_mysql