Feature - Retry Logic + Universal Logger (#6)

* Retry Wrapper for query()

* Internal Logger Impl

* Logs for Client and Connection Pool

Author: Calvinjmin

CMakeLists.txt

@@ -14,28 +14,30 @@ option(BUILD_EXAMPLES "Build example applications" ON)
 option(BUILD_TESTS "Build tests" OFF)
 option(BUILD_SHARED_LIBS "Build shared libraries" ON)
 
-# Find ODBC
+# Platform-specific configuration
 if(WIN32)
     # Windows uses odbc32
     set(ODBC_LIBRARIES odbc32)
-else()
-    # Unix/Linux/macOS uses unixODBC or iODBC
-    # Try to find ODBC using standard search paths
+elseif(APPLE)
+    # macOS: Prefer Homebrew paths on Apple Silicon
+    if(NOT CMAKE_PREFIX_PATH AND CMAKE_SYSTEM_PROCESSOR MATCHES "arm64")
+        list(PREPEND CMAKE_PREFIX_PATH "/opt/homebrew")
+    endif()
+
+    # Find ODBC using macOS paths
     find_path(ODBC_INCLUDE_DIR sql.h
         PATHS
             /opt/homebrew/include
             /usr/local/include
-            /usr/include
             /opt/local/include
         PATH_SUFFIXES odbc
         NO_DEFAULT_PATH)
 
     find_library(ODBC_LIBRARY
         NAMES odbc iodbc unixodbc
         PATHS
-            /opt/homebrew/lib 
+            /opt/homebrew/lib
             /usr/local/lib
-            /usr/lib
             /opt/local/lib
         NO_DEFAULT_PATH)
 
@@ -48,19 +50,50 @@ else()
         endif()
     else()
         message(FATAL_ERROR
-            "ODBC library not found. Please install the ODBC driver manager:\n"
-            "  macOS:   brew install unixodbc\n"
-            "  Linux:   sudo apt-get install unixodbc-dev (Debian/Ubuntu)\n"
-            "           sudo yum install unixODBC-devel (RedHat/CentOS)")
+            "ODBC library not found. Please install:\n"
+            "  brew install unixodbc")
+    endif()
+else()
+    # Linux: Use standard paths
+    find_path(ODBC_INCLUDE_DIR sql.h
+        PATHS
+            /usr/include
+            /usr/local/include
+        PATH_SUFFIXES odbc
+        NO_DEFAULT_PATH)
+
+    find_library(ODBC_LIBRARY
+        NAMES odbc unixodbc
+        PATHS
+            /usr/lib
+            /usr/local/lib
+        NO_DEFAULT_PATH)
+
+    if(ODBC_LIBRARY)
+        set(ODBC_LIBRARIES ${ODBC_LIBRARY})
+        message(STATUS "Found ODBC library: ${ODBC_LIBRARY}")
+        if(ODBC_INCLUDE_DIR)
+            set(ODBC_INCLUDE_DIRS ${ODBC_INCLUDE_DIR})
+            message(STATUS "Found ODBC include: ${ODBC_INCLUDE_DIR}")
+        endif()
+    else()
+        message(FATAL_ERROR
+            "ODBC library not found. Please install:\n"
+            "  Debian/Ubuntu: sudo apt-get install unixodbc-dev\n"
+            "  RedHat/CentOS: sudo yum install unixODBC-devel")
     endif()
 endif()
 
+# External libraries
+find_package(spdlog CONFIG REQUIRED)
+
 # Library sources
 set(SOURCES
     src/client.cpp
     src/config.cpp
     src/connection_pool.cpp
     src/internal/pool_manager.cpp
+    src/internal/logger.cpp
 )
 
 set(HEADERS
@@ -73,6 +106,7 @@ set(HEADERS
 # Internal headers (not installed)
 set(INTERNAL_HEADERS
     src/internal/pool_manager.h
+    src/internal/logger.h
 )
 
 # Create library target
@@ -88,7 +122,10 @@ target_include_directories(databricks_sdk
 )
 
 # Link ODBC libraries
-target_link_libraries(databricks_sdk PRIVATE ${ODBC_LIBRARIES})
+target_link_libraries(databricks_sdk PRIVATE 
+    ${ODBC_LIBRARIES}
+    spdlog::spdlog
+)
 
 # Set library properties
 set_target_properties(databricks_sdk PROPERTIES

README.md

@@ -113,11 +113,12 @@ The SDK uses a modular configuration system with separate concerns for authentic
 
 #### Configuration Structure
 
-The SDK separates configuration into three distinct concerns:
+The SDK separates configuration into four distinct concerns:
 
 - **`AuthConfig`**: Core authentication (host, token, timeout) - shared across all Databricks features
 - **`SQLConfig`**: SQL-specific settings (http_path, ODBC driver name)
 - **`PoolingConfig`**: Optional connection pooling settings (enabled, min/max connections)
+- **`RetryConfig`**: Optional automatic retry settings (enabled, max attempts, backoff strategy)
 
 This modular design allows you to:
 - Share `AuthConfig` across different Databricks service clients (SQL, Workspace, Delta, etc.)
@@ -267,6 +268,61 @@ int main() {
 
 **Note**: Multiple Clients with the same config automatically share the same pool!
 
+### Automatic Retry Logic (Reliability)
+
+The SDK includes automatic retry logic with exponential backoff for transient failures:
+
+```cpp
+#include <databricks/client.h>
+
+int main() {
+    // Configure retry behavior
+    databricks::RetryConfig retry;
+    retry.enabled = true;                 // Enable retries (default: true)
+    retry.max_attempts = 5;               // Retry up to 5 times (default: 3)
+    retry.initial_backoff_ms = 200;       // Start with 200ms delay (default: 100ms)
+    retry.backoff_multiplier = 2.0;       // Double delay each retry (default: 2.0)
+    retry.max_backoff_ms = 10000;         // Cap at 10 seconds (default: 10000ms)
+    retry.retry_on_timeout = true;        // Retry timeout errors (default: true)
+    retry.retry_on_connection_lost = true;// Retry connection errors (default: true)
+
+    // Build client with retry configuration
+    auto client = databricks::Client::Builder()
+        .with_environment_config()
+        .with_retry(retry)
+        .build();
+
+    // Queries automatically retry on transient errors
+    auto results = client.query("SELECT * FROM my_table");
+
+    return 0;
+}
+```
+
+**Retry Features:**
+- **Exponential backoff** with jitter to prevent thundering herd
+- **Intelligent error classification** - only retries transient errors:
+  - Connection timeouts and network errors
+  - Server unavailability (503, 502, 504)
+  - Rate limiting (429 Too Many Requests)
+- **Non-retryable errors** fail immediately:
+  - Authentication failures
+  - SQL syntax errors
+  - Permission denied errors
+- **Enabled by default** with sensible defaults
+- **Works with connection pooling** for maximum reliability
+
+**Disable Retries (if needed):**
+```cpp
+databricks::RetryConfig no_retry;
+no_retry.enabled = false;
+
+auto client = databricks::Client::Builder()
+    .with_environment_config()
+    .with_retry(no_retry)
+    .build();
+```
+
 ### Mixing Configuration Approaches
 
 The Builder pattern allows you to mix automatic and explicit configuration:
@@ -493,9 +549,14 @@ Async operations reduce perceived latency by performing work in the background:
 
 1. **Enable pooling** via `PoolingConfig` for applications making multiple queries
 2. **Use async operations** when you can do other work while waiting
-3. **Combine both** for maximum performance in concurrent scenarios
-4. **Size pools appropriately**: min = typical concurrent load, max = peak load
-5. **Share configs**: Clients with identical configs automatically share pools
+3. **Enable retry logic** (on by default) for production reliability against transient failures
+4. **Combine pooling + retries** for maximum reliability and performance
+5. **Size pools appropriately**: min = typical concurrent load, max = peak load
+6. **Share configs**: Clients with identical configs automatically share pools
+7. **Tune retry settings** based on your workload:
+   - High-throughput: Lower `max_attempts` (2-3) to fail fast
+   - Critical operations: Higher `max_attempts` (5-7) for maximum reliability
+   - Rate-limited APIs: Increase `initial_backoff_ms` and `max_backoff_ms`
 
 ## Advanced Usage
 

include/databricks/client.h

@@ -116,6 +116,29 @@ namespace databricks
              */
             Builder& with_auto_connect(bool enable = true);
 
+            /**
+             * @brief Set retry configuration for automatic error recovery
+             *
+             * Configures how the client handles transient failures like connection
+             * timeouts and network errors. When enabled, failed operations will be
+             * automatically retried with exponential backoff.
+             *
+             * @param retry Retry configuration
+             * @return Builder reference for chaining
+             *
+             * @code
+             * databricks::RetryConfig retry;
+             * retry.max_attempts = 5;
+             * retry.initial_backoff_ms = 200;
+             *
+             * auto client = databricks::Client::Builder()
+             *     .with_environment_config()
+             *     .with_retry(retry)
+             *     .build();
+             * @endcode
+             */
+            Builder& with_retry(const RetryConfig& retry);
+
             /**
              * @brief Build the Client
              *
@@ -128,6 +151,7 @@ namespace databricks
             std::unique_ptr<AuthConfig> auth_;
             std::unique_ptr<SQLConfig> sql_;
             std::unique_ptr<PoolingConfig> pooling_;
+            std::unique_ptr<RetryConfig> retry_;
             bool auto_connect_ = false;
         };
 
@@ -239,7 +263,7 @@ namespace databricks
 
     private:
         // Private constructor for Builder
-        Client(const AuthConfig& auth, const SQLConfig& sql, const PoolingConfig& pooling, bool auto_connect);
+        Client(const AuthConfig& auth, const SQLConfig& sql, const PoolingConfig& pooling, const RetryConfig& retry, bool auto_connect);
 
         class Impl;
         std::unique_ptr<Impl> pimpl_;

include/databricks/config.h

@@ -101,4 +101,41 @@ namespace databricks
         bool is_valid() const;
     };
 
+    /**
+     * @brief Retry configuration for automatic error recovery
+     *
+     * Configures automatic retry behavior for transient failures such as
+     * connection timeouts, network errors, and rate limits. Uses exponential
+     * backoff to avoid overwhelming the server during retries.
+     *
+     * Example usage:
+     * @code
+     * databricks::RetryConfig retry;
+     * retry.enabled = true;
+     * retry.max_attempts = 5;
+     * retry.initial_backoff_ms = 200;
+     *
+     * auto client = databricks::Client::Builder()
+     *     .with_environment_config()
+     *     .with_retry(retry)
+     *     .build();
+     * @endcode
+     */
+    struct RetryConfig
+    {
+        bool enabled = true;                    ///< Enable automatic retries (default: true)
+        size_t max_attempts = 3;                ///< Maximum retry attempts (default: 3)
+        size_t initial_backoff_ms = 100;        ///< Initial backoff in milliseconds (default: 100ms)
+        double backoff_multiplier = 2.0;        ///< Exponential backoff multiplier (default: 2x)
+        size_t max_backoff_ms = 10000;          ///< Maximum backoff cap (default: 10s)
+        bool retry_on_timeout = true;           ///< Retry on connection timeout (default: true)
+        bool retry_on_connection_lost = true;   ///< Retry on connection errors (default: true)
+
+        /**
+         * @brief Validate configuration values
+         * @return true if valid, false otherwise
+         */
+        bool is_valid() const;
+    };
+
 } // namespace databricks