StormByte-Database

This repository is StormByte Database: the C++26 SQL layer of the StormByte suite.

One API covers SQLite, PostgreSQL and MariaDB. You do not construct those backends as generic objects. They are base classes: derive your schema, call the backend constructor, prepare statements and hook connect/disconnect there.

The suite is split on purpose. Base, Buffer, Config, Crypto, Logger, Multimedia, Network and System are other repositories.

What this module does

• One connection type — StormByte::Database::Database with Connect / Disconnect, Query / SilentQuery, named prepared statements and RAII transactions.
• Inheritance first — SQLite3, MariaDB and Postgres constructors are protected. Your application database is a subclass.
• Values — type-erased Value (NULL, integers, double, text, blob, bool) with safe numeric Get<T>().
• Rows — ordered columns, lookup by name (ColumnNotFound / OutOfBounds).
• Prepared statements — bind by position (0-based), nullptr is SQL NULL, ExpectedRows on execute.
• Transactions — BeginTransaction(IsolationLevel) returns a Transaction that rolls back if you forget Commit.
• TLS — SslMode for MariaDB and PostgreSQL. SQLite ignores it.
• Not thread-safe — one connection per thread.

The rest of the suite

Module	Role	API
Base	Exceptions, Expected, serialization, strings, UUID, concepts	/StormByte
Buffer	FIFO, SharedFIFO, Ring, Producer/Consumer and multi-stage pipelines	/StormByte-Buffer
Config	Human-readable text and versioned binary documents (groups, lists, raw bytes)	/StormByte-Config
Crypto	Hash, compress, encrypt, sign and key agreement — Crypto++ never leaves the private tree	/StormByte-Crypto
Database	This repository	/StormByte-Database
Logger	Stream logger with levels, headers, human-readable sizes and redaction (ThreadedLog)	/StormByte-Logger
Multimedia	Decode, encode and containers without raw FFmpeg types; codecs enabled only if present	/StormByte-Multimedia
Network	Framed packets, Client/Server, IPv4/IPv6 TCP and Buffer pipelines (compress/encrypt)	/StormByte-Network
System	Processes, pipes and environment variables across Linux, Windows and macOS	/StormByte-System

Table of Contents

• What this module does
• The rest of the suite
• Installation
• Usage
  • Derive your database
  • Values and rows
  • Queries and statements
  • Transactions
• Contributing
• License

Installation

Needs a C++26 compiler, CMake 3.28 or newer, StormByte Base 1.1.0 and StormByte-Logger 1.1.0. Database exceptions use the component-aware exception API introduced in Base 1.1.0. Enable the backends you want (WITH_SQLITE, WITH_POSTGRES, WITH_MARIADB: OFF, SYSTEM or BUNDLED); SYSTEM discovers installed connectors and BUNDLED builds them.

git clone https://github.com/StormBytePP/StormByte-Database.git
cd StormByte-Database
cmake -S . -B build
cmake --build build

Usage

Headers are #include <StormByte/database/….hxx>. Namespace root is StormByte::Database. Moving a connected backend transfers ownership of its connection; the moved-from backend is disconnected.

Derive your database

#include <StormByte/database/sqlite/sqlite3.hxx>
#include <StormByte/logger/log.hxx>
 
class AppDb : public StormByte::Database::SQLite::SQLite3 {
public:
    AppDb(std::shared_ptr<StormByte::Logger::Log> log)
        : SQLite3(std::filesystem::path{"app.db"}, log) {}
 
protected:
    void DoPostConnect() noexcept override {
        EnableForeignKeys();
        PrepareSTMT("user_by_id", "SELECT id, name FROM users WHERE id = ?");
    }
};
 
int main() {
    AppDb db(nullptr);
    if (!db.Connect())
        return 1;
 
    auto rows = db.Query("SELECT 1 AS n");
    if (!rows)
        return 1;
}

MariaDB / Postgres follow the same pattern: subclass, pass host / user / password / database (and port on MariaDB), optionally SetSslMode before Connect(). PostgreSQL connection parameters are passed separately, so credentials may contain quotes and backslashes.

Values and rows

#include <StormByte/database/value.hxx>
 
using namespace StormByte::Database;
 
Value n(42);
Value empty;          // SQL NULL
auto i = n.Get<int>();
if (auto row = /* from Query */) {
    const Value& name = (*row)[0]["name"];
}

Malformed or out-of-range numeric values returned by a backend are reported through ExpectedRows as query errors.

Queries and statements

auto result = db.ExecuteSTMT("user_by_id", 7);
if (!result)
    return 1;
 
for (const auto& row : *result) {
    auto id = row["id"].Get<int>();
}

nullptr binds SQL NULL. Missing statement names raise UnknownSTMT through ExpectedRows.

Transactions

{
    auto tx = db.BeginTransaction(IsolationLevel::Serializable);
    db.SilentQuery("INSERT INTO users(name) VALUES ('ada')");
    tx.Commit();
} // Rollback if Commit was not called

Contributing

Issues only on this repository. Fork and open a pull request against master.

License

GNU Lesser General Public License version 3 or later. See [LICENSE](LICENSE) and https://www.gnu.org/licenses/lgpl-3.0.html.