efficient piecewise LOB fetching

Author: akostadinov

lib/oci8/bindtype.rb

@@ -245,13 +245,18 @@ def self.create(con, val, param, max_array_size)
 # datatype        type     size prec scale
 # -------------------------------------------------
 # CLOB          SQLT_CLOB  4000    0    0
-OCI8::BindType::Mapping[:clob] = OCI8::BindType::CLOB
-OCI8::BindType::Mapping[:nclob] = OCI8::BindType::NCLOB
+# NCLOB         SQLT_CLOB  4000    0    0
+# Default: Fetch as String using SQLT_CHR (fast, max 2GB)
+# See: OCI8::lob_fetch_mode
+OCI8::BindType::Mapping[:clob] = OCI8::BindType::Long
+OCI8::BindType::Mapping[:nclob] = OCI8::BindType::Long
 
 # datatype        type     size prec scale
 # -------------------------------------------------
 # BLOB          SQLT_BLOB  4000    0    0
-OCI8::BindType::Mapping[:blob] = OCI8::BindType::BLOB
+# Default: Fetch as binary String using SQLT_CHR (fast, max 2GB)
+# See: OCI8::lob_fetch_mode
+OCI8::BindType::Mapping[:blob] = OCI8::BindType::LongRaw
 
 # datatype        type     size prec scale
 # -------------------------------------------------

lib/oci8/oci8.rb

@@ -152,6 +152,7 @@ def initialize(*args)
     end
 
     @prefetch_rows = 100
+    @lob_prefetch_size = 0  # 0 means use Oracle default (disabled)
     @username = nil
   end
 
@@ -333,6 +334,27 @@ def prefetch_rows=(num)
     @prefetch_rows = num
   end
 
+  # Sets the LOB prefetch size in bytes. Only used when lob_fetch_mode is :locator.
+  # i.e. sets OCI_ATTR_DEFAULT_LOBPREFETCH_SIZE on the session handle.
+  # The default value is 0 (disabled).
+  #
+  # When set to a non-zero value (e.g., 65536 for 64KB), Oracle prefetches
+  # LOB data along with the row if the LOB size is <= this value.
+  # This reduces network round trips when fetching small to medium LOBs.
+  #
+  # This is a session-wide setting that applies to all LOB columns fetched
+  # from this connection.
+  #
+  # It has no effect when lob_fetch_mode is :long_as_string (the default).
+  #
+  # @param [Integer] size prefetch size in bytes (0 to disable)
+  # @see OCI8::lob_fetch_mode=
+  # @note Requires Oracle 11g or later
+  def lob_prefetch_size=(size)
+    @lob_prefetch_size = size
+    @session_handle.send(:attr_set_ub4, 438, size)
+  end
+
   # @private
   def inspect
     "#<OCI8:#{username}>"
@@ -370,6 +392,48 @@ def self.client_charset_name
     @@client_charset_name
   end
 
+  # Returns the current LOB fetch mode.
+  #
+  # @return [Symbol] :long_as_string or :locator
+  # @see lob_fetch_mode=
+  def self.lob_fetch_mode
+    @@lob_fetch_mode ||= :long_as_string
+  end
+
+  # Sets the LOB fetch mode.
+  #
+  # - +:long_as_string+ (default): Fetch LOBs as Strings using
+  #   Runtime Data Allocation and Piecewise Operations in OCI.
+  #   Fastest and most efficient fetch but limited to 2GB LOBs.
+  #
+  # - +:locator+: Fetch LOB locators (OCI8::CLOB/BLOB objects).
+  #   Calls OCILobRead2() on the lob fields individually.
+  #   Required for LOBs > 2GB, random access, or read/write operations.
+  #   @conn.lob_prefetch_size may reduce network roundtrips but my
+  #   unscientific testing only showed performance degradation.
+  #
+  # @param [Symbol] mode :long_as_string or :locator
+  # @return [Symbol] the mode that was set
+  # @see https://github.com/oracle/odpi/issues/163
+  def self.lob_fetch_mode=(mode)
+    unless [:long_as_string, :locator].include?(mode)
+      raise ArgumentError, "lob_fetch_mode must be :long_as_string or :locator"
+    end
+
+    case mode
+    when :long_as_string
+      OCI8::BindType::Mapping[:clob] = OCI8::BindType::Long
+      OCI8::BindType::Mapping[:nclob] = OCI8::BindType::Long
+      OCI8::BindType::Mapping[:blob] = OCI8::BindType::LongRaw
+    when :locator
+      OCI8::BindType::Mapping[:clob] = OCI8::BindType::CLOB
+      OCI8::BindType::Mapping[:nclob] = OCI8::BindType::NCLOB
+      OCI8::BindType::Mapping[:blob] = OCI8::BindType::BLOB
+    end
+
+    @@lob_fetch_mode = mode
+  end
+
   if OCI8.oracle_client_version >= OCI8::ORAVER_11_1
     # Returns send timeout in seconds.
     # Zero means no timeout.

test/config.rb

@@ -3,7 +3,7 @@
 #     GRANT EXECUTE ON dbms_lock TO ruby;
 $dbuser = "ruby"
 $dbpass = "oci8"
-$dbname = "127.0.0.1:1521/systempdb"
+$dbname = nil
 
 # for test_bind_string_as_nchar in test_encoding.rb
 ENV['ORA_NCHAR_LITERAL_REPLACE'] = 'TRUE' if OCI8.client_charset_name.include? 'UTF8'

test/test_clob.rb

@@ -6,10 +6,17 @@ class TestCLob < Minitest::Test
 
   def setup
     @conn = get_oci8_connection
+    # This test needs LOB locators for read/write operations
+    OCI8.lob_fetch_mode = :locator
     drop_table('test_table')
     @conn.exec('CREATE TABLE test_table (filename VARCHAR2(40), content CLOB)')
   end
 
+  def teardown
+    # Restore default mode
+    OCI8.lob_fetch_mode = :long_as_string if @conn
+  end
+
   def test_insert
     filename = File.basename($lobfile)
     @conn.exec("DELETE FROM test_table WHERE filename = :1", filename)

test/test_dbi_clob.rb

@@ -6,10 +6,17 @@ class TestDbiCLob < Minitest::Test
 
   def setup
     @dbh = get_dbi_connection()
+    # This test needs LOB locators for read/write operations
+    OCI8.lob_fetch_mode = :locator
     drop_table('test_table')
     @dbh.execute('CREATE TABLE test_table (filename VARCHAR2(40), content CLOB)')
   end
 
+  def teardown
+    # Restore default mode
+    OCI8.lob_fetch_mode = :long_as_string if @dbh
+  end
+
   def test_insert
     filename = File.basename($lobfile)