refactor!: unify SqlBuilder concept and type-safe DDL builder chaining

Replace three identical concepts (BuildsSql, AnySelectQuery, SqlStatement)
with a single SqlBuilder concept in sql_core.hpp. DDL builders now use a
typed Prior template parameter instead of std::string prior_sql_, making
raw-string construction impossible at the type level.

- Add no_prior sentinel and sql_string_builder bridge types for DDL chains
- Template ddl_continuation<Prior> and all DDL builders on SqlBuilder Prior
- Template union_query on Left/Right builders instead of storing pre-built SQL
- Template case_when_expr on Builder instead of storing pre-built SQL
- lateral_join methods now take SqlBuilder subquery + sql_alias (was string)
- Rename column_alias to sql_alias (it's used for table aliases too)
- TypedSelectQuery now refines SqlBuilder
- explain/explain_analyze use SqlBuilder constraint

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

Author: Pierre-Luc Gagné

CHANGELOG.md

@@ -51,7 +51,9 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `grant<privilege::select, ...>(grant_target, grant_user)` — compile-time privilege set overload of `grant`
 - `revoke(privilege_list, grant_target, grant_user)` — `REVOKE ... ON ... FROM ...`
 - `revoke<privilege::select, ...>(grant_target, grant_user)` — compile-time privilege set overload of `revoke`
-- `column_alias` — strongly-typed SQL alias identifier (wraps `std::string_view`); required as the second argument to `.with_alias()` in place of a plain `std::string`
+- `SqlBuilder` concept — unified concept for any type that can produce SQL via `build_sql() const → std::string`; replaces the previous `BuildsSql`, `AnySelectQuery`, and `SqlStatement` concepts which were structurally identical
+- `sql_alias` — strongly-typed SQL alias identifier (wraps `std::string_view`); used as the alias argument to `.with_alias()`, `.lateral_join()`, etc.
+- `no_prior` / `sql_string_builder` — DDL-internal sentinel and bridge types for the typed prior chain
 
 ### Changed
 
@@ -70,7 +72,7 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   | `.order_by<Col, sort_order::desc>()` | `.order_by(desc(Col{}))` |
   | `.order_by_alias<Proj>()` | `.order_by_alias(Proj{})` |
   | `.order_by_alias<Proj, sort_order::desc>()` | `.order_by_alias(desc(Proj{}))` |
-  | `.with_alias<Proj>("name")` | `.with_alias(Proj{}, column_alias{"name"})` |
+  | `.with_alias<Proj>("name")` | `.with_alias(Proj{}, sql_alias{"name"})` |
   | `.inner_join<T, L, R>()` | `.inner_join(T{}, L{}, R{})` |
   | `.inner_join_on<T>(pred)` | `.inner_join(T{}, pred)` |
   | `.left_join<T, L, R>()` | `.left_join(T{}, L{}, R{})` |
@@ -106,7 +108,15 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Simple column-ref predicate factories (`equal`, `greater_than`, `like`, `between`, `in`, etc.) now return `check_expr` instead of `sql_predicate`; `check_expr` implicitly converts to `sql_predicate` so existing WHERE/HAVING/JOIN ON usage is unaffected
 - Subquery predicate factories (`in_subquery`, `not_in_subquery`, `exists`, `not_exists`) and `match_against` return `sql_predicate` directly (not check-safe)
 
-- **Breaking:** `.with_alias()` now requires a `column_alias` value as its second argument instead of a plain `std::string`; replace `.with_alias(Proj{}, "name")` with `.with_alias(Proj{}, column_alias{"name"})`
+- **Breaking:** `column_alias` renamed to `sql_alias`; replace `sql_alias{"name"}` with `sql_alias{"name"}`
+- **Breaking:** `.with_alias()` now requires a `sql_alias` value as its second argument instead of a plain `std::string`; replace `.with_alias(Proj{}, "name")` with `.with_alias(Proj{}, sql_alias{"name"})`
+- **Breaking:** DDL builders now use a typed `Prior` template parameter instead of `std::string prior_sql_`; builder constructors no longer accept raw strings — chaining is enforced at the type level via `ddl_continuation<Prior>`
+- **Breaking:** `lateral_join` / `left_lateral_join` / `lateral_join_on` / `left_lateral_join_on` now take a `SqlBuilder`-constrained subquery and `sql_alias` instead of `std::string` and `std::string_view`; replace `.lateral_join(q.build_sql(), "alias")` with `.lateral_join(q, sql_alias{"alias"})`
+- **Breaking:** `union_query` now stores the two query builders instead of a pre-built SQL string; `union_()`, `union_all()`, `intersect_()`, `except_()` return deduced types
+- **Breaking:** `case_when_expr` now stores the builder instead of a pre-built SQL string
+- **Breaking:** `AnySelectQuery` and `SqlStatement` concepts removed; use `SqlBuilder` instead
+- `TypedSelectQuery` now refines `SqlBuilder`: `SqlBuilder<T> && requires { typename T::result_row_type; }`
+- `explain()` and `explain_analyze()` now use `SqlBuilder` concept constraint instead of inline requires clause
 - **Breaking:** `grant` and `revoke` now require strongly-typed `privilege_list`, `grant_target`, and `grant_user` arguments instead of plain strings; the old string-based overloads have been removed
 
 - `natural_join<T>()`, `natural_left_join<T>()`, `natural_right_join<T>()` — `NATURAL [LEFT|RIGHT] JOIN` with no ON/USING clause

lib/include/ds_mysql/schema_generator.hpp

@@ -485,7 +485,8 @@ template <typename T, std::size_t... Is>
     sql += table_name;
     sql += " (\n";
     for (std::size_t i = 0; i < sizeof...(Is); ++i) {
-        if (i > 0) sql += ",\n";
+        if (i > 0)
+            sql += ",\n";
         sql += col_defs[i];
     }
     sql += "\n)";

lib/include/ds_mysql/sql_core.hpp

@@ -161,7 +161,8 @@ namespace sql_detail {
     return result;
 }
 
-[[nodiscard]] inline std::string format_datetime(std::chrono::system_clock::time_point tp, uint32_t fractional_second_precision = 0) {
+[[nodiscard]] inline std::string format_datetime(std::chrono::system_clock::time_point tp,
+                                                 uint32_t fractional_second_precision = 0) {
     auto const precision = normalize_fractional_second_precision(fractional_second_precision);
     auto const micros = std::chrono::floor<std::chrono::microseconds>(tp);
     auto const secs = std::chrono::floor<std::chrono::seconds>(micros);
@@ -550,12 +551,11 @@ template <ColumnFieldType Col>
     return or_(std::move(a), std::move(b));
 }
 
-// Concept for any query that can produce SQL — used for subquery predicates.
-// Forward-declared here so subquery predicates can reference it before the full
-// SELECT builder is defined.
-template <typename Q>
-concept AnySelectQuery = requires(Q const& q) {
-    { q.build_sql() } -> std::convertible_to<std::string>;
+// SqlBuilder — any type that can produce a SQL string via build_sql().
+// Defined early so subquery predicates can reference it before the full SELECT builder is defined.
+template <typename T>
+concept SqlBuilder = requires(T const& t) {
+    { t.build_sql() } -> std::convertible_to<std::string>;
 };
 
 // check-safe: literal value list
@@ -715,7 +715,7 @@ template <ColumnFieldType... Cols>
     return {{}, {}, std::move(s)};
 }
 
-template <ColumnFieldType Col, AnySelectQuery Query>
+template <ColumnFieldType Col, SqlBuilder Query>
 [[nodiscard]] sql_predicate in_subquery(Query const& subquery) {
     auto sub = subquery.build_sql();
     std::string rhs;
@@ -726,7 +726,7 @@ template <ColumnFieldType Col, AnySelectQuery Query>
     return {column_traits<Col>::column_name(), " IN ", std::move(rhs)};
 }
 
-template <ColumnFieldType Col, AnySelectQuery Query>
+template <ColumnFieldType Col, SqlBuilder Query>
 [[nodiscard]] sql_predicate not_in_subquery(Query const& subquery) {
     auto sub = subquery.build_sql();
     std::string rhs;
@@ -737,7 +737,7 @@ template <ColumnFieldType Col, AnySelectQuery Query>
     return {column_traits<Col>::column_name(), " NOT IN ", std::move(rhs)};
 }
 
-template <AnySelectQuery Query>
+template <SqlBuilder Query>
 [[nodiscard]] sql_predicate exists(Query const& subquery) {
     auto sub = subquery.build_sql();
     std::string s;
@@ -748,7 +748,7 @@ template <AnySelectQuery Query>
     return {{}, {}, std::move(s)};
 }
 
-template <AnySelectQuery Query>
+template <SqlBuilder Query>
 [[nodiscard]] sql_predicate not_exists(Query const& subquery) {
     auto sub = subquery.build_sql();
     std::string s;
@@ -871,17 +871,17 @@ struct col_expr {
         return ds_mysql::null_safe_equal<Col>(Col{val});
     }
 
-    template <AnySelectQuery Query>
+    template <SqlBuilder Query>
     [[nodiscard]] sql_predicate in_subquery(Query const& subquery) const {
         return ds_mysql::in_subquery<Col>(subquery);
     }
 
-    template <AnySelectQuery Query>
+    template <SqlBuilder Query>
     [[nodiscard]] sql_predicate not_in_subquery(Query const& subquery) const {
         return ds_mysql::not_in_subquery<Col>(subquery);
     }
 
-    template <AnySelectQuery Query>
+    template <SqlBuilder Query>
     [[nodiscard]] sql_predicate eq_subquery(Query const& subquery) const {
         auto sub = subquery.build_sql();
         std::string rhs;
@@ -892,7 +892,7 @@ struct col_expr {
         return {column_traits<Col>::column_name(), " = ", std::move(rhs)};
     }
 
-    template <AnySelectQuery Query>
+    template <SqlBuilder Query>
     [[nodiscard]] sql_predicate ne_subquery(Query const& subquery) const {
         auto sub = subquery.build_sql();
         std::string rhs;
@@ -903,7 +903,7 @@ struct col_expr {
         return {column_traits<Col>::column_name(), " != ", std::move(rhs)};
     }
 
-    template <AnySelectQuery Query>
+    template <SqlBuilder Query>
     [[nodiscard]] sql_predicate lt_subquery(Query const& subquery) const {
         auto sub = subquery.build_sql();
         std::string rhs;
@@ -914,7 +914,7 @@ struct col_expr {
         return {column_traits<Col>::column_name(), " < ", std::move(rhs)};
     }
 
-    template <AnySelectQuery Query>
+    template <SqlBuilder Query>
     [[nodiscard]] sql_predicate gt_subquery(Query const& subquery) const {
         auto sub = subquery.build_sql();
         std::string rhs;
@@ -925,7 +925,7 @@ struct col_expr {
         return {column_traits<Col>::column_name(), " > ", std::move(rhs)};
     }
 
-    template <AnySelectQuery Query>
+    template <SqlBuilder Query>
     [[nodiscard]] sql_predicate le_subquery(Query const& subquery) const {
         auto sub = subquery.build_sql();
         std::string rhs;
@@ -936,7 +936,7 @@ struct col_expr {
         return {column_traits<Col>::column_name(), " <= ", std::move(rhs)};
     }
 
-    template <AnySelectQuery Query>
+    template <SqlBuilder Query>
     [[nodiscard]] sql_predicate ge_subquery(Query const& subquery) const {
         auto sub = subquery.build_sql();
         std::string rhs;
@@ -952,14 +952,4 @@ struct col_expr {
 template <ColumnFieldType Col>
 inline constexpr col_expr<Col> col_ref{};
 
-// ===================================================================
-// SqlStatement — unified concept for all SQL builder types.
-// Satisfied by any builder stage that exposes build_sql() -> std::string.
-// ===================================================================
-
-template <typename T>
-concept SqlStatement = requires(T const& t) {
-    { t.build_sql() } -> std::convertible_to<std::string>;
-};
-
 }  // namespace ds_mysql