Repository navigation
Version 2.0.0
[Summary]
StormByte Database is the C++26 SQL layer of the StormByte suite.
One API covers SQLite, PostgreSQL, MariaDB and Microsoft SQL Server (MSSQL).
Backends are base classes: you derive your schema, prepare statements and hook connect there.
This repository is not Base, Buffer, Config, Crypto, Logger, Multimedia, Network or System.
It requires StormByte-Logger 2.0.0 or newer, which supplies the bundled text and StormByte Base dependencies.
The original StormByte-Database source is dual-licensed under LGPL v3.0-or-later or a commercial license.
If you landed here from a release link and have not read the tree:
- What this module is, how to build it, and short examples: README.md
- License: dual LGPL v3.0-or-later / commercial, LICENSE and COPYING.LGPLv3
Changed
- DLL boundary — Hardened provider-owned storage while preserving inheritable database facades:
- Hid the prepared-statement registry behind an opaque
Safe::Uniqueowner on Base's heap and migrated its entries toSafe::Map<Safe::String, Safe::Shared<Safe::Unique<PreparedSTMT>>>. Creator-module callbacks retain map nodes and allocator state; copyable handles keep each statement uniquely owned without changing inheritable factories returningSafe::Unique. - Column names and prepared-statement names and SQL text use
Safe::String, so inline accessors no longer interpret another module's standard strings. - Migrated private connection settings in inheritable PostgreSQL, MariaDB and MSSQL backends, PostgreSQL's server-side statement name and MSSQL's callback diagnostics to Base-owned
Safe::String. Rows and positional prepared values use Base-ownedSafe::Vector/Safe::Map; telemetry counters useSafe::Atomic. Native connection and statement handles are hidden behind semantic holders defined in non-installed private headers, while client-specific temporary buffers remain local to Database implementations. Safe allocation ownership does not remove the compatible C++ ABI, RTTI, calling-convention and provider-lifetime requirements for derived objects. - SQLite's protected native-path constructors convert to Base-owned UTF-8 in forced-inline caller adapters; rvalue paths no longer transfer caller STL allocations to the Database DLL, and Windows paths use SQLite's UTF-8 encoding.
- Exported values, rows, transactions, database facades, prepared statements and telemetry declare
STORMBYTE_DECLARE_MAYBE_SAFEwith compatible-ABI and provider-lifetime requirements. Consumer derivatives remain responsible for their additional state and their own conditional declaration.
- Hid the prepared-statement registry behind an opaque
- MSSQL backend — Added an optional Microsoft SQL Server backend using the LGPL FreeTDS DB-Library client. Bundled builds compile only the static DB-Library and its required TDS support archives; logical prepared statements use
sp_executesqlRPC with typed, separately transmitted parameters. - StormByte Suite port — Migrated first-party repository and documentation links to StormByte-Suite, removed the retired String repository from the suite listing and Doxygen tag references, and updated the Logger and BuildMaster submodule URLs.
- Database API and connection behavior
- Breaking: Removed accessor
Get/Setprefixes:GetTelemetry()becomesTelemetry(), protectedSetTelemetry(handle)becomesTelemetry(handle), andGetSslMode()/SetSslMode(mode)becomeSslMode()/SslMode(mode).Value::Get<T>()is unchanged. Backend text-member layouts changed with the Safe storage migration; rebuild derived consumers. - Breaking:
BeginTransactionnow returnsExpected<Transaction, TransactionError>instead of throwing when transaction start fails.Databaseconstruction may also report allocation failure rather than terminating from anoexceptconstructor; rebuild consumers against this API revision. - Breaking: The public API contract changed beyond the DLL boundary fix. Inputs and storage use StormByte 2.0 types (
StormByte::Safe::String,StormByte::Safe::Binary,StormByte::Size,StormByte::ByteSize,std::string_view), backend logger ownership isStormByte::Safe::Shared<Logger::Log>instead of raw pointers, and statement/query factory signatures accept view-based names and SQL text rather than rvalue strings. Input views are consumed within Database and are not retained across the DLL boundary; owned text and bytes use Base Safe types. The exported layout ofDatabase,PreparedSTMT,Row,Rows,Value,NamedValueand backend result containers was tightened to enforce DLL-safe ownership and out-of-line heap operations; consumers must recompile and update code that relied on old string, logger, or STL-owning ABI assumptions. - Breaking: Added shared telemetry state to exported
DatabaseandPreparedSTMTobjects; rebuild consumers against this ABI revision. - Breaking:
Value::Type::LongIntegerandValue::Type::UnsignedLongIntegernow storelong long intandunsigned long long int, so they are 64-bit on every platform; useGet<long long int>()/Get<unsigned long long int>().long intandunsigned long intare still accepted when constructing values. - Serialized operations on each built-in connection. RAII transactions hold exclusive connection access through commit or rollback and must remain on their creating thread.
- Breaking: Removed accessor
- Telemetry — Added thread-safe operation counts, success/failure totals, returned-row counts, latency aggregates, backend error/warning categories, retained
StormByte::Safe::Sharedsnapshots, andStormByte::Safe::String/std::stringflattening for SQLite, PostgreSQL and MariaDB. Database telemetry derives fromStormByte::Telemetryand uses independent best-effortClock::Samplemeasurements, removing obsolete per-category locks and cumulative-time subtraction. Same-category samples can overlap or nest, and clock snapshots useGetValues(). Concurrent readers see zero rather than an uninitialized minimum-latency sentinel while the first result is being published. - Build and distribution — Ported the library to BuildMaster 2 HOST with shared/static selection. Static consumers receive flattened private vendor dependencies; vendor archives do not need repacking. Updated Doxygen configuration for StormByte Base and Logger 2.0 and the dual-license terms. Dependency tags and generated cross-links use verified HTTPS endpoints; preprocessing recognizes the Safe declaration and caller-inline macros. Doxygen generation was checked with warnings treated as errors without persisting that validation policy in CMake. Restored Linux CI coverage for Clang/libc++ with explicit
-stdlib=libc++inOFFandBUNDLEDdependency modes;SYSTEMremains excluded for that variant to avoid mixing standard-library ABIs. - Robustness tests — Expanded tests for numeric boundaries, Row/Rows value semantics, backend scalar and binary round-trips, transaction rollback, prepared-statement failures, registry duplicates and cleanup with long and embedded-NUL names, same-connection concurrency, overlapping telemetry samples, Safe classification, and an installed external consumer using Safe collections and inherited SQLite path constructors. Regression tests preserve complete embedded-NUL text through value/row copies, Safe collections and SQLite bindings, reject invalid SQLite SQL and paths, and reject PostgreSQL NUL text without inserting a truncated prefix. Telemetry assertions now use fixed-width unsigned expected values and SQLite concurrency lambdas omit unnecessary captures, allowing strict warning validation without suppressions.
Fixed
- MSSQL backend — Fixed result and statement handling across FreeTDS versions:
- Zero-length text and binary values are returned as empty values instead of being padded by
dbconvert(). - Connections enable
QUOTED_IDENTIFIER, so double-quoted identifiers resolve as identifiers on older DB-Library releases. - NULL prepared-statement parameters are sent as untyped
NULL, allowing them in any column type such asVARBINARY(MAX). - SQL Server error messages are kept instead of DB-Library's generic notice, and
Telemetry::Errors()now counts them.
- Zero-length text and binary values are returned as empty values instead of being padded by
- Windows bundled OpenSSL consumers — Nested builds now link
ws2_32andcrypt32alongside the static bundled OpenSSL:- PostgreSQL's Meson configure, so its OpenSSL function checks succeed.
- MariaDB Connector/C plugin DLLs such as
sha256_password.dll.
- TLS dependency selection — Added
WITH_OPENSSL=SYSTEM|BUNDLED, rejectingOFFand retainingBUNDLEDas the default. Windows forcesBUNDLEDregardless of the requested value, matching its database client policy. Bundled FreeTDS, MariaDB Connector C and PostgreSQL share pinned static OpenSSL 3.5.9 in bundled mode or discover installed dynamic OpenSSL in system mode without requiring static archives. CMake clients receive the selected library and include paths with static discovery disabled forSYSTEM; PostgreSQL uses native Meson discovery without a generated pkg-config adapter. Changing dependency modes requires a clean build directory. Linux and macOS CI select OpenSSL to match enabled dependency modes and omit the option when backends areOFF; Windows CI explicitly selectsBUNDLED, and macOS only adds system OpenSSL search paths inSYSTEMjobs. The installed-consumer smoke test checks that bundled TLS clients usingSYSTEMresolve the selected SSL and Crypto dynamic libraries, rather than silently falling back to a different installation. - MSSQL behavior tests — Query the fixture's temporary tables with SQL Server syntax, distinguish empty values from SQL NULL using DB-Library indicators, use the MAX binary RPC type, and set the text-size limit so large LOB values are not truncated.
- Base 2.0 and backend diagnostics
- Migrated ownership and text types to Base Safe APIs and updated the public headers for the new Base include layout.
BeginTransactionnow convertsStormByte::Exceptionfailures intoTransactionErrorrather than falling through to the generic unknown-backend result.- Fixed misleading indentation in MariaDB long-long result handling so the switch branch is explicit and warning-free.
- Value conversion and binding correctness
- Reject floating-point to integer conversions outside the destination range before casting, including values that round to the unsigned or signed upper bound.
- Preserve zero-length SQLite and MariaDB BLOB bindings as empty BLOB values rather than SQL NULL.
- Reject excess MariaDB prepared-statement parameters consistently and preserve SQLite long-integer bind errors so failed parameter binding is reported by statement execution.
- Honor Base's full-length
Safe::Stringsemantics: SQLite rejects embedded NULs in queries, prepared SQL and database paths before native calls can truncate them. PostgreSQL rejects NUL-containing text binds rather than silently sending a prefix, and all network backends reject NUL-containing connection settings before login. - Reject SQLite text binds larger than
INT_MAXbefore converting the length passed to SQLite; length-bearing text binds continue preserving embedded NULs and empty text remains distinct from SQL NULL.
- Windows builds
- Avoid applying
dllimportvisibility to static Windows consumers; shared/export macros remain enabled only for shared builds. - Fixed clang-cl build failures in the SQLite, PostgreSQL and MariaDB prepared statements by fully qualifying the base
PreparedSTMTso it is not resolved against theDatabaseclass. - Fixed undefined SQLite symbols when linking the Windows DLL:
sqlite3andsqlite3_stmtare now forward-declared asstruct, matching SQLite's own declarations and MSVC name mangling. - Windows Release builds no longer use
/fp:fast, so NaN and infinity handling in value conversions follows IEEE semantics. - 64-bit integer results from SQLite, PostgreSQL and MariaDB are no longer truncated to the 32-bit Windows
long, which turned values such asUINT_MAXnegative and made reads throw.
- Avoid applying