SqlConnection: allow configurable encryption via SQL_COPT_SS_ENCRYPT (#578)

Closes #14

## What

Adds `SqlEncryptionMode` (`DriverDefault` / `Disabled` / `Enabled`) and
a matching
`SqlConnectionDataSource::encryption` field, so an application can
explicitly request — or refuse —
a TLS-encrypted connection.

```cpp
SqlConnection::SetDefaultDataSource(SqlConnectionDataSource {
    .datasource = "MyServerDSN",
    .username = "user",
    .password = "password",
    .encryption = SqlEncryptionMode::Enabled,
});
```

## Why this shape

Previously the only way to configure encryption was to spell out a
driver keyword in a raw
connection string. On the DSN-based connect path (`SQLConnect`) there is
no connection string to put
that keyword in, so encryption was not configurable there at all — which
is exactly the gap
`SQL_COPT_SS_ENCRYPT` exists to close.

Three judgment calls worth reviewing, since the issue specifies the
mechanism but not the API:

1. **Tri-state with a `DriverDefault` sentinel**, following the existing
`SqlIsolationMode::DriverDefault`
precedent (`SqlTransaction.cpp:19`). The default leaves the attribute
untouched, so anything that
   does not opt in behaves bit-for-bit as before.
2. **Fail-closed.** `SQL_COPT_SS_ENCRYPT` is a *pre-connect* attribute,
so the server type is not known
yet and cannot be branched on — which is why only an explicit opt-in
touches it at all. If the
caller did opt in and the driver rejects the attribute, the connection
**fails** instead of being
established. Silently downgrading a requested encrypted connection to
plaintext seemed like the
wrong failure mode for a security setting; happy to flip this if you
disagree.
3. **The setting survives flattening into a connection string.**
`ToConnectionString()` emits
`Encrypt=yes|no` (nothing at all for `DriverDefault`),
`FromConnectionString()` parses it back, and
`SetDefaultDataSource()` now delegates to `ToConnectionString()` rather
than re-formatting a subset
of the fields — otherwise that path would silently drop the knob.
(`std::formatter<SqlConnectInfo>`
   was duplicating the same format string and is now delegated too.)

`SQL_COPT_SS_ENCRYPT` and its `SQL_EN_*` values live in Microsoft's
`msodbcsql.h`, which unixODBC does
not ship, so the values are mirrored locally rather than adding a
dependency on that header.

## Tests

- 11 new unit cases in `SqlConnectInfoEdgeTests.cpp`: keyword parsing
(all documented spellings,
case-insensitive, whitespace-tolerant, unknown → `DriverDefault`),
rendering, round-tripping,
comparison, and a regression guard that a non-opted-in data source
renders byte-for-byte as before.
- 1 new DB case in `SqlConnectionDbTests.cpp`: opens an explicitly
encrypted connection against SQL
Server and round-trips a query over it. `UNSUPPORTED_DATABASE`-gated for
the other backends, which
  configure TLS through their own keywords.

**Coverage gap, stated explicitly:** the
`SQLSetConnectAttr(SQL_COPT_SS_ENCRYPT)` call itself is on the
DSN connect path, which needs a registered DSN and so is not reachable
from the CI harness (all test
envs use connection strings). The end-to-end test therefore exercises
the equivalent
connection-string path. The attribute application itself is covered only
by construction and review.

## Databases tested

| Database | Result |
|---|---|
| `sqlite3` | 1414 cases, 1413 passed, 1 pre-existing skip |
| `mssql2022` (Docker, `mcr.microsoft.com/mssql/server:2022-latest`) |
1414 cases, 1411 passed, 3 pre-existing skips |
| `postgres` (Docker 16.4) | 1414 cases, 1412 passed, 2 pre-existing
skips |

The new encrypted-connection case was confirmed to actually *run* (not
skip) and pass on `mssql2022`.

## Compilers tested

- `clang-debug` (ASan + UBSan + pedantic `-Werror`) — all three
databases above. **This is the one that
  ran the suite.**
- **GCC was not exercised**, contrary to `AGENT.md` step 3. The
`gcc-release` preset is Linux-gated
(`Cannot use disabled configure preset`) and this is macOS. I configured
GCC 15 manually with
`LIGHTWEIGHT_BUILD_MODULES=ON` instead; `SqlConnection.cpp` and
`SqlConnectInfo.cpp` both compiled
clean under it, but the build cannot complete on macOS for reasons
unrelated to this change (see
  below). **The GCC and modules legs need CI to be the judge.**

## Pre-existing issues found while validating (not fixed here)

Building `gcc-release -D LIGHTWEIGHT_BUILD_MODULES=ON` with GCC 15 on
macOS fails on untouched code.
Flagging in case they bite on a compiler bump — CI currently pins GCC
14:

- `SqlLogger.cpp:291`: `'std::stacktrace' has not been declared`
(Homebrew libstdc++ lacks it; the
`LIGHTWEIGHT_HAVE_STDCXXEXP` probe fails and the `#if` guard then leaves
the call unguarded).
- GCC 15 tightened the module TU-local-exposure diagnostic and now
rejects three pre-existing entities:
`SqlConnectInfo.hpp`'s `PrefetchDepthDefault` (namespace-scope
`constexpr`, needs `inline constexpr`),
`detail::kDefaultRowArrayFetchDepth`, and
`Reflection::MaxReflectionMemerCount` (in the vendored
  `reflection-cpp` dep). None involve this PR's new symbols.

## Performance impact

None. One extra `SQLSetConnectAttr` per connection, and only when the
caller opts in; the default path
adds a single predictable enum comparison. No allocation added on any
hot path.

## Risk assessment

**Low.** The entire feature is inert unless a caller sets `encryption`
to something other than
`DriverDefault`. The one behaviour change that reaches non-opted-in code
is `SetDefaultDataSource()`
delegating to `ToConnectionString()` — verified to produce a
byte-identical string in that case, with a
regression test pinning it.

ABI: `SqlConnectionDataSource` grows a member, so this is a breaking ABI
change for that struct (source
compatible; the defaulted `operator<=>` now also compares the new
field).

Author: Yaraslaut

docs/usage.md

@@ -17,6 +17,47 @@ if (!sqlConnection.IsAlive())
 }
 ```
 
+## Connection encryption
+
+By default Lightweight does not touch the driver's TLS configuration — whatever the ODBC driver, the
+DSN, or the connection string already says stays in force. To take explicit control, set the
+`encryption` field of `SqlConnectionDataSource`:
+
+```cpp
+SqlConnection::SetDefaultDataSource(SqlConnectionDataSource {
+    .datasource = "MyServerDSN",
+    .username = "user",
+    .password = "password",
+    .encryption = SqlEncryptionMode::Enabled,
+});
+```
+
+`SqlEncryptionMode` has three values:
+
+| Value | Meaning |
+|-------|---------|
+| `DriverDefault` | Do not touch the setting (the default). |
+| `Disabled` | Request an unencrypted connection. |
+| `Enabled` | Request an encrypted connection. |
+
+This maps onto the Microsoft SQL Server ODBC attribute
+[`SQL_COPT_SS_ENCRYPT`](https://learn.microsoft.com/en-us/sql/relational-databases/native-client-odbc-api/sqlsetconnectattr),
+which has to be applied to the connection handle *before* connecting. Because the server type is not
+yet known at that point, the setting is applied verbatim whenever you opt in — and if the driver
+rejects it, the connection **fails** rather than silently falling back to an unencrypted channel.
+Leave the field at `DriverDefault` on backends that configure TLS through their own keywords
+(PostgreSQL's `sslmode`, for example).
+
+When connecting with a raw `SqlConnectionString` instead, use the driver's own `Encrypt=` keyword —
+it is what `SqlConnectionDataSource::ToConnectionString()` emits, and
+`SqlConnectionDataSource::FromConnectionString()` reads it back:
+
+```cpp
+auto const connectionString = SqlConnectionString {
+    .value = "Driver={ODBC Driver 18 for SQL Server};SERVER=db;UID=user;PWD=password;Encrypt=yes"
+};
+```
+
 ## Raw SQL Queries
 
 To directly make a call to the database use `ExecuteDirect` function, for example

src/Lightweight/Lightweight.cppm

@@ -55,6 +55,7 @@ using Lightweight::Field;
 using Lightweight::FieldNameAt;
 using Lightweight::FieldNameOf;
 using Lightweight::FieldWithStorage;
+using Lightweight::FormatEncryptionMode;
 using Lightweight::FormatName;
 using Lightweight::FormatType;
 using Lightweight::FullyQualifiedNameOf;
@@ -99,6 +100,7 @@ using Lightweight::MemberClassType;
 using Lightweight::MemberIndexOf;
 using Lightweight::NotSqlElements;
 using Lightweight::ParseConnectionString;
+using Lightweight::ParseEncryptionMode;
 using Lightweight::PostgreSqlFormatter;
 using Lightweight::PrimaryKey;
 using Lightweight::QualifiedColumnName;
@@ -156,6 +158,7 @@ using Lightweight::SqlDynamicUtf16String;
 using Lightweight::SqlDynamicUtf32String;
 using Lightweight::SqlDynamicWideString;
 using Lightweight::SqlElements;
+using Lightweight::SqlEncryptionMode;
 using Lightweight::SqlError;
 using Lightweight::SqlErrorCategory;
 using Lightweight::SqlErrorInfo;

src/Lightweight/SqlConnectInfo.cpp

@@ -3,13 +3,15 @@
 #include "SqlConnectInfo.hpp"
 
 #include <algorithm>
+#include <array>
 #include <filesystem>
 #include <fstream>
 #include <ranges>
 #include <regex>
 #include <string>
 #include <string_view>
 #include <system_error>
+#include <utility>
 
 namespace Lightweight
 {
@@ -48,7 +50,50 @@ namespace
         return result;
     }
 
+    /// Maps the ODBC `Encrypt=` keyword spellings onto SqlEncryptionMode. The first entry of each mode
+    /// is also its canonical rendering, so the table drives both directions.
+    constexpr std::array<std::pair<std::string_view, SqlEncryptionMode>, 8> EncryptionModeSpellings { {
+        { "yes", SqlEncryptionMode::Enabled },
+        { "true", SqlEncryptionMode::Enabled },
+        { "1", SqlEncryptionMode::Enabled },
+        // `mandatory` is the ODBC Driver 18 synonym of `yes`.
+        { "mandatory", SqlEncryptionMode::Enabled },
+        { "no", SqlEncryptionMode::Disabled },
+        { "false", SqlEncryptionMode::Disabled },
+        { "0", SqlEncryptionMode::Disabled },
+        // `optional` is the ODBC Driver 18 synonym of `no`.
+        { "optional", SqlEncryptionMode::Disabled },
+    } };
+
+    constexpr bool EqualsIgnoreCase(std::string_view a, std::string_view b) noexcept
+    {
+        return std::ranges::equal(a, b, [](char x, char y) {
+            return std::tolower(static_cast<unsigned char>(x)) == std::tolower(static_cast<unsigned char>(y));
+        });
+    }
+
 } // end namespace
+
+SqlEncryptionMode ParseEncryptionMode(std::string_view value) noexcept
+{
+    auto const trimmed = Trim(value);
+    for (auto const& [spelling, mode]: EncryptionModeSpellings)
+        if (EqualsIgnoreCase(spelling, trimmed))
+            return mode;
+    return SqlEncryptionMode::DriverDefault;
+}
+
+std::string_view FormatEncryptionMode(SqlEncryptionMode mode) noexcept
+{
+    if (mode == SqlEncryptionMode::DriverDefault)
+        return {};
+
+    for (auto const& [spelling, candidate]: EncryptionModeSpellings)
+        if (candidate == mode)
+            return spelling;
+    return {};
+}
+
 std::string SqlConnectionString::Sanitized() const
 {
     return SanitizePwd(value);
@@ -177,6 +222,9 @@ SqlConnectionDataSource SqlConnectionDataSource::FromConnectionString(SqlConnect
     if (auto timeout = parsedConnectionStringPairs.extract("TIMEOUT"); !timeout.empty())
         result.timeout = std::chrono::seconds(std::stoi(timeout.mapped()));
 
+    if (auto encrypt = parsedConnectionStringPairs.extract("ENCRYPT"); !encrypt.empty())
+        result.encryption = ParseEncryptionMode(encrypt.mapped());
+
     return result;
 }
 

src/Lightweight/SqlConnectInfo.hpp

@@ -6,9 +6,11 @@
 
 #include <chrono>
 #include <cstddef>
+#include <cstdint>
 #include <format>
 #include <map>
 #include <string>
+#include <string_view>
 #include <variant>
 
 namespace Lightweight
@@ -23,6 +25,51 @@ namespace Lightweight
 /// a value <= 1 disables prefetch.
 constexpr std::size_t PrefetchDepthDefault = 1000;
 
+/// @ingroup CoreApi
+/// @brief Whether the client/server connection is TLS-encrypted.
+///
+/// Maps onto the Microsoft SQL Server ODBC connection attribute @c SQL_COPT_SS_ENCRYPT, which must be
+/// set on the connection handle *before* connecting. This is the only way to request encryption on the
+/// DSN-based connect path (@c SQLConnect), where there is no connection string for an @c Encrypt=
+/// keyword to live in.
+///
+/// @see https://learn.microsoft.com/en-us/sql/relational-databases/native-client-odbc-api/sqlsetconnectattr
+enum class SqlEncryptionMode : std::uint8_t
+{
+    /// Leave the attribute untouched — whatever the driver, DSN, or connection string configures wins.
+    ///
+    /// This is the default, so an application that does not opt in behaves exactly as before.
+    DriverDefault = 0,
+
+    /// Request an unencrypted connection (@c SQL_EN_OFF).
+    Disabled = 1,
+
+    /// Request an encrypted connection (@c SQL_EN_ON).
+    Enabled = 2,
+};
+
+/// Parses an ODBC @c Encrypt= connection-string value into a @ref SqlEncryptionMode.
+///
+/// Recognizes the spellings the SQL Server drivers accept, case-insensitively: @c yes / @c no,
+/// @c true / @c false, @c 1 / @c 0, and the ODBC Driver 18 synonyms @c mandatory / @c optional.
+///
+/// @warning @c SqlEncryptionMode has no representation for ODBC Driver 18's @c strict (TDS 8.0 with
+///          mandatory certificate validation), so @c Encrypt=strict parses as
+///          @c SqlEncryptionMode::DriverDefault and is *dropped* by a subsequent
+///          @ref SqlConnectionDataSource::ToConnectionString(). Keep such connection strings as a raw
+///          @ref SqlConnectionString instead of round-tripping them through a data source.
+///
+/// @param value The raw keyword value.
+/// @return The matching mode, or @c SqlEncryptionMode::DriverDefault if @p value is not recognized.
+[[nodiscard]] LIGHTWEIGHT_API SqlEncryptionMode ParseEncryptionMode(std::string_view value) noexcept;
+
+/// Renders a @ref SqlEncryptionMode as the ODBC @c Encrypt= connection-string value.
+///
+/// @param mode The mode to render.
+/// @return @c "yes" or @c "no", or an empty view for @c SqlEncryptionMode::DriverDefault (which is
+///         expressed by omitting the keyword entirely).
+[[nodiscard]] LIGHTWEIGHT_API std::string_view FormatEncryptionMode(SqlEncryptionMode mode) noexcept;
+
 /// @ingroup CoreApi
 /// Represents an ODBC connection string.
 struct SqlConnectionString
@@ -82,15 +129,27 @@ struct [[nodiscard]] SqlConnectionDataSource
     /// native row-array fetching (see @c SqlConnection::SupportsNativeRowArrayFetch).
     std::size_t defaultPrefetchDepth = PrefetchDepthDefault;
 
+    /// @brief Whether to request a TLS-encrypted connection.
+    ///
+    /// Defaults to @c SqlEncryptionMode::DriverDefault, which leaves the driver's own configuration in
+    /// charge. Any other value is applied to the connection handle before connecting, and a driver that
+    /// rejects it fails the connection rather than silently downgrading to plaintext.
+    SqlEncryptionMode encryption = SqlEncryptionMode::DriverDefault;
+
     /// Constructs a SqlConnectionDataSource from the given connection string.
     LIGHTWEIGHT_API static SqlConnectionDataSource FromConnectionString(SqlConnectionString const& value);
 
     /// Converts this data source to an ODBC connection string.
+    ///
+    /// The @c Encrypt= keyword is emitted only when @ref encryption is not
+    /// @c SqlEncryptionMode::DriverDefault, so the rendering of a data source that did not opt in is
+    /// byte-for-byte what it always was.
     [[nodiscard]] LIGHTWEIGHT_API SqlConnectionString ToConnectionString() const
     {
-        return SqlConnectionString {
-            .value = std::format("DSN={};UID={};PWD={};TIMEOUT={}", datasource, username, password, timeout.count())
-        };
+        auto value = std::format("DSN={};UID={};PWD={};TIMEOUT={}", datasource, username, password, timeout.count());
+        if (auto const encryptValue = FormatEncryptionMode(encryption); !encryptValue.empty())
+            value += std::format(";Encrypt={}", encryptValue);
+        return SqlConnectionString { .value = std::move(value) };
     }
 
     /// Three-way comparison operator.
@@ -108,10 +167,7 @@ struct std::formatter<Lightweight::SqlConnectInfo>: std::formatter<std::string>
     {
         if (auto const* dsn = std::get_if<Lightweight::SqlConnectionDataSource>(&info))
         {
-            return formatter<string>::format(
-                std::format(
-                    "DSN={};UID={};PWD={};TIMEOUT={}", dsn->datasource, dsn->username, dsn->password, dsn->timeout.count()),
-                ctx);
+            return formatter<string>::format(dsn->ToConnectionString().value, ctx);
         }
         else if (auto const* connectionString = std::get_if<Lightweight::SqlConnectionString>(&info))
         {

src/Lightweight/SqlConnection.cpp

@@ -12,6 +12,7 @@
 #include <algorithm>
 #include <array>
 #include <mutex>
+#include <optional>
 #include <stdexcept>
 
 #include <sql.h>
@@ -45,6 +46,38 @@ namespace
         return std::string { reinterpret_cast<char const*>(utf8.data()), utf8.size() };
     }
 
+    // SQL_COPT_SS_ENCRYPT and its SQL_EN_* values are declared in the Microsoft-specific `msodbcsql.h`
+    // (formerly `sqlncli.h`), which unixODBC does not ship and which we must not take a dependency on —
+    // Lightweight builds against plain unixODBC on Linux/macOS. Mirror the values instead; they are part
+    // of the driver's stable ABI.
+    // https://learn.microsoft.com/en-us/sql/relational-databases/native-client-odbc-api/sqlsetconnectattr
+    constexpr SQLINTEGER SqlCoptSsEncrypt = 1200 + 23; // SQL_COPT_SS_BASE + 23
+    constexpr SQLULEN SqlEncryptOff = 0;               // SQL_EN_OFF
+    constexpr SQLULEN SqlEncryptOn = 1;                // SQL_EN_ON
+
+    /// Maps a SqlEncryptionMode onto the SQL_COPT_SS_ENCRYPT attribute value to set.
+    ///
+    /// @param mode The requested encryption mode.
+    /// @return The attribute value, or `std::nullopt` for `DriverDefault` (the attribute is then not
+    ///         touched at all, leaving the driver's own configuration in charge).
+    constexpr std::optional<SQLULEN> ToOdbcEncryptValue(SqlEncryptionMode mode) noexcept
+    {
+        switch (mode)
+        {
+            case SqlEncryptionMode::DriverDefault:
+                return std::nullopt;
+            case SqlEncryptionMode::Disabled:
+                return SqlEncryptOff;
+            case SqlEncryptionMode::Enabled:
+                return SqlEncryptOn;
+        }
+        // Unreachable: the switch above is exhaustive over the enumerators, and every arm returns.
+        // It stays because a switch over a scoped enum without a default label still leaves the
+        // function without a return statement as far as -Wreturn-type is concerned. The coverage
+        // report flags this line for that reason, not because a test is missing.
+        return std::nullopt;
+    }
+
 } // namespace
 
 // =====================================================================================================================
@@ -153,11 +186,9 @@ void SqlConnection::SetDefaultConnectionString(SqlConnectionString const& connec
 
 void SqlConnection::SetDefaultDataSource(SqlConnectionDataSource const& dataSource) noexcept
 {
-    gDefaultConnectionString = SqlConnectionString { .value = std::format("DSN={};UID={};PWD={};TIMEOUT={}",
-                                                                          dataSource.datasource,
-                                                                          dataSource.username,
-                                                                          dataSource.password,
-                                                                          dataSource.timeout.count()) };
+    // Delegate rather than re-format: ToConnectionString() is the single place that knows which fields
+    // (including the optional `Encrypt=` keyword) have to survive the flattening into a connection string.
+    gDefaultConnectionString = dataSource.ToConnectionString();
 }
 
 SqlConnectionString const& SqlConnection::ConnectionString() const noexcept
@@ -270,6 +301,32 @@ bool SqlConnection::Connect(SqlConnectionDataSource const& info) noexcept
             return false;
         }
 
+        // SQL_COPT_SS_ENCRYPT is a pre-connect attribute, so it has to be set here rather than in
+        // PostConnect() — which also means the server type is not known yet and cannot be branched on.
+        // Only an explicit opt-in touches the attribute, so non-SQL-Server drivers are unaffected by
+        // default. When the caller *did* opt in and the driver rejects the attribute, the connection is
+        // failed rather than established: silently downgrading a requested encrypted connection to
+        // plaintext would be the wrong failure mode for a security setting.
+        //
+        // Caveat: the DBC handle is reused across Connect() calls (see SQLDisconnect above), and ODBC
+        // offers no way to restore a connection attribute to "driver default". So reconnecting the same
+        // SqlConnection with SqlEncryptionMode::DriverDefault after an explicit opt-in keeps the
+        // previously applied value. Use a fresh SqlConnection when the encryption request changes.
+        if (auto const encryptValue = ToOdbcEncryptValue(info.encryption))
+        {
+            // NOLINTNEXTLINE(performance-no-int-to-ptr)
+            sqlReturn = SQLSetConnectAttrW(m_hDbc, SqlCoptSsEncrypt, (SQLPOINTER) *encryptValue, SQL_IS_UINTEGER);
+            if (!SQL_SUCCEEDED(sqlReturn))
+            {
+                // Not reachable from the test suite: this needs a driver manager that rejects
+                // SQL_COPT_SS_ENCRYPT at set time. Both unixODBC and the Windows driver manager defer
+                // driver-specific connection attributes until a driver is loaded, so every driver in
+                // the matrix accepts the call here and surfaces a refusal from SQLConnectW instead.
+                SqlLogger::GetLogger().OnError(LastError());
+                return false;
+            }
+        }
+
         sqlReturn = SQLConnectW(m_hDbc,
                                 wDataSource.data(),
                                 wDataSource.length(),