Address result columns by the name used in the query builder

[Yaraslaut]

Closes #341

What

Result columns of a builder-composed query can now be read by the name spelled in the builder, instead of by a 1-based index that shifts whenever the projection changes:

auto cursor = stmt.ExecuteDirect(stmt.Query("Table_A")
                                     .Select()
                                     .Field(SqlQualifiedTableColumnName { "Table_A", "foo" })
                                     .Fields({ "a"sv, "b"sv }, "Table_B")
                                     .Field(Aggregate::Count("id"sv)).As("total"sv)
                                     .LeftOuterJoin("Table_B", "id"sv, "that_id"sv)
                                     .All());

while (cursor.FetchRow())
{
    auto const foo = cursor.GetColumn<int>("Table_A.foo");
    auto const a = cursor.GetColumn<int>("Table_B.a");
    auto const total = cursor.GetColumn<int>("total");
}

GetNullableColumn<T>(name) and GetColumnOr<T>(name, defaultValue) take a name the same way.

Why the mapping comes from the builder, not from ODBC

The obvious implementation — ask the driver via SQLDescribeCol / SQLColAttribute — cannot deliver the table-qualified names the issue asks for. Probing all three supported drivers with the same join (SELECT t1.x, t2.a, ... FROM t1 JOIN t2 ...):

Driver	Column name	Table name
SQLite3 ODBC	reported	reported
PostgreSQL Unicode	reported	reported
ODBC Driver 18 for SQL Server	reported	empty

SQL Server only populates SQL_DESC_TABLE_NAME when the statement runs a static, server-side cursor; under the library's default forward-only cursor it returns empty strings. Going that route would have meant either an API that behaves differently per DBMS, or switching cursor type library-wide.

Recording the names in SqlSelectQueryBuilder as the projection is assembled avoids both: the mapping is identical on every backend and costs no round-trip. The trade-off is that named access is available only for builder-composed queries.

Name rules

Names match exactly as spelled — no case folding, no implicit qualification:

Builder call	Name to read it back by
Field("foo")	"foo"
Field({ "Table_A", "foo" })	"Table_A.foo"
Fields({ "a"sv, "b"sv }, "Table_B")	"Table_B.a", "Table_B.b"
Field(...).As("total") / FieldAs(..., "total")	"total"
Field(Aggregate::Count("id"sv))	not addressable — occupies an unnamed slot that holds its position

std::invalid_argument is thrown for a name that is unknown, ambiguous (projected twice), or empty, and for a query with no usable mapping: raw SQL, or a projection containing a wildcard, whose column count is unknown at build time. A statement reused for raw SQL drops the previous query's mapping rather than resolving stale names.

Implementation

• detail::ComposedQuery gains projectedFieldNames + projectionHasWildcard, exposed via ProjectedFieldNames() / ProjectionHasWildcard(). It already travels to the statement as the query object, so no new plumbing was needed between builder and statement.
• A new SqlNamedProjectionQueryObject concept lets Prepare / ExecuteDirect adopt the mapping when the query object carries one.
• SqlResultCursor — already the object the statement returns — resolves names by linear scan over a vector that is realistically under 20 entries. No hash map, no per-lookup allocation.
• Incidental fix: the rvalue Prepare(SqlQueryObject auto const&) && overload could not have compiled if instantiated (it called the &-qualified string overload, which returns void, from a function returning SqlStatement). It is now correct, since named queries take that path.

Verification

Databases — full suite, run sequentially, lexical order:

Database	Result
sqlite3 (SQLite 3.46.1)	1409 passed, 1 skipped
postgres (Docker, PostgreSQL 16.4)	1408 passed, 2 skipped
mssql2022 (Docker, SQL Server 16.00.4265)	1407 passed, 3 skipped

Compilers — clang-release (Clang 21, macOS) locally; clang-tidy run against the changed translation units with the clang-debug compile database, clean. GCC and the C++20-modules / C++26-reflection configurations are left to CI — they are not reachable from a local preset on this host.

Coverage — 9 new builder-level test cases in QueryBuilderTests.cpp asserting the recorded name vector for every projection entry point with no database involved, and 8 end-to-end cases in SqlStatementDbTests.cpp covering bare / qualified / aliased reads, Prepare + Execute, nullable and default-valued reads, and every error path.

Risk

• Per-DBMS: none by construction — the mapping never consults the driver, so it cannot vary by backend.
• Behaviour: purely additive. Existing index-based overloads are untouched; the new overloads are selected only for a std::string_view-convertible argument.
• Performance: one std::string per projected column at build time; the SQL text itself is unchanged. Lookup is a linear scan, only on the named path.
• Ordering caveat (documented): reads must still ascend in column order, since SQL Server rejects out-of-order SQLGetData with SQLSTATE 07009 and named access makes reordering easy to do inadvertently.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.76543% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/Lightweight/SqlQuery/Select.hpp	50.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!