feat: add sql_default() sentinel, positional and column-specific insert APIs

Introduce sql_default_t/sql_default() for emitting DEFAULT in INSERT
statements. Columns with auto_increment or default_value attributes can
be constructed from or assigned sql_default(). Add two new insert paths:
positional field-based (.values(sql_default(), col{"val"}, ...)) and
column-specific (.columns(col1{}, col2{}).values(v1, v2)). Both support
on_duplicate_key_update. Generalize upsert builder to work with all
insert paths.

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

Author: Pierre-Luc Gagné

CHANGELOG.md

@@ -10,6 +10,10 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- `sql_default()` sentinel and `sql_default_t` type — represents the SQL `DEFAULT` keyword in INSERT statements
+- Positional field-based insert — `insert_into(t{}).values(sql_default(), col2{"val"}, col3{"val"})` allows specifying all struct fields in order with `sql_default()` as a placeholder for columns that should use their database default
+- Column-specific insert — `insert_into(t{}).columns(col1{}, col2{}).values(val1, val2)` allows inserting a subset of columns; column list is instance-based (no template arguments needed)
+- Column field `sql_default()` assignability — columns with `auto_increment` or `default_value` attributes can be constructed from or assigned `sql_default()`: `row.id_ = sql_default()`, then the struct-based `insert_into(t{}).values(row)` emits `DEFAULT` for those columns
 - `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

CLAUDE.md

@@ -49,11 +49,11 @@ Style: Google-based, 120-char line limit, 4-space indent (`.clang-format` at roo
 - `ds_mysql.hpp` — umbrella include; users include only this
 - `mysql_connection.hpp` — `mysql_config`, `connect_options`, and `mysql_connection` classes; `.query()` returns `std::expected<ResultType, std::string>`, `.execute()` returns `std::expected<uint64_t, std::string>` (affected row count; errors include the failing SQL statement); also provides `last_insert_id()`, `ping()`, `commit()`, `rollback()`, `autocommit()`, `select_db()`, `reset_connection()`, `escape_string()`, `warning_count()`, `info()`, `server_version()`, `server_info()`, `stat()`, `thread_id()`, `character_set()`, `set_character_set()`
 - `sql_ddl.hpp` — `create_table(T{})`, `drop_table(T{})`, `create_database(DB{})`, `create_all_tables(DB{})`
-- `sql_dml.hpp` — `insert_into(T{})`, `update(T{})`, `delete_from(T{})`, `truncate_table(T{})`
+- `sql_dml.hpp` — `insert_into(T{})` (struct-based, positional field-based with `sql_default()`, column-specific via `.columns().values()`), `update(T{})`, `delete_from(T{})`, `truncate_table(T{})`
 - `sql_dql.hpp` — `select(col1{}, col2{})`, `count(T{})`, `describe(T{})`
 - `connect_options.hpp` — `connect_options` fluent builder and `ssl_mode` enum for pre-connect `mysql_options()` configuration (timeouts, SSL/TLS, charset, compression, etc.)
 - `charset_name.hpp` — `charset_name` strong type for character set names
-- `column_field.hpp` / `column_field_base_*.hpp` — `column_field<"name", Type, Attrs...>` descriptors, `COLUMN_FIELD(name, type, attrs...)` macro, and column attributes passed as NTTP instances: `column_attr::primary_key{}`, `auto_increment{}`, `unique{}`, `default_value(0)`, `default_value("text")`, `default_value(current_timestamp)`, `on_update(current_timestamp)`, `comment("...")`, `collate("...")`
+- `column_field.hpp` / `column_field_base_*.hpp` — `column_field<"name", Type, Attrs...>` descriptors, `COLUMN_FIELD(name, type, attrs...)` macro, column attributes passed as NTTP instances: `column_attr::primary_key{}`, `auto_increment{}`, `unique{}`, `default_value(0)`, `default_value("text")`, `default_value(current_timestamp)`, `on_update(current_timestamp)`, `comment("...")`, `collate("...")`; `sql_default_t` sentinel and `sql_default()` factory — columns with `auto_increment` or `default_value` support construction/assignment from `sql_default()`
 - `schema_generator.hpp` — derives CREATE TABLE SQL from a C++ struct at compile time using Boost.PFR
 - `sql_varchar.hpp`, `sql_numeric.hpp`, `sql_temporal.hpp` — library-specific SQL types (`varchar_type<N>`, `decimal_type<P,S>`, `datetime_type<FSP>`, etc.)
 - `metadata.hpp` — types for querying `information_schema`

lib/include/ds_mysql/column_field.hpp

@@ -102,7 +102,6 @@ struct attr_type_compat<ColumnType, First, Rest...> {
 template <fixed_string Name, typename T, auto... Attrs>
 struct column_field : column_field_detail::base<T> {
     using column_field_detail::base<T>::base;
-    using column_field_detail::base<T>::operator=;
 
     static constexpr bool ddl_primary_key = (std::is_same_v<decltype(Attrs), column_attr::primary_key> || ...);
     static constexpr bool ddl_auto_increment = (std::is_same_v<decltype(Attrs), column_attr::auto_increment> || ...);
@@ -111,9 +110,47 @@ struct column_field : column_field_detail::base<T> {
     static constexpr bool ddl_has_default = (column_field_detail::is_default_value_attr_v<decltype(Attrs)> || ...);
     static constexpr bool ddl_has_on_update = (column_field_detail::is_on_update_attr_v<decltype(Attrs)> || ...);
 
+    static constexpr bool supports_sql_default = ddl_auto_increment || ddl_has_default;
+
     static_assert(column_field_detail::attr_type_compat<T, Attrs...>::value,
                   "default_value / on_update type must match column value type");
 
+    // --- sql_default support ---------------------------------------------------
+    bool is_sql_default_ = false;
+
+    constexpr column_field(sql_default_t) noexcept
+        requires supports_sql_default
+        : is_sql_default_{true} {
+    }
+
+    constexpr column_field& operator=(sql_default_t) noexcept
+        requires supports_sql_default
+    {
+        is_sql_default_ = true;
+        return *this;
+    }
+
+    // Generic forwarding operator= that resets the sql_default flag.
+    template <typename U>
+    constexpr auto operator=(U&& v) -> column_field&
+        requires(!std::same_as<std::decay_t<U>, sql_default_t> && !std::same_as<std::decay_t<U>, column_field>) &&
+                requires(column_field_detail::base<T>& b) { b = std::forward<U>(std::declval<U>()); }
+    {
+        static_cast<column_field_detail::base<T>&>(*this) = std::forward<U>(v);
+        is_sql_default_ = false;
+        return *this;
+    }
+
+    constexpr column_field() = default;
+    constexpr column_field(column_field const&) = default;
+    constexpr column_field(column_field&&) = default;
+    constexpr column_field& operator=(column_field const&) = default;
+    constexpr column_field& operator=(column_field&&) = default;
+
+    [[nodiscard]] constexpr bool is_sql_default() const noexcept {
+        return is_sql_default_;
+    }
+
     [[nodiscard]] static std::string ddl_default_sql() {
         return column_field_detail::default_value_sql<Attrs...>::get();
     }

lib/include/ds_mysql/column_field_base_core.hpp

@@ -30,6 +30,15 @@ inline constexpr bool is_fixed_string_v = is_fixed_string<T>::value;
 struct current_timestamp_t {};
 inline constexpr current_timestamp_t current_timestamp{};
 
+/// Sentinel type for SQL DEFAULT keyword in INSERT statements.
+/// Use with the field-based insert API or assign to auto_increment / default_value columns:
+///   insert_into(table{}).values(sql_default(), col2{"val"}, ...).build_sql()
+///   table::id field{sql_default()};
+struct sql_default_t {};
+[[nodiscard]] inline constexpr sql_default_t sql_default() noexcept {
+    return {};
+}
+
 namespace column_attr {
 
 struct primary_key {};

lib/include/ds_mysql/sql_core.hpp

@@ -206,7 +206,14 @@ namespace sql_detail {
  */
 template <typename T>
 [[nodiscard]] std::string to_sql_value(T const& v) {
-    if constexpr (ColumnFieldType<T>) {
+    if constexpr (std::same_as<T, sql_default_t>) {
+        return "DEFAULT";
+    } else if constexpr (ColumnFieldType<T>) {
+        if constexpr (requires(T const& x) { x.is_sql_default_; }) {
+            if (v.is_sql_default_) {
+                return "DEFAULT";
+            }
+        }
         return to_sql_value(v.value);
     } else if constexpr (is_optional_v<T>) {
         if (!v.has_value()) {
@@ -267,10 +274,10 @@ template <typename T>
 // ===================================================================
 template <typename T>
 concept SqlValue =
-    ColumnFieldType<T> || is_optional_v<T> || is_datetime_type_v<T> || is_timestamp_type_v<T> || is_date_type_v<T> ||
-    std::same_as<T, std::chrono::system_clock::time_point> || is_time_type_v<T> || std::same_as<T, bool> ||
-    std::integral<T> || std::floating_point<T> || is_formatted_numeric_type_v<T> || is_varchar_type_v<T> ||
-    is_text_type_v<T> || std::same_as<T, std::string>;
+    std::same_as<T, sql_default_t> || ColumnFieldType<T> || is_optional_v<T> || is_datetime_type_v<T> ||
+    is_timestamp_type_v<T> || is_date_type_v<T> || std::same_as<T, std::chrono::system_clock::time_point> ||
+    is_time_type_v<T> || std::same_as<T, bool> || std::integral<T> || std::floating_point<T> ||
+    is_formatted_numeric_type_v<T> || is_varchar_type_v<T> || is_text_type_v<T> || std::same_as<T, std::string>;
 
 // ===================================================================
 // check_id<"name">     — compile-time CHECK constraint name type.

lib/include/ds_mysql/sql_dml.hpp

@@ -12,12 +12,16 @@ namespace ds_mysql {
 //   describe<T>()
 //       → build_sql()                           — DESCRIBE T
 //
-//   insert_into<T>()
+//   insert_into(T{})
 //       .values(row)
 //       → build_sql()                           — INSERT INTO T (...) VALUES (...)
 //       → .on_duplicate_key_update(col1, ...)   — ... ON DUPLICATE KEY UPDATE ...
 //       .values(rows) where rows is std::ranges::input_range<T>
 //       → build_sql()                           — INSERT INTO T (...) VALUES (...), (...), ...
+//       .values(sql_default(), col2{"v"}, ...)  — positional, all fields
+//       → build_sql()                           — INSERT INTO T (...) VALUES (DEFAULT, ...)
+//       .columns(col1{}, col2{}).values(v1, v2) — column-specific, subset
+//       → build_sql()                           — INSERT INTO T (col1, col2) VALUES (...)
 //
 //   update<T>()
 //       .set(col1, col2, ...)                   — all columns in one call
@@ -71,15 +75,15 @@ class insert_into_builder;
 template <typename... Cols>
 [[nodiscard]] std::string build_assignment_sql_from_tuple(std::tuple<Cols...> const& assignments);
 
-template <typename T, typename... Cols>
+template <typename T, typename InnerBuilder, typename... Cols>
 class insert_into_upsert_builder {
 public:
-    insert_into_upsert_builder(insert_into_values_builder<T> values_builder, std::tuple<Cols...> assignments)
-        : values_builder_(std::move(values_builder)), assignments_(std::move(assignments)) {
+    insert_into_upsert_builder(InnerBuilder inner, std::tuple<Cols...> assignments)
+        : inner_(std::move(inner)), assignments_(std::move(assignments)) {
     }
 
     [[nodiscard]] std::string build_sql() const {
-        auto insert_sql = values_builder_.build_sql();
+        auto insert_sql = inner_.build_sql();
         auto update_clause = build_assignment_sql_from_tuple(assignments_);
         std::string sql;
         sql.reserve(insert_sql.size() + 26 + update_clause.size());
@@ -90,7 +94,7 @@ class insert_into_upsert_builder {
     }
 
 private:
-    insert_into_values_builder<T> values_builder_;
+    InnerBuilder inner_;
     std::tuple<Cols...> assignments_;
 };
 
@@ -108,8 +112,9 @@ class insert_into_values_builder {
     // Template form: .on_duplicate_key_update<T::col>("val")  (mirrors update().set<>())
     template <FieldOf<T>... Cols>
         requires(sizeof...(Cols) > 0)
-    [[nodiscard]] insert_into_upsert_builder<T, Cols...> on_duplicate_key_update(Cols const&... assignments) const {
-        return insert_into_upsert_builder<T, Cols...>{*this, std::tuple<Cols...>{assignments...}};
+    [[nodiscard]] insert_into_upsert_builder<T, insert_into_values_builder<T>, Cols...> on_duplicate_key_update(
+        Cols const&... assignments) const {
+        return {*this, std::tuple<Cols...>{assignments...}};
     }
 
     [[nodiscard]] std::string build_sql() const {
@@ -155,13 +160,105 @@ class insert_into_values_builder {
     bool bulk_ = false;
 };
 
+// ---------------------------------------------------------------
+// insert_into_fields_builder — positional field-based insert
+// (all struct fields, in order, each either column_field or sql_default)
+// ---------------------------------------------------------------
+template <typename T, typename... Args>
+class insert_into_fields_builder {
+public:
+    explicit insert_into_fields_builder(std::tuple<Args...> args) : args_(std::move(args)) {
+    }
+
+    template <FieldOf<T>... Cols>
+        requires(sizeof...(Cols) > 0)
+    [[nodiscard]] insert_into_upsert_builder<T, insert_into_fields_builder<T, Args...>, Cols...>
+    on_duplicate_key_update(Cols const&... assignments) const {
+        return {*this, std::tuple<Cols...>{assignments...}};
+    }
+
+    [[nodiscard]] std::string build_sql() const {
+        const auto table_name = table_name_for<T>::value().to_string_view();
+        const auto& column_list = dml_detail::generate_column_list<T>();
+        auto values = dml_detail::generate_field_values_impl(args_, std::make_index_sequence<sizeof...(Args)>{});
+        std::string s;
+        s.reserve(12 + table_name.size() + 2 + column_list.size() + 10 + values.size() + 1);
+        s += "INSERT INTO ";
+        s += table_name;
+        s += " (";
+        s += column_list;
+        s += ") VALUES (";
+        s += values;
+        s += ')';
+        return s;
+    }
+
+private:
+    std::tuple<Args...> args_;
+};
+
+// ---------------------------------------------------------------
+// insert_into_column_values_builder — column-specific insert
+// (subset of columns, raw values wrapped into column fields)
+// ---------------------------------------------------------------
+template <typename T, typename StoredTuple, typename... Cols>
+class insert_into_column_values_builder {
+public:
+    explicit insert_into_column_values_builder(StoredTuple stored) : stored_(std::move(stored)) {
+    }
+
+    template <FieldOf<T>... UpdateCols>
+        requires(sizeof...(UpdateCols) > 0)
+    [[nodiscard]] insert_into_upsert_builder<T, insert_into_column_values_builder, UpdateCols...>
+    on_duplicate_key_update(UpdateCols const&... assignments) const {
+        return {*this, std::tuple<UpdateCols...>{assignments...}};
+    }
+
+    [[nodiscard]] std::string build_sql() const {
+        const auto table_name = table_name_for<T>::value().to_string_view();
+        auto column_list = dml_detail::generate_column_names<Cols...>();
+        auto values = dml_detail::generate_field_values_impl(stored_, std::make_index_sequence<sizeof...(Cols)>{});
+        std::string s;
+        s.reserve(12 + table_name.size() + 2 + column_list.size() + 10 + values.size() + 1);
+        s += "INSERT INTO ";
+        s += table_name;
+        s += " (";
+        s += column_list;
+        s += ") VALUES (";
+        s += values;
+        s += ')';
+        return s;
+    }
+
+private:
+    StoredTuple stored_;
+};
+
+template <typename T, typename... Cols>
+class insert_into_columns_builder {
+public:
+    template <typename... Vals>
+        requires(sizeof...(Vals) == sizeof...(Cols) &&
+                 dml_detail::valid_column_values_impl<std::tuple<Cols...>, Vals...>(
+                     std::make_index_sequence<sizeof...(Cols)>{}))
+    [[nodiscard]] auto values(Vals const&... vals) const {
+        auto stored = std::tuple{dml_detail::make_insert_value<Cols>(vals)...};
+        return insert_into_column_values_builder<T, decltype(stored), Cols...>{std::move(stored)};
+    }
+};
+
+// ---------------------------------------------------------------
+// insert_into_builder
+// ---------------------------------------------------------------
 template <typename T>
 class insert_into_builder {
 public:
+    // Struct-based insert: .values(row)
     [[nodiscard]] insert_into_values_builder<T> values(T const& row) const {
         return insert_into_values_builder<T>{row};
     }
 
+    // Bulk insert: .values(range_of_rows)
     template <std::ranges::input_range Rows>
         requires std::same_as<std::remove_cvref_t<std::ranges::range_value_t<Rows>>, T>
     [[nodiscard]] insert_into_values_builder<T> values(Rows&& rows) const {
@@ -174,6 +271,23 @@ class insert_into_builder {
         }
         return {std::move(collected_rows), /*bulk=*/true};
     }
+
+    // Positional field-based insert: .values(sql_default(), col2{"val"}, ...)
+    // All struct fields must be provided in order. Each is either sql_default()
+    // or the matching column field type at that position.
+    template <typename... Args>
+        requires ValidFieldArgs<T, std::decay_t<Args>...>
+    [[nodiscard]] insert_into_fields_builder<T, std::decay_t<Args>...> values(Args const&... args) const {
+        return insert_into_fields_builder<T, std::decay_t<Args>...>{std::tuple<std::decay_t<Args>...>{args...}};
+    }
+
+    // Column-specific insert: .columns(col1{}, col2{}).values(val1, val2)
+    // Specify a subset of columns; values are provided in a subsequent .values() call.
+    template <FieldOf<T>... Cols>
+        requires(sizeof...(Cols) > 0)
+    [[nodiscard]] insert_into_columns_builder<T, Cols...> columns(Cols const&...) const {
+        return {};
+    }
 };
 
 // ---------------------------------------------------------------
@@ -410,9 +524,16 @@ template <ValidTable T>
  * Bulk insert (multiple rows in one statement):
  *   insert_into(symbol{}).values(rows).build_sql()   // rows is std::ranges::input_range<T>
  *
+ * Positional field-based insert (all fields, sql_default() for auto-increment):
+ *   insert_into(symbol{}).values(sql_default(), symbol::ticker{"AAPL"}, symbol::instrument{"Stock"}).build_sql()
+ *   // → INSERT INTO symbol (id, ticker, instrument) VALUES (DEFAULT, 'AAPL', 'Stock')
+ *
+ * Column-specific insert (subset of columns):
+ *   insert_into(symbol{}).columns(symbol::ticker{}, symbol::instrument{}).values("AAPL", "Stock").build_sql()
+ *   // → INSERT INTO symbol (ticker, instrument) VALUES ('AAPL', 'Stock')
+ *
  * Upsert (INSERT … ON DUPLICATE KEY UPDATE):
  *   insert_into(symbol{}).values(row).on_duplicate_key_update(symbol::ticker{"AAPL"}, ...)
- *   insert_into(symbol{}).values(row).on_duplicate_key_update<symbol::ticker>("AAPL")  // template form
  *
  * Example:
  *   symbol row;