Add Cursor#reparse_between_execs to work around OCI re-exec deadlock

Re-executing the same parsed cursor under CURSOR_SHARING=FORCE (or
SIMILAR) when the SQL contains BOTH a literal AND a RETURNING ... INTO
:bind clause hangs forever on the second exec. The server reports
"SQL*Net more data from client"; the client sits in
OCIStmtExecute -> kpuexec -> ... -> nttfprd -> read().

A SQL*Net wire trace shows OCIStmtExecute constructs a 31-byte fast-path
"execute already-parsed cursor" packet, and that packet differs from the
working (CURSOR_SHARING=EXACT) case by exactly one byte computed inside
libclntsh from cursor state set by exec kubo#1's response. ruby-oci8 calls
OCIStmtExecute with identical arguments in both runs, so the defect is
in the Oracle Client TTC marshalling, not ruby-oci8.

Add an opt-in Cursor#reparse_between_execs accessor (default false) that
releases and re-prepares the underlying statement handle before every
exec after the first, forcing OCI onto the full parse+exec path and
avoiding the buggy fast path. Bind values are preserved.

- ext/oci8/stmt.c: add private __reprepare(sql), and let oci8_bind cleanly
  detach a bind object from a previous statement so the same valuep/indp
  buffers can be re-attached to a fresh statement handle.
- lib/oci8/cursor.rb: remember the parsed SQL on initialize, expose
  reparse_between_execs, and re-bind every entry in @bind_handles after
  __reprepare.
- test/test_reparse_between_execs.rb: regression test covering the
  literal + RETURNING + same-cursor scenario plus a plain repeated
  INSERT to ensure the flag does not affect ordinary cursors.

The flag is off by default; existing cursors keep their fast-path
behavior. Leave it false unless you actually hit the deadlock - the
extra round trip costs measurable latency on hot paths.

Refs: rsim/oracle-enhanced#2619, rsim/oracle-enhanced#2620.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: yahonda

ext/oci8/stmt.c

@@ -97,6 +97,48 @@ static VALUE oci8_stmt_initialize(VALUE self, VALUE svc, VALUE sql)
     return Qnil;
 }
 
+/*
+ * @overload __reprepare(sql_statement)
+ *
+ *  Releases the underlying OCI statement handle and re-prepares it
+ *  with the same SQL text. Workaround for an Oracle Client TTC
+ *  fast-path bug under CURSOR_SHARING + RETURNING + same-cursor
+ *  re-execute. Caller must re-attach all bind/define handles after
+ *  this call.
+ *
+ *  @param [String] sql_statement
+ *  @private
+ */
+static VALUE oci8_stmt_reprepare(VALUE self, VALUE sql)
+{
+    oci8_stmt_t *stmt = TO_STMT(self);
+    oci8_svcctx_t *svcctx;
+    sword rv;
+
+    OCI8SafeStringValue(sql);
+    svcctx = oci8_get_svcctx(stmt->svc);
+    oci8_check_pid_consistency(svcctx);
+
+    if (stmt->use_stmt_release) {
+        OCIStmtRelease(stmt->base.hp.stmt, oci8_errhp, NULL, 0, OCI_DEFAULT);
+        stmt->use_stmt_release = 0;
+    } else if (stmt->base.hp.ptr != NULL) {
+        OCIHandleFree(stmt->base.hp.ptr, OCI_HTYPE_STMT);
+    }
+    stmt->base.hp.ptr = NULL;
+    stmt->base.type = 0;
+
+    rv = OCIStmtPrepare2(svcctx->base.hp.svc, &stmt->base.hp.stmt, oci8_errhp,
+                         RSTRING_ORATEXT(sql), RSTRING_LENINT(sql),
+                         NULL, 0, OCI_NTV_SYNTAX, OCI_DEFAULT);
+    if (IS_OCI_ERROR(rv)) {
+        chker2(rv, &svcctx->base);
+    }
+    stmt->base.type = OCI_HTYPE_STMT;
+    stmt->use_stmt_release = 1;
+    return self;
+}
+
 /*
  * @overload __define(position, bindobj)
  *
@@ -196,7 +238,15 @@ static VALUE oci8_bind(VALUE self, VALUE vplaceholder, VALUE vbindobj)
     }
     obind = TO_BIND(vbindobj); /* 2 */
     if (obind->base.hp.bnd != NULL) {
-        oci8_base_free(&obind->base); /* TODO: OK? */
+        /* The bind object is already attached to a statement. Detach
+         * cleanly so OCIBindByPos / OCIBindByName below installs a
+         * fresh OCI bind handle on the (possibly new) statement,
+         * while reusing the existing valuep / indp buffers. The OCI
+         * bind handle itself is owned by the previous statement and
+         * is freed when that statement is released. */
+        oci8_unlink_from_parent(&obind->base);
+        obind->base.hp.bnd = NULL;
+        obind->base.type = 0;
     }
     data_type = (const oci8_bind_data_type_t *)obind->base.data_type;
 
@@ -218,6 +268,7 @@ static VALUE oci8_bind(VALUE self, VALUE vplaceholder, VALUE vbindobj)
         chker3(status, &stmt->base, stmt->base.hp.stmt);
     }
     obind->base.type = OCI_HTYPE_BIND;
+    obind->base.closed = 0;
     /* link to the parent as soon as possible to preserve deallocation order. */
     oci8_unlink_from_parent((oci8_base_t*)obind);
     oci8_link_to_parent((oci8_base_t*)obind, (oci8_base_t*)stmt);
@@ -437,6 +488,7 @@ void Init_oci8_stmt(VALUE cOCI8)
     cOCIStmt = oci8_define_class_under(cOCI8, "Cursor", &oci8_stmt_data_type, oci8_stmt_alloc);
 
     rb_define_private_method(cOCIStmt, "__initialize", oci8_stmt_initialize, 2);
+    rb_define_private_method(cOCIStmt, "__reprepare", oci8_stmt_reprepare, 1);
     rb_define_private_method(cOCIStmt, "__define", oci8_define_by_pos, 2);
     rb_define_private_method(cOCIStmt, "__bind", oci8_bind, 2);
     rb_define_private_method(cOCIStmt, "__execute", oci8_stmt_execute, 1);

lib/oci8/cursor.rb

@@ -28,10 +28,35 @@ def initialize(conn, sql = nil)
       @fetch_array_size = nil
       @rowbuf_size = 0
       @rowbuf_index = 0
+      @sql = sql
+      @reparse_between_execs = false
+      @already_executed = false
       __initialize(conn, sql) # Initialize the internal C structure.
       self.prefetch_rows = conn.instance_variable_get(:@prefetch_rows)
     end
 
+    # When true, releases and re-prepares the underlying OCI statement
+    # handle before every {#exec} call after the first. Default false.
+    #
+    # Workaround for an Oracle Client (libclntsh) defect that produces
+    # a half-duplex SQL*Net deadlock when ALL of the following hold:
+    #
+    #   1. session has +CURSOR_SHARING = FORCE+ (or +SIMILAR+),
+    #   2. SQL contains a literal AND a +RETURNING ... INTO :bind+ clause,
+    #   3. the same parsed cursor is executed more than once.
+    #
+    # Under that combination, OCIStmtExecute builds a fast-path "execute
+    # already-parsed cursor" packet that the server treats as
+    # incomplete; both ends then wait on the other forever. Setting
+    # this flag forces a full parse+exec round trip on each call,
+    # avoiding the buggy fast path. Bind values are preserved.
+    #
+    # Leave this off unless you actually hit the deadlock — the extra
+    # round trip costs measurable latency on hot paths.
+    #
+    # @return [Boolean]
+    attr_accessor :reparse_between_execs
+
     # explicitly indicate the date type of fetched value. run this
     # method within parse and exec. pos starts from 1. lentgh is used
     # when type is String.
@@ -125,18 +150,30 @@ def bind_param(key, param, type = nil, length = nil)
     # though PL/SQL. Use OCI8::Cursor#[] explicitly to get bind
     # variables.
     def exec(*bindvars)
-      bind_params(*bindvars)
-      case type
-      when :select_stmt
-        __execute(0)
-        define_columns() if @column_metadata.size == 0
+      if @reparse_between_execs && @already_executed && @sql
+        __reprepare(@sql)
+        @bind_handles.each { |key, handle| __bind(key, handle) }
+        @column_metadata = []
+        @define_handles = []
+        @names = nil
         @rowbuf_size = 0
         @rowbuf_index = 0
-        @column_metadata.size
-      else
-        __execute(1)
-        row_count
       end
+      bind_params(*bindvars)
+      result =
+        case type
+        when :select_stmt
+          __execute(0)
+          define_columns() if @column_metadata.size == 0
+          @rowbuf_size = 0
+          @rowbuf_index = 0
+          @column_metadata.size
+        else
+          __execute(1)
+          row_count
+        end
+      @already_executed = true
+      result
     end
 
     # Gets fetched data as array. This is available for select

test/test_all.rb

@@ -20,6 +20,7 @@
 require "#{srcdir}/test_connstr"
 require "#{srcdir}/test_metadata"
 require "#{srcdir}/test_array_dml"
+require "#{srcdir}/test_reparse_between_execs"
 require "#{srcdir}/test_rowid"
 require "#{srcdir}/test_appinfo"
 require "#{srcdir}/test_oracle_version"

test/test_reparse_between_execs.rb

@@ -0,0 +1,92 @@
+require 'oci8'
+require File.dirname(__FILE__) + '/config'
+
+class TestReparseBetweenExecs < Minitest::Test
+  TABLE_NAME    = 'rb_reparse_test'
+  TRIGGER_NAME  = 'rb_reparse_test_pkt'
+  SEQUENCE_NAME = 'rb_reparse_test_seq'
+
+  def setup
+    @conn = get_oci8_connection
+    drop_table(TABLE_NAME)
+    drop_sequence(SEQUENCE_NAME)
+    @conn.exec("CREATE TABLE #{TABLE_NAME} (id NUMBER PRIMARY KEY, name VARCHAR2(50))")
+    @conn.exec("CREATE SEQUENCE #{SEQUENCE_NAME}")
+    @conn.exec(<<~SQL)
+      CREATE OR REPLACE TRIGGER #{TRIGGER_NAME}
+        BEFORE INSERT ON #{TABLE_NAME} FOR EACH ROW
+      BEGIN
+        IF :new.id IS NULL THEN
+          SELECT #{SEQUENCE_NAME}.NEXTVAL INTO :new.id FROM dual;
+        END IF;
+      END;
+    SQL
+  end
+
+  def teardown
+    drop_table(TABLE_NAME) if @conn
+    drop_sequence(SEQUENCE_NAME) if @conn
+    @conn.logoff if @conn
+  end
+
+  def drop_sequence(name)
+    @conn.exec("DROP SEQUENCE #{name}")
+  rescue OCIError
+    raise if $!.code != 2289 # ORA-02289: sequence does not exist
+  end
+
+  # Default state: the opt-in flag is off so existing behavior is unchanged.
+  def test_default_flag_is_false
+    cur = @conn.parse("SELECT 1 FROM dual")
+    assert_equal false, cur.reparse_between_execs
+  ensure
+    cur.close if cur
+  end
+
+  # Re-executing the same parsed cursor under CURSOR_SHARING=FORCE with
+  # both a literal and a RETURNING ... INTO :bind clause triggers an
+  # Oracle Client TTC fast-path defect that deadlocks the session.
+  # Setting reparse_between_execs = true must work around it: every exec
+  # succeeds and yields a fresh sequence value via the RETURNING bind.
+  def test_returning_into_under_cursor_sharing_force_with_flag
+    @conn.exec("ALTER SESSION SET CURSOR_SHARING = FORCE")
+    cur = @conn.parse(
+      "INSERT INTO #{TABLE_NAME} (name) VALUES ('a') RETURNING id INTO :returning_id"
+    )
+    cur.reparse_between_execs = true
+    cur.bind_param(1, nil, Integer)
+
+    ids = Array.new(3) do
+      cur.exec
+      cur[1]
+    end
+
+    assert_equal 3, ids.size
+    ids.each { |id| assert_kind_of Integer, id }
+    assert_equal ids, ids.uniq,
+      'each RETURNING value must be a fresh sequence number'
+  ensure
+    cur.close if cur
+    @conn.exec("ALTER SESSION SET CURSOR_SHARING = EXACT") rescue nil
+  end
+
+  # The flag must not break a plain INSERT (no RETURNING, no cursor
+  # sharing) that re-executes the same cursor with a different bind
+  # value each time.
+  def test_flag_does_not_break_plain_repeated_insert
+    cur = @conn.parse("INSERT INTO #{TABLE_NAME} (name) VALUES (:name)")
+    cur.reparse_between_execs = true
+    cur.bind_param(:name, nil, String, 50)
+
+    %w[alpha beta gamma].each do |name|
+      cur[:name] = name
+      cur.exec
+    end
+
+    rows = []
+    @conn.exec("SELECT name FROM #{TABLE_NAME} ORDER BY id") { |r| rows << r[0] }
+    assert_equal %w[alpha beta gamma], rows
+  ensure
+    cur.close if cur
+  end
+end