fb-cpp

A modern C++ wrapper for the Firebird database API.

Documentation | Repository | DeepWiki

Overview

fb-cpp provides a clean, modern C++ interface to the Firebird database engine. It wraps the Firebird C++ API with RAII principles, smart pointers, and modern C++ features.

Features

• Modern C++: Uses C++20 features for type safety and performance
• RAII: Automatic resource management with smart pointers
• Type Safety: Strong typing for database operations
• Exception Safety: Proper error handling with exceptions
• Boost Integration: Optional Boost.DLL for loading fbclient and Boost.Multiprecision support for large numbers

Quick Start

#include "fb-cpp/fb-cpp.h"

using namespace fbcpp;

// Create a client
Client client{"fbclient"};

// Connect to a database
const auto attachmentOptions = AttachmentOptions()
    .setConnectionCharSet("UTF8");
Attachment attachment{client, "localhost:database.fdb", attachmentOptions};

// Start a transaction
const auto transactionOptions = TransactionOptions()
    .setIsolationLevel(TransactionIsolationLevel::READ_COMMITTED);
Transaction transaction{attachment, transactionOptions};

// Prepare a statement
Statement statement{attachment, transaction, "select id, name from users where id = ?"};

// Set parameters
statement.setInt32(0, 42);
/*
// Or:
statement.set(0, 42);

// Or:
statement.set(SomeStructOrTuple{42});
*/

// Execute and get results
if (statement.execute(transaction))
{
    // Process results...
    do
    {
        const std::optional<std::int32_t> id = statement.getInt32(0);
        const std::optional<std::string> name = statement.getString(1);

        /*
        // Or:
        const auto id = statement.get<std::int32_t>(0);
        const auto name = statement.get<std::string>(1);

        // Or:
        const auto [id, name] = statement.get<SomeStructOrTuple>();
        */
    } while (statement.fetchNext());
}

// Commit transaction
transaction.commit();

Using with vcpkg

This library is present in firebird-vcpkg-registry.

To install, add the registry or overlay to your vcpkg configuration and install the fb-cpp package:

vcpkg install fb-cpp

Or add it to your vcpkg.json manifest:

{
  ...
  "dependencies": [
    {
      "name": "fb-cpp",
      "default-features": true
    }
  ]
}

The default features are:

• boost-dll: Enable Boost.DLL support for runtime dynamic loading of Firebird client library
• boost-multiprecision: Enable Boost.Multiprecision support for INT128 and DECFLOAT types

Building

This project uses CMake presets (CMakePresets.json) and vcpkg for dependency management.

Copy the appropriate CMakeUserPresets.json.<platform>.template file to CMakeUserPresets.json to set environment variables for tests and define the default preset.

# Configure
cmake --preset default

# Build
cmake --build --preset default

# Run tests
ctest --preset default

# Build docs
cmake --build --preset default --target docs

Firebird 2.5 Legacy API Support

fb-cpp can also be built against the Firebird 2.5 legacy C API instead of the default Firebird 3.0+ OO API.

Building with Firebird 2.5

Since Firebird 2.5 is not available via vcpkg, you must provide the include and library paths manually:

cmake -DFB_CPP_FIREBIRD_LEGACY=ON \
      -DFIREBIRD_INCLUDE_DIR=/path/to/firebird2/include \
      -DFIREBIRD_LIBRARY=/path/to/libfbclient.so \
      -B build .

cmake --build build

Feature Differences

When building with FB_CPP_FIREBIRD_LEGACY=ON, the following features are not available:

• INT128, DecFloat16, DecFloat34 types
• BOOLEAN type
• TIMESTAMP WITH TIME ZONE
• Blob class
• EventListener class

Basic operations (connect, transactions, prepared statements, standard SQL types) work identically.

Compile-Time Detection

Use the FB_CPP_LEGACY_API preprocessor macro to conditionally compile code:

#if FB_CPP_LEGACY_API
    // Firebird 2.5 specific code
#else
    // Firebird 3.0+ specific code
#endif

Documentation

The complete API documentation is available in the build doc/docs/ directory after building with the docs target.

License

MIT License - see LICENSE.md for details.

Donation

If this project help you reduce time to develop, you can show your appreciation with a donation.

• GitHub Sponsor: https://github.com/sponsors/asfernandes
• Pix (Brazil): 278dd4e5-8226-494d-93a9-f3fb8a027a99
• BTC: 1Q1W3tLD1xbk81kTeFqobiyrEXcKN1GfHG
•