Contributions for Firebird ODBC Driver

[fdcastel]

Hi Adriano!

I’m working on a full revamp of Firebird ODBC Driver and this library caught my eye. ❤️

May I ask you what's its current status? Are you planning to keep evolving it, or was it mainly a prototype?

I’d really like to use it in the ODBC driver; it could help us remove a lot of legacy code.

With a little help from Claude 😄 we jotted down a few topics we’d need to cover to move forward -- would you mind taking a look?

P.S. Of course, I'd be happy to contribute with PRs, as well.

---

Summary of Proposed Contributions

#	Feature	PR Size	Priority	Notes	Link	Status
2	Batch + BatchCompletionState classes	Large (~500 LOC + tests)	Critical	We'll implement & test	#26	✅ COMPLETED
3	CursorType in StatementOptions	Small (~20 LOC)	High	Trivial change	#25	✅ COMPLETED
8	Error vector in DatabaseException	Medium (~50 LOC + tests)	Critical	Non-breaking addition	#24	✅ COMPLETED
6	Move assignment for Statement + Attachment	Small (~30 LOC)	Medium	Enables container use	#36	✅ COMPLETED
5	alias field in Descriptor	Small (~10 LOC)	Medium	One new field	#37	✅ COMPLETED
7	Thread safety docs in README	Docs only	Low	After code PRs
10	ODBC-style example	Docs only	Low	After batch PR

---

📋 Suggestions for Improvement

1. Missing IResultSet Wrapper / Multi-Row Fetch

Issue: The Statement class has execute() and fetchNext(), but there's no separate ResultSet abstraction. This makes it awkward to:

• Differentiate between a statement that returns results vs. one that doesn't
• Pass a result set to another function without passing the statement
• Support multiple simultaneous result sets from the same statement (e.g., stored procedures returning multiple cursors)

Suggestion: Consider adding a ResultSet class that wraps IResultSet and is returned from Statement::execute() when the statement produces a result set. This matches the JDBC pattern (Statement.executeQuery() returns ResultSet).

Alternative: If keeping the single-class design, document that Statement::execute() returns true if there are results to fetch, and fetchNext() should only be called after execute() returns true.

---

2. Batch Execution (IBatch) Not Exposed

Issue: The Firebird 4.0+ IBatch interface enables high-performance bulk inserts with a single server roundtrip. This is critical for ETL workloads and ODBC array parameter binding. The current API requires calling execute() N times for N rows.

Suggestion: Add a Batch class or extend Statement with:

void Statement::addBatch();  // Queue current parameter values
BatchResult Statement::executeBatch();  // Execute all queued rows in one roundtrip

The BatchResult could expose per-row status (IBatchCompletionState::getState()).

Priority: High — this is the single biggest performance differentiator between naive row-by-row and professional-grade bulk operations.

---

3. No Scrollable Cursor Support

Issue: Statement only exposes fetchNext(), fetchPrior(), fetchFirst(), fetchLast(), fetchAbsolute(), fetchRelative(). However, these require opening the result set with IStatement::openCursor() specifying CURSOR_TYPE_SCROLLABLE. The current implementation uses CURSOR_TYPE_SCROLLABLE (line 167 of Statement.cpp), but this is always enabled even for forward-only queries.

Suggestion: Add a CursorType enum to StatementOptions:

enum class CursorType { FORWARD_ONLY, SCROLLABLE };

• Default to FORWARD_ONLY for performance (no server-side cursor buffering)
• When SCROLLABLE, call openCursor() with CURSOR_TYPE_SCROLLABLE

Note: We observed that execute() always passes IStatement::CURSOR_TYPE_SCROLLABLE. For forward-only streaming of large result sets, this forces the server to buffer all rows. Consider defaulting to 0 (forward-only) and only using CURSOR_TYPE_SCROLLABLE when scrollable methods are needed.

---

5. Missing Descriptor Metadata Access

Issue: The Descriptor struct in Descriptor.h contains rich metadata (type, scale, length, nullability, field/relation names). However:

• Statement::getInputDescriptors() and getOutputDescriptors() return const std::vector<Descriptor>&
• The Descriptor struct is only defined for read access — applications can't modify it for deferred binding

Suggestion: For ODBC drivers and similar adapters, we need:

1. Access to IMessageMetadata::getField(), getRelation(), getAlias() etc. — currently these are processed internally but not fully exposed
2. Ability to override input metadata (e.g., bind a string value as VARCHAR when the server expects INTEGER) — this requires IMetadataBuilder

Consider exposing:

• Statement::getInputMetadata() → FbRef<IMessageMetadata> (already exists!)
• Statement::getOutputMetadata() → FbRef<IMessageMetadata> (already exists!)
• A helper to build custom IMessageMetadata for input override scenarios

---

6. Statement Copy/Move Semantics

Issue: Statement is move-only (copy deleted, move-only). After a move, isValid() returns false. This is correct, but:

• Statement::operator=(Statement&&) is deleted — why? This prevents std::swap and vector/map usage
• The moved-from statement's statementHandle is moved but attachment reference becomes dangling

Suggestion: Either:

1. Make Statement fully movable (implement operator=(Statement&&))
2. Or document explicitly that Statement should be heap-allocated and managed via std::unique_ptr

---

7. Thread Safety Documentation

Issue: The library doesn't document thread safety guarantees. Questions:

• Is it safe to use one Client from multiple threads?
• Is it safe to use one Attachment from multiple threads with different Transactions?
• Is StatusWrapper thread-safe (it contains a dirty flag)?

Suggestion: Add a "Thread Safety" section to the documentation. Based on our reading of the code:

• Client appears thread-safe (only reads from master)
• Attachment is NOT thread-safe (shared Transaction state)
• Statement is NOT thread-safe (mutable inMessage/outMessage)

---

8. Error Message Localization

Issue: DatabaseException::what() returns the Firebird error message, which is localized based on the server's LC_MESSAGES setting. For ODBC drivers, we need access to:

• The raw ISC error vector (intptr_t*) for SQLSTATE mapping
• The SQLCODE (via IUtil::formatStatus() or equivalent)

Suggestion: Expose the raw error data in DatabaseException:

const std::vector<intptr_t>& getErrorVector() const;
int getSqlCode() const;  // Computed via IStatus::getErrors()

---

9. Missing IUtil Wrapper

Issue: Firebird's IUtil provides valuable utilities:

• formatStatus() — format error messages
• decodeDate()/encodeDate() — manual date conversion
• getClientVersion() — client library version
• getInt128()/getDecFloat16()/getDecFloat34() — type converters

Some of these are used internally (NumericConverter, CalendarConverter) but not exposed.

Suggestion: Consider exposing Client::getUtil() → fb::IUtil* or wrapping the most useful methods.

[fdcastel]

BTW with these items checked there's also an opportunity to kick off a DuckDB extension for Firebird.

That’s another item on my long to-do list -- and actually the original reason I asked about vcpkg support some months ago.

DuckDB is quickly becoming a major force in the database world. The upcoming 1.5 release (expected in the next few weeks) introduces a completely redesigned ODBC implementation -- and it already includes first-class support for Firebird.

[asfernandes]

Hi Adriano!

I’m working on a full revamp of Firebird ODBC Driver and this library caught my eye. ❤️

May I ask you what's its current status? Are you planning to keep evolving it, or was it mainly a prototype?

It's to keep evolving, it just need good use to streess it.

I’d really like to use it in the ODBC driver; it could help us remove a lot of legacy code.

Good!

With a little help from Claude 😄 we jotted down a few topics we’d need to cover to move forward -- would you mind taking a look?

P.S. Of course, I'd be happy to contribute with PRs, as well.

📋 Suggestions for Improvement

1. Missing IResultSet Wrapper / Multi-Row Fetch

Issue: The Statement class has execute() and fetchNext(), but there's no separate ResultSet abstraction. This makes it awkward to:

This project had private non-published versions before and I always used a separate ResultSet class, but here decided to not. It's not possible to have multiple active result sets opened from a single statement in Firebird.

• Differentiate between a statement that returns results vs. one that doesn't
• Pass a result set to another function without passing the statement
  *>
• Support multiple simultaneous result sets from the same statement (e.g., stored procedures returning multiple cursors)

Does not exist in Firebird.

Suggestion: Consider adding a ResultSet class that wraps IResultSet and is returned from Statement::execute() when the statement produces a result set. This matches the JDBC pattern (Statement.executeQuery() returns ResultSet).

Alternative: If keeping the single-class design, document that Statement::execute() returns true if there are results to fetch, and fetchNext() should only be called after execute() returns true.

Don't it already has that?

		///
		/// @brief Executes a prepared statement using the supplied transaction.
		/// @param transaction Transaction that will own the execution context.
		/// @return `true` when execution yields a record.
		///
		bool execute(Transaction& transaction);

2. Batch Execution (IBatch) Not Exposed

Issue: The Firebird 4.0+ IBatch interface enables high-performance bulk inserts with a single server roundtrip. This is critical for ETL workloads and ODBC array parameter binding. The current API requires calling execute() N times for N rows.

Suggestion: Add a Batch class or extend Statement with:

void Statement::addBatch(); // Queue current parameter values
BatchResult Statement::executeBatch(); // Execute all queued rows in one roundtrip
The BatchResult could expose per-row status (IBatchCompletionState::getState()).

Priority: High — this is the single biggest performance differentiator between naive row-by-row and professional-grade bulk operations.

Batch should be added.

3. No Scrollable Cursor Support

Issue: Statement only exposes fetchNext(), fetchPrior(), fetchFirst(), fetchLast(), fetchAbsolute(), fetchRelative(). However, these require opening the result set with IStatement::openCursor() specifying CURSOR_TYPE_SCROLLABLE. The current implementation uses CURSOR_TYPE_SCROLLABLE (line 167 of Statement.cpp), but this is always enabled even for forward-only queries.

Suggestion: Add a CursorType enum to StatementOptions:

enum class CursorType { FORWARD_ONLY, SCROLLABLE };

• Default to FORWARD_ONLY for performance (no server-side cursor buffering)
• When SCROLLABLE, call openCursor() with CURSOR_TYPE_SCROLLABLE

Note: We observed that execute() always passes IStatement::CURSOR_TYPE_SCROLLABLE. For forward-only streaming of large result sets, this forces the server to buffer all rows. Consider defaulting to 0 (forward-only) and only using CURSOR_TYPE_SCROLLABLE when scrollable methods are needed.

Ok.

5. Missing Descriptor Metadata Access

Issue: The Descriptor struct in Descriptor.h contains rich metadata (type, scale, length, nullability, field/relation names). However:

• Statement::getInputDescriptors() and getOutputDescriptors() return const std::vector<Descriptor>&
• The Descriptor struct is only defined for read access — applications can't modify it for deferred binding

Suggestion: For ODBC drivers and similar adapters, we need:

1. Access to IMessageMetadata::getField(), getRelation(), getAlias() etc. — currently these are processed internally but not fully exposed

Could be added.

3. Ability to override input metadata (e.g., bind a string value as VARCHAR when the server expects INTEGER) — this requires IMetadataBuilder>
   Consider exposing:

• Statement::getInputMetadata() → FbRef<IMessageMetadata> (already exists!)
• Statement::getOutputMetadata() → FbRef<IMessageMetadata> (already exists!)
• A helper to build custom IMessageMetadata for input override scenarios

Should be discussed.

6. Statement Copy/Move Semantics

Issue: Statement is move-only (copy deleted, move-only). After a move, isValid() returns false. This is correct, but:

• Statement::operator=(Statement&&) is deleted — why? This prevents std::swap and vector/map usage
• The moved-from statement's statementHandle is moved but attachment reference becomes dangling

Suggestion: Either:

1. Make Statement fully movable (implement operator=(Statement&&))
2. Or document explicitly that Statement should be heap-allocated and managed via std::unique_ptr

It should be movable.

7. Thread Safety Documentation

Issue: The library doesn't document thread safety guarantees. Questions:

Should be added.

• Is it safe to use one Client from multiple threads?

Yes, unless one thread is not deleting it.

• Is it safe to use one Attachment from multiple threads with different Transactions?

Should be.

• Is StatusWrapper thread-safe (it contains a dirty flag)?

No.

Suggestion: Add a "Thread Safety" section to the documentation. Based on our reading of the code:

• Client appears thread-safe (only reads from master)

• Attachment is NOT thread-safe (shared Transaction state)

What you mean?

• Statement is NOT thread-safe (mutable inMessage/outMessage)

It's not.

8. Error Message Localization

Issue: DatabaseException::what() returns the Firebird error message, which is localized based on the server's LC_MESSAGES setting. For ODBC drivers, we need access to:

• The raw ISC error vector (intptr_t*) for SQLSTATE mapping

Should be copied from original status and exposed.

• The SQLCODE (via IUtil::formatStatus() or equivalent)

Suggestion: Expose the raw error data in DatabaseException:

const std::vector<intptr_t>& getErrorVector() const;
int getSqlCode() const; // Computed via IStatus::getErrors()

9. Missing IUtil Wrapper

Issue: Firebird's IUtil provides valuable utilities:

• formatStatus() — format error messages
• decodeDate()/encodeDate() — manual date conversion
• getClientVersion() — client library version
• getInt128()/getDecFloat16()/getDecFloat34() — type converters

Some of these are used internally (NumericConverter, CalendarConverter) but not exposed.

Suggestion: Consider exposing Client::getUtil() → fb::IUtil* or wrapping the most useful methods.

It's already exposed, isn't it?

PS: Would be good to open different issues or PRs if it's going to have major discussion on each topic.

[fdcastel]

😉

---

Hi Adriano!

Thank you for taking the time to review our suggestions — your answers confirmed our reading of the code and clarified several points. Here's a round-2 that addresses your feedback and proposes concrete next steps.

We'd like to contribute PRs for the features below. We created a detailed plan at FB_CPP_PLAN.md with implementation specs for each item. Let us know if the approach looks reasonable before we start coding.

---

Item-by-Item Follow-Up

1 — ResultSet abstraction

"Not possible to have multiple active result sets from a single statement in Firebird."
"Don't it already has that?" (re: execute() returning true)

You're right — Firebird doesn't support multiple result sets from one statement, and execute() does return true when there's a row. The API is clear enough as-is; we withdraw this suggestion. We'll keep Statement as the single class.

Status: Withdrawn ✅

---

2 — Batch Execution (IBatch)

"Batch should be added."

Great! This is our highest priority contribution. We've already implemented IBatch integration in the ODBC driver directly against the raw Firebird OO API (Phase 9 of our plan), so we know the interface well. We'll port this knowledge into a clean fb-cpp Batch class.

Proposed design (detailed in FB_CPP_PLAN.md § Phase 1):

// BatchOptions — mirrors IXpbBuilder(BATCH) parameters
class BatchOptions {
    setMultiError(bool);
    setRecordCounts(bool);
    setBufferBytesSize(unsigned);
    setBlobPolicy(BlobPolicy);   // NONE, ID_ENGINE, ID_USER, STREAM
    setDetailedErrors(unsigned);
};

// Batch — wraps IBatch
class Batch {
    // Create from a prepared Statement (most common)
    Batch(Statement& stmt, Transaction& transaction, const BatchOptions& = {});
    // Create from an Attachment + SQL string (convenience)
    Batch(Attachment& att, Transaction& transaction, std::string_view sql,
          unsigned dialect = 3, const BatchOptions& = {});

    void add(unsigned count, const void* inBuffer);
    void addMessage();                           // add current Statement's inMessage
    BlobId addBlob(std::span<const std::byte>);  // inline blob
    void registerBlob(const BlobId& existing, BlobId& batchId);
    BatchCompletionState execute();
    void cancel();
    void close();
    unsigned getBlobAlignment();
    FbRef<fb::IMessageMetadata> getMetadata();
};

// BatchCompletionState — wraps IBatchCompletionState
class BatchCompletionState {
    unsigned getSize();
    int getState(unsigned pos);           // EXECUTE_FAILED or affected rows
    std::optional<unsigned> findError(unsigned pos);  // nullopt = NO_MORE_ERRORS
    // getStatus() for detailed error vectors — needed for ODBC SQLSTATE mapping
};

Key design decisions for your review:

1. Two constructors: from Statement (uses IStatement::createBatch) and from Attachment (uses IAttachment::createBatch). The Statement-based one is more common in ODBC usage.
2. An addMessage() convenience that adds the Statement's current inMessage buffer — so users can call stmt.setInt32(0, val); batch.addMessage(); in a loop.
3. BatchCompletionState is a value type (owns the IBatchCompletionState via RAII) — disposed in destructor.
4. BlobPolicy enum for the blob mode constants.

Questions for you:

• Should Batch take ownership of (or reference) the Transaction, or just use it at execute() time?
• For the Statement-based constructor, should we store a reference to the Statement and use its inMetadata automatically?

---

3 — Scrollable Cursor Control

"Ok."

Good. We noticed that Statement::execute() currently opens cursors with flag 0 (forward-only). The scrollable fetch methods (fetchPrior, fetchFirst, fetchLast, fetchAbsolute, fetchRelative) are already exposed but silently fail if the cursor was opened forward-only.

Proposed change (detailed in FB_CPP_PLAN.md § Phase 2):

Add a CursorType enum to StatementOptions:

enum class CursorType { FORWARD_ONLY, SCROLLABLE };

StatementOptions& setCursorType(CursorType value);

• Default: FORWARD_ONLY (current behavior, flag 0)
• When SCROLLABLE, pass IStatement::CURSOR_TYPE_SCROLLABLE to openCursor()
• Forward-only cursors are more efficient for streaming large result sets

PR scope: Small — ~20 lines of code change in StatementOptions + Statement.cpp.

---

5 — Descriptor Metadata Access

"Could be added." / "Should be discussed."

For our ODBC driver, we need two things from descriptors:

1. Relation name and alias — Descriptor already has field, relation, but not alias. ODBC's SQL_DESC_LABEL maps to the column alias. The Firebird IMessageMetadata has getAlias().

2. Input metadata override — ODBC allows binding a parameter as one type while the server expects another (e.g., bind SQL_C_CHAR to an INTEGER column). The ODBC layer handles conversion, but we need to build a custom IMessageMetadata for the input message. Currently exposed via Statement::getInputMetadata() — could you confirm we can use IMetadataBuilder externally for this, or would you prefer a helper in fb-cpp?

Proposed change: Add alias field to Descriptor. Small PR.

For IMetadataBuilder, we can use getInputMetadata() + Firebird's IMetadataBuilder directly. No fb-cpp wrapper needed immediately.

---

6 — Statement Move Assignment

"It should be movable."

We'll submit a small PR adding operator=(Statement&&) to both Statement and Attachment (both currently have it deleted). Same pattern as the existing move constructors.

---

7 — Thread Safety Documentation

"Should be added."

re: Client: "Yes, unless one thread is not deleting it."
re: Attachment: "Should be."
re: StatusWrapper: "No."
re: Attachment NOT thread-safe: "What you mean?"

Thank you for the clarifications! Our concern about Attachment thread safety was wrong — we were confused by the fact that StatusWrapper (which is per-object, not shared) is not thread-safe. Since each Statement and Transaction has its own StatusWrapper, using different Statements/Transactions on different threads against the same Attachment should be fine — each thread has its own status. The Attachment itself holds only client (read-only) and handle (thread-safe via Firebird's IAttachment contract).

We'll submit a PR adding a "Thread Safety" section to README.md:

• Client: thread-safe (read-only after construction)
• Attachment: safe to share; each thread should use its own Transaction / Statement
• Transaction, Statement, Blob: NOT thread-safe (per-object StatusWrapper)
• EventListener: thread-safe (internal mutex + condition variable)

---

8 — Error Vector in DatabaseException

"Should be copied from original status and exposed."

This is critical for us — ODBC requires mapping Firebird ISC error codes to SQLSTATE codes (e.g., isc_dsql_error → 42000, isc_deadlock → 40001). Currently DatabaseException only stores the formatted message string.

Proposed change (detailed in FB_CPP_PLAN.md § Phase 3):

class DatabaseException final : public FbCppException {
public:
    explicit DatabaseException(Client& client, const std::intptr_t* status);

    // NEW: access the raw error vector
    const std::vector<std::intptr_t>& getErrors() const noexcept;

    // NEW: access the SQLCODE (legacy, but ODBC uses it for mapping)
    int getSqlCode() const noexcept;

private:
    std::vector<std::intptr_t> errorVector_;  // deep copy of IStatus::getErrors()
    int sqlCode_ = 0;                          // computed via fb_sqlcode or IUtil
};

The status vector is copied in the constructor (before the IStatus is reused). getSqlCode() is computed from the error vector. This is a non-breaking change — existing code continues to work.

---

9 — IUtil Wrapper

"It's already exposed, isn't it?"

You're absolutely right! Client::getUtil() returns fb::IUtil* and it's public. We missed it. Sorry about the noise.

Status: Withdrawn ✅ — already exposed

---

10 — ODBC-Style Usage Example

This is lower priority and we can contribute it later once the Batch and error vector PRs are merged. We'll write a small example showing:

• Parameter binding with type override
• Batch insert with per-row status
• Chunked BLOB read
• Error vector → SQLSTATE mapping

---

— Firebird ODBC Driver Team, February 2026

FB_CPP_PLAN.md

[fdcastel]

PS: Would be good to open different issues or PRs if it's going to have major discussion on each topic.

FULLY agree! I’ll submit each PRs separately.

But now, just for the planning phase, it would be easier for me if we keep all the context together in one thread/document.

[fdcastel]

Thank you, @asfernandes. With these changes in place, I’ll resume working on the ODBC driver development, now aiming to adopt fb-cpp in it.