dwh 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 899fb3e403f0362cb21132d9af44f622e870b339776aac7bd4d3e7ed333d59e4
-  data.tar.gz: a3d536eb6da5885d4817be013d80e6b5a5ed422bce1466ac582c2b478724e278
+  metadata.gz: e782fe9e0167d10f1672d0ce2b1601445cd0484c2e9b68b46df11be0cd0f20ca
+  data.tar.gz: 795f5cb0173413e2a475b216f824aed8b0de975a4abb39e30fa27f7cccb9f779
 SHA512:
-  metadata.gz: 5703c4ee14bf336b92f15740bfd0a6bce086ac9b636d67bcf269ea337a550a80bdd6a2f9d4265dd0a476d8d693a313dd2e6c8fa2fc587ea0f4653f6e0b528860
-  data.tar.gz: fa72a56f3eac7c5b4eae524a70b002f93b23e54513209d182de92e119aa43ea57a08d31d0f183b19d7df36601472045d9d2a001b26dda8bd56ee886556d4b21e
+  metadata.gz: f42b78511e879191933ff87b4441041b63541413c37f3f308a4854564f278ef4e8ff91e7547a573f03104e37e4fb068e187ee5d3cbab9fe834dbf129b27f68ac
+  data.tar.gz: ef6f624c3e0f7f2dfd9deff755af97d28798aed6c8c8ddea474899fbb02f079bfc4a80772ddb2048e9d0777da4f5a508a51ede9669159082758f8019e523bb08

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-04-28
+
+### Added
+
+- Token persistence interface via `DWH::TokenStore` for adapters that support OAuth token lifecycle management.
+- `TokenManageable` adapter concern for standardized token read/write behavior across adapters.
+- PKCE-based U2M OAuth support for the Databricks adapter.
+- Expanded tests for OAuth and Databricks token flows.
+
+### Changed
+
+- Databricks adapter now requires explicit `auth_mode` to reduce ambiguous auth configuration.
+- Updated documentation for adapter auth/token usage and adapter authoring.
+
+## [0.3.0] - 2026-04-22
+
+### Changed
+
+- Added Databricks Adapter
+
+## [0.2.1] - 2025-01-27
+
+### Changed
+
+- **Adapter missing-gem error messages** (Athena, DuckDB, MySQL, PostgreSQL, SQL Server, Trino): replace platform-specific system library install instructions with links to official documentation. Messages now include `gem install` and a single link for system libraries.
+
 ## [0.2.0] - 2025-10-12
 
 ### Added

data/docs/guides/adapters.md

@@ -179,7 +179,7 @@ adapter = DWH.create(:snowflake, {
   account_identifier: 'myorg-myaccount.us-east-1',
   oauth_client_id: '<YOUR_CLIENT_ID>',
   oauth_client_secret: '<YOUR_CLIENT_SECRET>',
-  oauth_redirect_url: 'https://localhost:3030/some/path',
+  oauth_redirect_uri: 'https://localhost:3030/some/path',
   database: 'ANALYTICS',
   client_name: 'myapp' # sent as user agent header value
 })
@@ -189,10 +189,92 @@ To successfully use OAuth you have to pass the adapter valid access and refresh
 
 The typical flow is like so:
 
-1. Generate an authorization code by visiting the url generated by `adapter.authorization_url.`  This will redirect to the configured `oauth_redirect_url.`  You must be able to retrieve the `code` from there.
+1. Generate an authorization code by visiting the url generated by `adapter.authorization_url.`  This will redirect to the configured `oauth_redirect_uri.`  You must be able to retrieve the `code` from there.
 2. Take the code from above and generate new access tokens: `adapter.generate_oauth_tokens(code)`. This will return Hash with access_token and refresh_token.  You can cache and reuse this until the refresh_token gets expired. This method will also apply the token to the current adapter instance.
 3. You can apply an existing set of tokens like so:`adapter.apply_oauth_tokens(access_token: token, refresh_token: token, expires_at: Time.now)`
 
+### Host integration contract (CLI / server)
+
+The host application is responsible for orchestration and persistence. DWH is responsible for OAuth protocol calls and token lifecycle methods.
+
+Public OAuth methods you can call on adapters that include `OpenAuthorizable`:
+
+- `authorization_url(state:, scope:)` - build provider authorize URL (authorization-code flow only)
+- `generate_oauth_tokens(code)` - exchange auth code for tokens and apply/store them
+- `apply_oauth_tokens(access_token:, refresh_token:, expires_at:)` - inject tokens from host storage
+- `oauth_access_token` - get a usable access token (load/refresh/mint as needed)
+- `refresh_access_token` - explicitly refresh using current refresh token
+- `mint_access_token` - explicitly mint via client credentials (M2M only)
+- `oauth_token_info` - inspect current token state
+
+Host requirements:
+
+1. Build and pass adapter config to `DWH.create(...)`, including correct `auth_mode` and OAuth fields.
+2. For U2M, implement browser redirect + callback capture, then call `generate_oauth_tokens(code)`.
+3. Validate OAuth `state` in the host callback handler (DWH does not enforce callback state verification).
+4. Persist tokens either by:
+   - passing a `token_store` object (`load`, `store`, `delete`), or
+   - storing tokens externally and rehydrating with `apply_oauth_tokens`.
+5. Handle auth exceptions and trigger reconnect UX when needed (for example, expired/invalid refresh token).
+
+Call order by mode:
+
+- **M2M (`oauth_m2m`)**
+  1. `adapter = DWH.create(...)`
+  2. Run query/test methods (`execute`, `test_connection`, etc.)
+  3. DWH internally calls `oauth_access_token`, which mints or refreshes as required
+
+- **U2M (`oauth_u2m`)**
+  1. `adapter = DWH.create(...)`
+  2. `url = adapter.authorization_url(...)`
+  3. Host sends user to URL and receives callback with `code`
+  4. `adapter.generate_oauth_tokens(code)`
+  5. Run query/test methods; DWH reuses and refreshes tokens as needed
+
+Note: for PKCE-enabled U2M providers, call `authorization_url` and `generate_oauth_tokens` on the same adapter instance.
+
+## Databricks
+
+The Databricks adapter uses the SQL Statements REST API and supports OAuth with
+both machine-to-machine (M2M) and user-to-machine (U2M) authorization-code flow.
+Set `auth_mode` explicitly to select the flow.
+
+### Basic configuration
+
+```ruby
+adapter = DWH.create(:databricks, {
+  host: 'workspace.cloud.databricks.com',
+  auth_mode: 'oauth_m2m',
+  warehouse: 'warehouse_id',
+  oauth_client_id: '<CLIENT_ID>',
+  oauth_client_secret: '<CLIENT_SECRET>',
+  catalog: 'main',
+  schema: 'default'
+})
+```
+
+### M2M (service principal) flow
+
+Set `auth_mode: 'oauth_m2m'`. The adapter mints access tokens using
+`grant_type=client_credentials`.
+
+### U2M (authorization code) flow
+
+Set `auth_mode: 'oauth_u2m'` and provide `oauth_redirect_uri` in config, then run:
+
+1. Generate authorize URL from `adapter.authorization_url`
+2. Capture `code` from redirect callback
+3. Exchange with `adapter.generate_oauth_tokens(code)`
+
+When U2M is active, PKCE is applied automatically by the adapter.
+
+### Migration note
+
+Databricks now requires explicit `auth_mode`.
+
+- Existing service-principal setups should set `auth_mode: 'oauth_m2m'`
+- U2M setups should set `auth_mode: 'oauth_u2m'` and provide `oauth_redirect_uri`
+
 ## MySQL Adapter
 
 The MySQL adapter uses the `mysql2` gem. Note that MySQL's concept of "database" maps to "schema" in DWH.

data/docs/guides/creating-adapters.md

@@ -363,6 +363,49 @@ end
 
 ## Advanced Features
 
+### Identity-Bound Token Store Integration
+
+Adapters that use OAuth/M2M token exchange can support host-managed persistence by
+accepting `token_store` in adapter config and using base helpers from `Adapter`.
+
+`token_store` should be identity-bound by the host app (for example datasource-bound
+for service accounts, user+datasource-bound for per-user OAuth). The adapter should
+not parse or infer identity keys.
+
+```ruby
+class MyOAuthAdapter < Adapter
+  config :token_store, Object, required: false, default: nil
+
+  def access_token
+    payload = load_tokens_from_store
+    apply_token_payload(payload) if payload
+    return @access_token if @access_token && !token_expired?
+
+    token = request_new_token!
+    store_tokens_in_store(
+      access_token: token[:access_token],
+      refresh_token: token[:refresh_token],
+      expires_at: token[:expires_at]
+    )
+    @access_token
+  end
+end
+```
+
+Expected token-store methods:
+
+- `load` -> returns `nil` or hash with `access_token`, optional `refresh_token`, and `expires_at`
+- `store(token_hash)` -> persists latest token payload
+- `delete` -> optional revoke/cleanup hook for terminal auth failures
+
+For OAuth adapters, keep token persistence centralized and only override provider hooks:
+
+- `oauth_supports_authorization_code_flow?` -> `true` for U2M flows
+- `oauth_supports_client_credentials_flow?` -> `true` for M2M flows
+- `oauth_client_credentials_params` -> provider-specific client-credentials form body
+- `oauth_tokenization_url` -> provider token endpoint
+- `oauth_token_expiry_leeway_seconds` -> eager refresh buffer (for near-expiry tokens)
+
 ### Error Handling
 
 ```ruby

data/docs/guides/usage.md

@@ -341,6 +341,71 @@ readonly_analytics = DWH.create(:sqlite, {
 })
 ```
 
+## Identity-Bound Token Stores
+
+For OAuth and M2M adapters, DWH can optionally reuse tokens through a host-provided
+`token_store` object. The store should be identity-bound before it is passed into
+adapter config so DWH remains agnostic of app-level user/datasource models.
+
+### Token Store Contract
+
+`DWH::TokenStore` is the reference contract, but duck-typed objects are supported.
+
+```ruby
+class MyTokenStore < DWH::TokenStore
+  def load
+    # return nil or hash with:
+    # access_token (optional), refresh_token (optional), expires_at (optional)
+    #
+    # Notes:
+    # - providing expires_at enables proactive refresh/mint behavior
+    # - providing refresh_token enables refresh when access_token expires
+  end
+
+  def store(token)
+    # token includes at least access_token and expires_at
+  end
+
+  def delete
+    # optional cleanup/revoke path for terminal auth failures
+  end
+end
+```
+
+### Service Account (M2M) Example
+
+```ruby
+store = DatasourceTokenStore.new(datasource_id: datasource.id)
+
+client = DWH.create(:databricks, {
+  host: datasource.host,
+  auth_mode: 'oauth_m2m',
+  warehouse: datasource.warehouse,
+  oauth_client_id: datasource.oauth_client_id,
+  oauth_client_secret: datasource.oauth_client_secret,
+  token_store: store
+})
+```
+
+### Per-User OAuth Example (host-owned)
+
+```ruby
+store = UserDatasourceTokenStore.new(
+  user_id: current_user.id,
+  datasource_id: datasource.id
+)
+
+client = DWH.create(:snowflake, {
+  auth_mode: 'oauth',
+  account_identifier: datasource.account_identifier,
+  database: datasource.database,
+  oauth_client_id: datasource.oauth_client_id,
+  oauth_client_secret: datasource.oauth_client_secret,
+  oauth_redirect_uri: datasource.oauth_redirect_uri,
+  token_store: store
+})
+```
+
 ## Error Handling and Debugging
 
 ### Comprehensive Error Handling

data/lib/dwh/adapters/athena.rb

@@ -202,8 +202,15 @@ module DWH
       def valid_config?
         super
         require 'aws-sdk-athena'
+        require 'aws-sdk-s3'
       rescue LoadError
-        raise ConfigError, "Required 'aws-sdk-athena' and 'aws-sdk-s3' gems missing. Please add them to your Gemfile."
+        raise ConfigError, <<~MSG
+          Athena adapter requires the 'aws-sdk-athena' and 'aws-sdk-s3' gems.
+
+          Install with: gem install aws-sdk-athena aws-sdk-s3
+
+          No system libraries required (pure Ruby).
+        MSG
       end
 
       private

data/lib/dwh/adapters/databricks.rb

@@ -0,0 +1,338 @@
+require 'csv'
+require_relative 'open_authorizable'
+
+module DWH
+  module Adapters
+    # Databricks adapter for executing SQL queries against Databricks SQL warehouses.
+    #
+    # Supports OAuth M2M (service principal) and U2M (authorization code) flows.
+    # The host application must set auth_mode explicitly:
+    # - oauth_m2m: client_credentials flow
+    # - oauth_u2m: authorization_code + PKCE flow
+    #
+    # @example Connection with OAuth (service principal)
+    #   DWH.create(:databricks, {
+    #     host: 'adb-1234567890123456.7.azuredatabricks.net',
+    #     warehouse: 'abc123def456',
+    #     oauth_client_id: 'service-principal-app-id',
+    #     oauth_client_secret: 'your-oauth-secret-here',
+    #     catalog: 'main',
+    #     schema: 'default'
+    #   })
+    class Databricks < Adapter
+      include OpenAuthorizable
+
+      oauth_with authorize: ->(adapter) { "https://#{adapter.host}/oidc/v1/authorize" },
+                 tokenize: ->(adapter) { "https://#{adapter.host}/oidc/v1/token" },
+                 default_scope: 'all-apis'
+
+      config :host, String, required: true, message: 'Databricks workspace host (e.g., adb-xxx.databricks.cloud.com)'
+      config :auth_mode, String, required: true, allowed: %w[oauth_m2m oauth_u2m],
+                                 message: 'Authentication mode: oauth_m2m or oauth_u2m'
+      config :oauth_client_id, String, required: true, message: 'OAuth client ID (service principal application ID)'
+      config :oauth_client_secret, String, required: true, message: 'OAuth client secret'
+      config :client_name, String, required: false, default: 'Ruby DWH Gem', message: 'Client name sent to Databricks'
+      config :query_timeout, Integer, required: false, default: 3600, message: 'Query execution timeout in seconds'
+      config :warehouse, String, required: true, message: 'Databricks SQL warehouse ID to use for query execution'
+      config :catalog, String, required: false, message: 'Default catalog (Unity Catalog)'
+      config :schema, String, required: false, message: 'Default schema'
+
+      DEFAULT_POLL_INTERVAL = 0.25
+      MAX_POLL_INTERVAL = 30
+
+      STATEMENTS_API = '/api/2.0/sql/statements'.freeze
+
+      def initialize(config)
+        super
+        validate_oauth_config
+      end
+
+      def connection
+        return @connection if @connection && !token_expired?
+
+        reset_connection if token_expired?
+        @connection = Faraday.new(
+          url: "https://#{workspace_host}",
+          headers: {
+            'Content-Type' => 'application/json',
+            'Authorization' => "Bearer #{oauth_access_token}",
+            'User-Agent' => config[:client_name]
+          },
+          request: {
+            timeout: config[:query_timeout]
+          }.merge(extra_connection_params)
+        )
+      end
+
+      def test_connection(raise_exception: false)
+        execute('SELECT 1')
+        true
+      rescue StandardError => e
+        raise ConnectionError, "Failed to connect to Databricks: #{e.message}" if raise_exception
+
+        logger.error "Connection test failed: #{e.message}"
+        false
+      end
+
+      # (see Adapter#execute)
+      def execute(sql, format: :array, retries: 0)
+        result = with_retry(retries + 1) do
+          with_debug(sql) do
+            response = submit_query(sql)
+            fetch_data(handle_query_response(response))
+          end
+        end
+
+        format_result(result, format)
+      end
+
+      def execute_stream(sql, io, stats: nil, retries: 0)
+        with_retry(retries) do
+          with_debug(sql) do
+            response = submit_query(sql)
+            fetch_data(handle_query_response(response), io: io, stats: stats)
+          end
+        end
+
+        io.rewind
+        io
+      end
+
+      # Execute SQL query and yield streamed results
+      # @param sql [String] SQL query to execute
+      # @yield [chunk] yields each chunk of data as it's processed
+      def stream(sql, &block)
+        with_debug(sql) do
+          response = submit_query(sql)
+          fetch_data(handle_query_response(response), proc: block)
+        end
+      end
+
+      def tables(**qualifiers)
+        catalog = qualifiers[:catalog] || config[:catalog]
+        schema = qualifiers[:schema] || config[:schema]
+
+        raise ConfigError, 'catalog is required for Databricks tables query' unless catalog
+
+        sql = "SELECT table_name FROM #{catalog}.information_schema.tables"
+        sql += " WHERE table_schema = '#{schema}'" if schema
+
+        result = execute(sql)
+        result.flatten
+      end
+
+      def metadata(table, **qualifiers)
+        catalog = qualifiers[:catalog] || config[:catalog]
+        schema = qualifiers[:schema] || config[:schema]
+
+        raise ConfigError, 'catalog is required for Databricks metadata query' unless catalog
+
+        db_table = Table.new(table, schema: schema, catalog: catalog)
+
+        sql = <<~SQL
+          SELECT column_name, data_type, numeric_precision, numeric_scale, character_maximum_length
+          FROM #{catalog}.information_schema.columns
+          WHERE table_name = '#{db_table.physical_name}'
+        SQL
+        sql += " AND table_schema = '#{db_table.schema}'" if db_table.schema
+
+        columns = execute(sql)
+
+        columns.each do |col|
+          db_table << Column.new(
+            name: col[0]&.downcase,
+            data_type: col[1]&.downcase,
+            precision: col[2],
+            scale: col[3],
+            max_char_length: col[4]
+          )
+        end
+
+        db_table
+      end
+
+      def stats(table, date_column: nil)
+        date_fields = if date_column
+                        ", MIN(#{date_column}) AS date_start, MAX(#{date_column}) AS date_end"
+                      else
+                        ', NULL AS date_start, NULL AS date_end'
+                      end
+
+        data = execute("SELECT COUNT(*) AS row_count#{date_fields} FROM #{table}")
+        cols = data.first
+
+        TableStats.new(
+          row_count: cols[0],
+          date_start: cols[1],
+          date_end: cols[2]
+        )
+      end
+
+      private
+
+      def reset_connection
+        @oauth_access_token = nil
+        @oauth_refresh_token = nil
+        @token_expires_at = nil
+        close
+      end
+
+      def submit_query(sql)
+        connection.post(STATEMENTS_API) do |req|
+          req.body = {
+            statement: sql,
+            warehouse_id: config[:warehouse],
+            catalog: config[:catalog],
+            schema: config[:schema],
+            wait_timeout: '30s',
+            on_wait_timeout: 'CONTINUE',
+            format: 'JSON_ARRAY',
+            disposition: 'INLINE'
+          }.compact.merge(extra_query_params).to_json
+        end
+      end
+
+      def handle_query_response(response)
+        body = JSON.parse(response.body)
+
+        case response.status
+        when 200
+          state = body.dig('status', 'state')
+          state == 'SUCCEEDED' ? body : poll(body['statement_id'])
+        when 202
+          poll(body['statement_id'])
+        else
+          error_message = body['message'] || body['error_code'] || response.body
+          raise ExecutionError, "Databricks query failed (#{response.status}): #{error_message}"
+        end
+      end
+
+      def poll(statement_id)
+        sleep_interval = DEFAULT_POLL_INTERVAL
+
+        logger.debug "Polling for query completion: #{statement_id}"
+
+        loop do
+          response = connection.get("#{STATEMENTS_API}/#{statement_id}")
+          body = JSON.parse(response.body)
+          state = body.dig('status', 'state')
+
+          case state
+          when 'SUCCEEDED'
+            return body
+          when 'FAILED', 'CANCELED', 'CLOSED'
+            error_msg = body.dig('status', 'error', 'message') || state
+            raise ExecutionError, "Databricks query #{state}: #{error_msg}"
+          else
+            logger.debug "Query still running (state: #{state}). Sleeping #{sleep_interval}s..."
+            sleep(sleep_interval)
+            sleep_interval = sleep_interval == MAX_POLL_INTERVAL ? DEFAULT_POLL_INTERVAL : sleep_interval
+            sleep_interval = [sleep_interval * 2, MAX_POLL_INTERVAL].min
+          end
+        end
+      end
+
+      def fetch_data(result, io: nil, stats: nil, proc: nil)
+        columns = result.dig('manifest', 'schema', 'columns')&.map { |col| col['name'] } || []
+        chunks = result.dig('manifest', 'chunks') || []
+        collector = {
+          columns: columns,
+          data: [],
+          io: io,
+          stats: stats,
+          wrote_header: false
+        }
+
+        write_data(result.dig('result', 'data_array') || [], collector, io, stats, proc)
+
+        return collector unless chunks.size > 1
+
+        statement_id = result['statement_id']
+        chunks[1..].each do |chunk|
+          chunk_index = chunk['chunk_index']
+          logger.debug "Fetching chunk #{chunk_index} of #{chunks.size} for statement: #{statement_id}"
+
+          resp = connection.get("#{STATEMENTS_API}/#{statement_id}/result/chunks/#{chunk_index}")
+          raise ExecutionError, "Failed to fetch chunk #{chunk_index}: #{resp.body}" unless resp.status == 200
+
+          chunk_data = JSON.parse(resp.body)
+          write_data(chunk_data['data_array'] || [], collector, io, stats, proc)
+        end
+
+        collector
+      end
+
+      def write_data(data, collector, io = nil, stats = nil, proc = nil)
+        if io
+          unless collector[:wrote_header]
+            io << CSV.generate_line(collector[:columns])
+            collector[:wrote_header] = true
+          end
+
+          data.each do |row|
+            stats << row if stats
+            io << CSV.generate_line(row)
+          end
+        elsif proc
+          data.each { proc.call(it) }
+        else
+          data.each { collector[:data] << it }
+        end
+
+        collector
+      end
+
+      def format_result(result, format)
+        data = result[:data]
+        columns = result[:columns]
+
+        case format
+        when :array
+          data
+        when :object
+          data.map { |row| columns.zip(row).to_h }
+        when :csv
+          CSV.generate do |csv|
+            csv << columns
+            data.each { |row| csv << row }
+          end
+        when :native
+          result
+        else
+          raise UnsupportedCapability, "Unknown result format: #{format}"
+        end
+      end
+
+      def workspace_host
+        config[:host].to_s
+      end
+
+      def oauth_supports_authorization_code_flow?
+        auth_mode == 'oauth_u2m'
+      end
+
+      def oauth_supports_client_credentials_flow?
+        auth_mode == 'oauth_m2m'
+      end
+
+      def oauth_redirect_uri_required?
+        oauth_supports_authorization_code_flow?
+      end
+
+      def oauth_client_credentials_params
+        {
+          grant_type: 'client_credentials',
+          scope: 'all-apis'
+        }
+      end
+
+      def oauth_token_expiry_leeway_seconds
+        30
+      end
+
+      def oauth_uses_pkce?
+        oauth_supports_authorization_code_flow?
+      end
+    end
+  end
+end

data/lib/dwh/adapters/duck_db.rb

@@ -209,7 +209,13 @@ module DWH
         super
         require 'duckdb'
       rescue LoadError
-        raise ConfigError, "Required 'duckdb' gem missing. Please add it to your Gemfile."
+        raise ConfigError, <<~MSG
+          DuckDB adapter requires the 'duckdb' gem.
+
+          Install with: gem install duckdb
+
+          See https://github.com/suketa/ruby-duckdb for installation details.
+        MSG
       end
 
       private

data/lib/dwh/adapters/my_sql.rb

@@ -219,7 +219,13 @@ module DWH
         super
         require 'mysql2'
       rescue LoadError
-        raise ConfigError, "Required 'MySql2' gem missing. Please add it to your Gemfile."
+        raise ConfigError, <<~MSG
+          MySQL adapter requires the 'mysql2' gem.
+
+          Install with: gem install mysql2
+
+          System libraries: https://dev.mysql.com/downloads/
+        MSG
       end
 
       def result_to_csv(result)

data/lib/dwh/adapters/open_authorizable.rb

@@ -1,5 +1,7 @@
 require 'base64'
 require 'securerandom'
+require 'digest'
+require_relative 'token_manageable'
 
 module DWH
   module Adapters
@@ -26,7 +28,7 @@ module DWH
     module OpenAuthorizable
       # rubcop:disable Style/DocumentationModule
       module ClassMethods
-        def oauth_with(authorize:, tokenize:, default_scope: 'refresh_token')
+        def oauth_with(authorize: nil, tokenize: nil, default_scope: 'refresh_token')
           @oauth_settings = { authorize: authorize, tokenize: tokenize, default_scope: default_scope }
         end
 
@@ -39,14 +41,18 @@ module DWH
 
       def self.included(base)
         base.extend(ClassMethods)
+        base.include(TokenManageable)
         base.config :oauth_client_id, String, required: false, message: 'OAuth client_id'
         base.config :oauth_client_secret, String, required: false, message: 'OAuth client_secret'
         base.config :oauth_redirect_uri, String, required: false, message: 'OAuth redirect_uri'
-        base.config :oauth_scope, String, required: false, message: 'OAuth redirect_url'
+        base.config :oauth_scope, String, required: false, message: 'OAuth scope'
       end
 
       # Generate authorization URL for user to visit
       def authorization_url(state: SecureRandom.hex(16), scope: nil)
+        raise UnsupportedCapability, "#{adapter_name} does not support authorization-code OAuth flow" unless oauth_supports_authorization_code_flow?
+
+        code_verifier = oauth_pkce_code_verifier_for_session
         params = {
           'response_type' => 'code',
           'client_id' => oauth_client_id,
@@ -54,6 +60,7 @@ module DWH
           'state' => state,
           'scope' => scope || oauth_scope || oauth_settings[:default_scope]
         }.compact
+        params.merge!(oauth_pkce_authorization_params(code_verifier))
 
         uri = URI(oauth_settings[:authorize])
         uri.query = URI.encode_www_form(params)
@@ -66,7 +73,7 @@ module DWH
       #
       # param access_token [String] the access token
       # @param refresh_token [String] optional refresh token
-      def apply_oauth_tokens(access_token:, refresh_token: nil, expires_at: nil)
+      def apply_oauth_tokens(access_token: nil, refresh_token: nil, expires_at: nil)
         @oauth_access_token = access_token
         @oauth_refresh_token = refresh_token
         @token_expires_at = expires_at
@@ -77,11 +84,15 @@ module DWH
       # @param authorization_code [String] this code should come from
       #   the redirect that is captured from the #authorization_url
       def generate_oauth_tokens(authorization_code)
+        raise UnsupportedCapability, "#{adapter_name} does not support authorization-code OAuth flow" unless oauth_supports_authorization_code_flow?
+
+        code_verifier = oauth_pkce_code_verifier_for_session
         params = {
           grant_type: 'authorization_code',
           code: authorization_code,
           redirect_uri: oauth_redirect_uri
         }
+        params.merge!(oauth_pkce_token_params(code_verifier))
 
         response = oauth_http_client.post(oauth_tokenization_url) do |req|
           req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
@@ -95,14 +106,23 @@ module DWH
       def refresh_access_token
         raise AuthenticationError, 'No refresh token available' unless @oauth_refresh_token
 
-        params = {
-          grant_type: 'refresh_token',
-          refresh_token: @oauth_refresh_token
-        }
+        params = oauth_refresh_token_params
+        response = oauth_http_client.post(oauth_tokenization_url) do |req|
+          req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
+          req.headers['Authorization'] = oauth_token_request_auth_header
+          req.body = URI.encode_www_form(params)
+        end
 
+        oauth_token_response(response)
+      end
+
+      def mint_access_token
+        raise UnsupportedCapability, "#{adapter_name} does not support client-credentials OAuth flow" unless oauth_supports_client_credentials_flow?
+
+        params = oauth_client_credentials_params
         response = oauth_http_client.post(oauth_tokenization_url) do |req|
           req.headers['Content-Type'] = 'application/x-www-form-urlencoded'
-          req.headers['Authorization'] = basic_auth_header
+          req.headers['Authorization'] = oauth_token_request_auth_header
           req.body = URI.encode_www_form(params)
         end
 
@@ -116,22 +136,22 @@ module DWH
       # @return [String] access token
       # @raise [AuthenticationError]
       def oauth_access_token
-        if token_expired? && @oauth_refresh_token
-          refresh_access_token
+        load_oauth_tokens_from_store! unless @oauth_access_token || @oauth_refresh_token
+        return @oauth_access_token if oauth_token_usable?
 
-          # return token unless exception was raised
-          @oauth_access_token
-        elsif @oauth_access_token
-          @oauth_access_token
-        else
-          raise AuthenticationError,
-                'Access token was never set. Either run the auth flow or set the tokens via apply_oauth_tokens method.'
-        end
+        refresh_access_token if oauth_refresh_token_usable?
+        return @oauth_access_token if oauth_token_usable?
+
+        mint_access_token if oauth_supports_client_credentials_flow?
+        return @oauth_access_token if oauth_token_usable?
+
+        raise AuthenticationError,
+              'Access token was never set. Either run the auth flow, mint via client credentials, or set tokens via apply_oauth_tokens.'
       end
 
       # Check if we have a valid access token
       def oauth_authenticated?
-        @oauth_access_token && !token_expired?
+        @oauth_access_token && oauth_token_usable?
       end
 
       # Get current state of tokens
@@ -140,7 +160,7 @@ module DWH
           access_token: @oauth_access_token,
           refresh_token: @oauth_refresh_token,
           expires_at: @token_expires_at,
-          expired: token_expired?,
+          expired: !oauth_token_usable?,
           authenticated: oauth_authenticated?
         }
       end
@@ -148,9 +168,11 @@ module DWH
       def validate_oauth_config
         raise ConfigError, 'Missing config: oauth_client_id. Required for OAuth.' unless config[:oauth_client_id]
         raise ConfigError, 'Missing config: oauth_client_secret. Required for OAuth.' unless config[:oauth_client_secret]
-        raise ConfigError, 'Missing config: oauth_redirect_url. Required for OAuth.' unless config[:oauth_redirect_uri]
 
-        oauth_settings
+        raise ConfigError, 'Missing config: oauth_redirect_uri. Required for OAuth.' if oauth_redirect_uri_required? && !config[:oauth_redirect_uri]
+
+        oauth_settings if oauth_supports_authorization_code_flow?
+        true
       end
 
       def oauth_settings
@@ -170,6 +192,75 @@ module DWH
         "Basic #{credentials}"
       end
 
+      def oauth_token_request_auth_header
+        basic_auth_header
+      end
+
+      def oauth_refresh_token_params
+        {
+          grant_type: 'refresh_token',
+          refresh_token: @oauth_refresh_token
+        }
+      end
+
+      def oauth_client_credentials_params
+        {
+          grant_type: 'client_credentials',
+          scope: oauth_scope || oauth_settings[:default_scope]
+        }.compact
+      end
+
+      def oauth_supports_authorization_code_flow?
+        true
+      end
+
+      def oauth_supports_client_credentials_flow?
+        false
+      end
+
+      def oauth_redirect_uri_required?
+        oauth_supports_authorization_code_flow?
+      end
+
+      def oauth_token_expiry_leeway_seconds
+        0
+      end
+
+      # PKCE is optional and disabled by default
+      def oauth_uses_pkce?
+        false
+      end
+
+      def oauth_pkce_code_challenge_method
+        'S256'
+      end
+
+      def oauth_pkce_code_verifier_for_session
+        return nil unless oauth_uses_pkce?
+
+        @oauth_pkce_code_verifier_for_session ||= oauth_pkce_code_verifier
+      end
+
+      def oauth_pkce_code_verifier
+        SecureRandom.urlsafe_base64(64).delete('=')
+      end
+
+      def oauth_token_usable?
+        return false unless @oauth_access_token
+
+        !token_expiring_soon?
+      end
+
+      def oauth_refresh_token_usable?
+        @oauth_refresh_token && token_expired?
+      end
+
+      def token_expiring_soon?(seconds = oauth_token_expiry_leeway_seconds)
+        return true if @token_expires_at.nil?
+
+        (Time.now + seconds) >= @token_expires_at
+      end
+
       def oauth_http_client
         @oauth_http_client ||= Faraday.new(
           headers: {
@@ -191,11 +282,20 @@ module DWH
           # Calculate expiration time
           expires_in = data['expires_in'] || 3600
           @token_expires_at = Time.now + expires_in
+          store_tokens_in_store(
+            access_token: @oauth_access_token,
+            refresh_token: @oauth_refresh_token,
+            expires_at: @token_expires_at,
+            token_type: data['token_type'],
+            scope: data['scope'],
+            raw: data
+          )
 
           { success: true, data: data }
         else
           error_data = parse_error_response(response)
           if error_data['error'] == 'invalid_grant' && @oauth_refresh_token
+            delete_tokens_from_store
             raise TokenExpiredError, "Potentially expired refresh token. #{error_data['message']}"
           end
 
@@ -205,11 +305,48 @@ module DWH
 
       private
 
+      def load_oauth_tokens_from_store!
+        payload = load_tokens_from_store
+        return unless payload
+
+        apply_oauth_tokens(
+          access_token: payload[:access_token],
+          refresh_token: payload[:refresh_token],
+          expires_at: payload[:expires_at]
+        )
+      end
+
       def parse_error_response(response)
         JSON.parse(response.body)
       rescue JSON::ParserError
         { 'error' => 'unknown', 'message' => response.body }
       end
+
+      def oauth_pkce_authorization_params(code_verifier)
+        return {} unless oauth_uses_pkce?
+
+        {
+          'code_challenge' => oauth_pkce_code_challenge(code_verifier),
+          'code_challenge_method' => oauth_pkce_code_challenge_method
+        }
+      end
+
+      def oauth_pkce_token_params(code_verifier)
+        return {} unless oauth_uses_pkce?
+
+        { code_verifier: code_verifier }
+      end
+
+      def oauth_pkce_code_challenge(code_verifier)
+        case oauth_pkce_code_challenge_method
+        when 'S256'
+          Base64.urlsafe_encode64(Digest::SHA256.digest(code_verifier), padding: false)
+        when 'plain'
+          code_verifier
+        else
+          raise ConfigError, "Unsupported PKCE code challenge method: #{oauth_pkce_code_challenge_method}"
+        end
+      end
     end
   end
 end

data/lib/dwh/adapters/postgres.rb

@@ -221,7 +221,13 @@ module DWH
         super
         require 'pg'
       rescue LoadError
-        raise ConfigError, "Required 'pg' gem missing. Please add it to your Gemfile."
+        raise ConfigError, <<~MSG
+          PostgreSQL adapter requires the 'pg' gem.
+
+          Install with: gem install pg
+
+          System libraries: https://www.postgresql.org/download/
+        MSG
       end
 
       private

data/lib/dwh/adapters/snowflake.rb

@@ -39,7 +39,7 @@ module DWH
     #     account_identifier: 'myorg-myaccount.us-east-1',
     #     oauth_client_id: '<YOUR_CLIENT_ID>',
     #     oauth_client_secret: '<YOUR_CLIENT_SECRET>',
-    #     oauth_redirect_url: 'https://localhost:3030/some/path',
+    #     oauth_redirect_uri: 'https://localhost:3030/some/path',
     #     database: 'ANALYTICS'
     #   })
     #

data/lib/dwh/adapters/sql_server.rb

@@ -234,7 +234,13 @@ module DWH
         super
         require 'tiny_tds'
       rescue LoadError
-        raise ConfigError, "Required 'tiny_tds' gem missing. Please add it to your Gemfile."
+        raise ConfigError, <<~MSG
+          SQL Server adapter requires the 'tiny_tds' gem.
+
+          Install with: gem install tiny_tds
+
+          System libraries (FreeTDS): https://www.freetds.org/
+        MSG
       end
 
       private

data/lib/dwh/adapters/token_manageable.rb

@@ -0,0 +1,81 @@
+require 'time'
+
+module DWH
+  module Adapters
+    # TokenManageable hold the logic to load, store and delete tokens from the token store.
+    module TokenManageable
+      def token_store
+        config[:token_store]
+      end
+
+      def load_tokens_from_store
+        return nil unless token_store.respond_to?(:load)
+
+        payload = token_store.load
+        normalize_token_payload(payload)
+      rescue StandardError => e
+        logger.warn("Failed loading token from token_store: #{e.message}")
+        nil
+      end
+
+      def store_tokens_in_store(token_payload)
+        return unless token_store.respond_to?(:store)
+
+        token_store.store(normalize_token_payload_for_store(token_payload))
+      rescue StandardError => e
+        logger.warn("Failed storing token in token_store: #{e.message}")
+      end
+
+      def delete_tokens_from_store
+        return unless token_store.respond_to?(:delete)
+
+        token_store.delete
+      rescue StandardError => e
+        logger.warn("Failed deleting token from token_store: #{e.message}")
+      end
+
+      private
+
+      def normalize_token_payload(payload)
+        return nil unless payload.is_a?(Hash)
+
+        data = payload.transform_keys(&:to_sym)
+        access_token = data[:access_token]
+        access_token = nil if access_token.to_s.strip == ''
+
+        refresh_token = data[:refresh_token]
+        refresh_token = nil if refresh_token.respond_to?(:empty?) && refresh_token.empty?
+        return nil if access_token.nil? && refresh_token.nil?
+
+        {
+          access_token: access_token&.to_s,
+          refresh_token: refresh_token,
+          expires_at: parse_token_expiry(data[:expires_at])
+        }
+      end
+
+      def normalize_token_payload_for_store(payload)
+        data = payload.transform_keys(&:to_sym)
+        cleaned = {
+          access_token: data[:access_token]&.to_s,
+          refresh_token: data[:refresh_token],
+          expires_at: parse_token_expiry(data[:expires_at]),
+          token_type: data[:token_type],
+          scope: data[:scope],
+          issued_at: parse_token_expiry(data[:issued_at]),
+          raw: data[:raw]
+        }
+        cleaned.reject { |_k, v| v.nil? }
+      end
+
+      def parse_token_expiry(value)
+        return value if value.is_a?(Time)
+        return nil if value.nil? || value.to_s.strip == ''
+
+        Time.parse(value.to_s)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/dwh/adapters/trino.rb

@@ -194,7 +194,13 @@ module DWH
         super
         require 'trino-client'
       rescue LoadError
-        raise ConfigError, "Required 'trino-client' gem missing. Please add it to your Gemfile."
+        raise ConfigError, <<~MSG
+          Trino adapter requires the 'trino-client' gem.
+
+          Install with: gem install trino-client
+
+          No system libraries required (pure Ruby).
+        MSG
       end
 
       private

data/lib/dwh/adapters.rb

@@ -79,6 +79,13 @@ module DWH
       # @return [Hash] the actual instance configuration
       attr_reader :config
 
+      # Optional host-implemented token store for OAuth token reuse.
+      # That should implement the following methods:
+      #   - load -> Hash|nil
+      #   - store(token_hash)
+      #   - delete
+      config :token_store, Object, required: false, default: nil, message: 'Token store instance implementing load/store/delete'
+
       def initialize(config)
         @config = config.transform_keys(&:to_sym)
         # Per instance customization of general settings

data/lib/dwh/settings/databricks.yml

@@ -1,6 +1,5 @@
-
 # quotes and string lit
-quote: "\"@exp\""
+quote: "`@exp`"
 string_literal: "'@exp'"
 
 # Date Literal Formats

data/lib/dwh/token_store.rb

@@ -0,0 +1,24 @@
+module DWH
+  # Optional contract for host applications that want token persistence.
+  #
+  # The store instance should be identity-bound before it is passed into
+  # adapter config so the adapter remains unaware of user/datasource identity.
+  #
+  # This class is intentionally minimal and can be subclassed or duck-typed.
+  class TokenStore
+    # @return [Hash,nil] token payload
+    def load
+      raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+    end
+
+    # @param token [Hash] normalized payload with at least access_token and expires_at
+    def store(_token)
+      raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+    end
+
+    # Remove/revoke persisted token state.
+    def delete
+      raise NotImplementedError, "#{self.class} must implement ##{__method__}"
+    end
+  end
+end

data/lib/dwh/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DWH
-  VERSION = '0.2.0'
+  VERSION = '0.4.0'
 end

data/lib/dwh.rb

@@ -5,6 +5,7 @@ require_relative 'dwh/errors'
 require_relative 'dwh/logger'
 require_relative 'dwh/streaming_stats'
 require_relative 'dwh/factory'
+require_relative 'dwh/token_store'
 require_relative 'dwh/adapters'
 require_relative 'dwh/table'
 require_relative 'dwh/table_stats'
@@ -18,6 +19,7 @@ require_relative 'dwh/adapters/duck_db'
 require_relative 'dwh/adapters/sqlite'
 require_relative 'dwh/adapters/athena'
 require_relative 'dwh/adapters/redshift'
+require_relative 'dwh/adapters/databricks'
 
 # DWH encapsulates the full functionality of this gem.
 #
@@ -49,6 +51,7 @@ module DWH
   register(:sqlite, Adapters::Sqlite)
   register(:athena, Adapters::Athena)
   register(:redshift, Adapters::Redshift)
+  register(:databricks, Adapters::Databricks)
 
   # start_reaper
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dwh
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ajo Abraham
@@ -154,6 +154,7 @@ files:
 - lib/dwh.rb
 - lib/dwh/adapters.rb
 - lib/dwh/adapters/athena.rb
+- lib/dwh/adapters/databricks.rb
 - lib/dwh/adapters/druid.rb
 - lib/dwh/adapters/duck_db.rb
 - lib/dwh/adapters/my_sql.rb
@@ -163,6 +164,7 @@ files:
 - lib/dwh/adapters/snowflake.rb
 - lib/dwh/adapters/sql_server.rb
 - lib/dwh/adapters/sqlite.rb
+- lib/dwh/adapters/token_manageable.rb
 - lib/dwh/adapters/trino.rb
 - lib/dwh/behaviors.rb
 - lib/dwh/capabilities.rb
@@ -191,6 +193,7 @@ files:
 - lib/dwh/streaming_stats.rb
 - lib/dwh/table.rb
 - lib/dwh/table_stats.rb
+- lib/dwh/token_store.rb
 - lib/dwh/version.rb
 - sig/dwh.rbs
 homepage: https://www.strata.site