sqlgen/docs/result.md

sqlgen::Result

The sqlgen::Result type provides a way to handle errors without exceptions in sqlgen. It is an alias for rfl::Result and is used throughout sqlgen's API to handle potential failures in database operations.

Note that sqlgen::Result and rfl::Result are deliberately designed to resemble C++ 23's std::expected.

Usage

Basic Usage

Handle database operations that might fail:

// Reading from database
const auto people = sqlgen::read<std::vector<Person>>(conn);

if (people) {
    // Success case - use the value
    const auto& result = *people;
} else {
    // Error case - handle the error
    const auto& error = people.error();
}

// Writing to database
const auto write_result = sqlgen::write(conn, data);

if (!write_result) {
    // Handle write error
    const auto& error = write_result.error();
}

Safe Value Access

Access values safely using different methods:

const auto result = sqlgen::read<std::vector<Person>>(conn);

// Method 1: Using .value() (throws if error)
const auto person = result.value();

// Method 2: Using .value_or() (provides default if error)
const auto person = result.value_or(std::vector<Person>());

// Method 3: Using operator * (undefined if error)
if (result) {
    const auto& person = *result;
}

Monadic Operations

Chain operations using monadic functions:

// Transform successful results - note that this
// is not a particularly efficient way of counting, 
// but it highlights the point.
const auto count = sqlgen::read<std::vector<Person>>(conn)
    .transform([](const auto& people) {
        return people.size();
    });

// Chain operations that might fail
const auto result = sqlgen::sqlite::connect("database.db")
    .and_then(sqlgen::read<std::vector<Person>>);

Error Handling

Handle errors explicitly:

const auto result = sqlgen::read<std::vector<Person>>(conn);

// Check for errors
if (!result) {
    const auto& error = result.error();
    // Handle error...
}

// Transform errors
const auto better_error = result.transform_error([](const auto& e) {
    return sqlgen::error("Database error: " + e.what());
});

Notes

• sqlgen::Result is an alias for rfl::Result
• All database operations in sqlgen return Result types
• The type supports:
  • Safe value access with .value() and .value_or()
  • Monadic operations with .transform() and .and_then()
  • Error handling with .error()
  • Boolean checks for success/failure
  • Move and copy semantics
• It's recommended to handle errors explicitly rather than using .value() which throws exceptions