Respect the database's CURSOR_SHARING setting by default

[yahonda]

Summary

Stops applying cursor_sharing = force from the adapter at session login. Introduces :default as the new effective default for the :cursor_sharing connection option; with it (or unset) the adapter does not run any ALTER SESSION SET cursor_sharing and the database's instance-level setting is what the session sees. Explicit values ('exact', 'force') continue to issue the corresponding ALTER SESSION.

:cursor_sharing in config	What the adapter does
not set, or :default	no ALTER SESSION (database's instance-level setting kept)
explicit value ('force', 'exact')	ALTER SESSION SET cursor_sharing = value
anything else	ArgumentError

Why

Oracle's documented software default for CURSOR_SHARING is EXACT. Most users running an Oracle Database have not changed it from EXACT, and many are not even aware that oracle_enhanced has been silently overriding it to FORCE at the session level since 2009 (ebb60f3).

The implicit force default made sense at the time it was added: Active Record didn't bind literals yet, so the adapter sent SQL with literals inlined, and force was the only way the server could collapse that into a single shared cursor.

That premise no longer holds:

• The AbstractAdapter default for prepared_statements became true in Rails 7.1 (rails/rails#45945, commit a0fd15ee7e) — oracle_enhanced inherits this default. With prepared_statements: true, Active Record binds application SQL literals before sending, so the server sees identical SQL text regardless of bind values, and force's rewrite has nothing left to do for that traffic.
• All all_* / user_* dictionary queries inside oracle_enhanced itself are now bind-driven (Bind literals in dictionary queries #2629 finished the last four), so dictionary access doesn't depend on force for shared-cursor reuse either.
• Keeping force on by default also keeps connections exposed to the OCI8 + cursor_sharing=force x INSERT ... RETURNING INTO :returning_id hangs in SQL*Net half-duplex deadlock #2619 hang combination on amd64 Oracle Database (cached cursor + a literal the server rewrites + RETURNING ... INTO). Honor intent.prepare in _exec_insert to avoid OCI8 half-duplex deadlock #2620 removed the exposure for the typical Rails ORM path; dropping the implicit force default removes it for raw-SQL callers too.

After this PR, sessions run with whatever CURSOR_SHARING the database is configured with — for almost all installations that means the documented Oracle default EXACT, which is what users were already (unknowingly) running on the server level. The adapter simply stops imposing its own value on top.

Opting in to the legacy behavior

Anyone who actually relied on force — typically connections still configured with prepared_statements: false, where Active Record interpolates application-SQL literals at the visitor level — can opt back in with one line in database.yml:

production:
  adapter: oracle_enhanced
  # ...
  cursor_sharing: force

(Setting prepared_statements: false is independent and orthogonal — having both, just one, or neither is a deliberate choice.)

CI matrix — Run RSpec duration (seconds)

Run RSpec step only (Oracle Client install / container start excluded; identical across rows). Lower is better; numbers within ±10s on this CI are noise.

	prepared_statements: true (adapter default)	prepared_statements: false (explicit)
cursor_sharing: 'force' (today's adapter-imposed default)	3.3: 122 / 3.4: 125 / 4.0: 134 / jruby: 180	3.3: 128 / 3.4: 143 / 4.0: 149 / jruby: 163
:default (proposed default, after #2629 merged)	3.3: 147 / 3.4: 133 / 4.0: 123 / jruby: 158	3.3: 149 / 3.4: 149 / 4.0: 135 / jruby: 192

Sources of each cell:

• (true, force) — master baseline before this PR, avg of 5 recent runs
• (true, :default) — measurement run #25042855383 (combined branch of Respect the database's CURSOR_SHARING setting by default #2626 and Bind literals in dictionary queries #2629; Bind literals in dictionary queries #2629 is now in master)
• (false, force) — measurement run #25043429031 (master with prepared_statements: false hard-coded into CONNECTION_PARAMS for measurement)
• (false, :default) — measurement run #25043431071 (same hard-coded variant on the combined branch)

Both rows are within noise. The earlier observation that :default alone (without #2629) regressed by +20–43% is preserved in this comment for the record; #2629 already cancelled that out.

Tests

• New describe \"cursor_sharing\" block in connection_spec.rb covers: unset (default), :default, explicit :force, explicit :exact, and the existing ArgumentError for unsupported values.
• Test sessions use the regular CONNECTION_PARAMS user. Observation goes through a separate SystemObserver AR connection (SYSTEM) reading v$parameter and v$ses_optimizer_env (both normalized to upper-case so the comparison is stable across views), since the regular user has no v$ access by default.

Doc update

The :cursor_sharing doc comment in oracle_enhanced_adapter.rb is updated to describe the new default, the accepted values including :default, and the explicit cursor_sharing: 'force' opt-in for the legacy behavior.

References

• Oracle Database 26 Database Reference — CURSOR_SHARING (documented default EXACT; FORCE and EXACT are the only valid values; SIMILAR was removed)
• Rails — rails/rails#45945 makes prepared_statements: true the AbstractAdapter default starting with Rails 7.1
• oracle_enhanced — original 2009 commit introducing the force default: ebb60f3

Refs #2622, #2628.

[yahonda]

On hold pending #2628

Comparing the Run RSpec step duration (Oracle Client install / container start excluded) between this branch and master shows a measurable performance regression:

Ruby	master avg	#2626 avg	delta
3.3	122s	175s	+53s (+43%)
3.4	125s	150s	+25s (+20%)
4.0	134s	155s	+21s (+16%)
jruby-10.1.0.0	180s	240s	+60s (+33%)

(5 master runs vs 2 PR runs; effect is well above the per-run variance.)

This is exactly the dictionary-query trade-off the PR body flagged: with cursor_sharing = force no longer applied by default, the spec suite's many CREATE/DROP TABLE cycles cause each unique table name to produce a fresh shared cursor in all_tab_columns / all_indexes / etc.

Holding this PR until #2628 (binding the literals in those dictionary queries at the call sites) lands. Once the dictionary queries are properly bound, removing the cursor_sharing = force default has no measurable performance cost.