POC: resolve describe() via DBMS_UTILITY.NAME_RESOLVE

Replaces the UNION ALL catalog query inside
SchemaStatements#resolve_data_source_name with a single
DBMS_UTILITY.NAME_RESOLVE PL/SQL call. Private and public synonyms
are chased server-side, so the iterative loop + visited Set used to
guard against circular synonyms is no longer needed -- Oracle
reports a cycle natively as ORA-00980 ("synonym translation is no
longer valid").

DBMS_UTILITY.NAME_RESOLVE is documented for Oracle 8i (released
1999), so version support is not a concern on any supported
release. See the Oracle8i Supplied PL/SQL Packages Reference,
Release 2 (8.1.6), A76936-01:
https://docs.oracle.com/cd/A87860_01/doc/appdev.817/a76936/dbms_uti.htm

Design notes

  1. Driver-layer helpers. OCIConnection#name_resolve uses an
     anonymous PL/SQL block with named binds. JDBCConnection#name_resolve
     uses CallableStatement + registerOutParameter. Both return
     [schema, object_name]; the caller is the adapter's
     SchemaStatements mix-in, not the raw driver.

  2. Instrumentation preserved. NAME_RESOLVE bypasses select_one
     entirely, so we wrap the call in an explicit sql.active_record
     SCHEMA notification. The regression spec that subscribes to
     that event and was introduced alongside the move-describe
     refactor stays green.

  3. Case handling. NAME_RESOLVE uppercases unquoted input, so
     mixed-case identifiers like "test_Mixed" fail with ORA-06564
     unless quoted. normalize_name_for_name_resolve upcases each
     dotted part when the part is a valid unquoted identifier and
     wraps it in double quotes otherwise; "sys.test_Mixed" becomes
     SYS."test_Mixed" rather than the all-quoted
     "sys"."test_Mixed" that would send Oracle hunting for a
     lowercase schema.

  4. context=0. NAME_RESOLVE's context argument matters:
     context=1 covers PL/SQL objects only and raises ORA-04047 for
     tables/views. context=0 covers tables, views, and synonyms.

Trade-off: the select_one-based resolve_data_source_name benefits
from the AR query cache on repeated describes in the same scope;
NAME_RESOLVE always hits the server. The win is round-trip count
(one call instead of UNION ALL + synonym loop), which dominates
on cold-cache / synonym-heavy schemas -- see benchmark results in
PR rsim#2531.

The benchmark script (script/benchmark_describe.rb) is retargeted
to adapter.send(:resolve_data_source_name, name) so all three
implementations (master UNION ALL, PR rsim#2521 all_objects, this POC)
can be measured against a shared 1000-object fixture. A
before(:suite) PURGE RECYCLEBIN hook keeps the suite from
accumulating stale BIN$... dictionary rows across rspec runs.
create_oracle_enhanced_users.sql adds CREATE/DROP PUBLIC SYNONYM
grants required by the benchmark's public-synonym fixtures.

Full rspec suite:
  - CRuby 4.0.2:  453 examples, 0 failures, 6 pending
  - JRuby 10.0.5.0: 458 examples, 0 failures, 6 pending

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: yahonda

lib/active_record/connection_adapters/oracle_enhanced/jdbc_connection.rb

@@ -306,6 +306,25 @@ def database_version
           @database_version ||= (md = raw_connection.getMetaData) && [md.getDatabaseMajorVersion, md.getDatabaseMinorVersion]
         end
 
+        # Resolve a schema object (table, view, synonym) to [owner, object_name]
+        # in a single round trip via DBMS_UTILITY.NAME_RESOLVE. Private and
+        # public synonyms are chased server-side, and Oracle raises ORA-01775
+        # natively on a looping chain.
+        def name_resolve(name)
+          cs = @raw_connection.prepareCall("BEGIN DBMS_UTILITY.NAME_RESOLVE(?, 0, ?, ?, ?, ?, ?, ?); END;")
+          cs.setString(1, name)
+          cs.registerOutParameter(2, java.sql.Types::VARCHAR) # schema
+          cs.registerOutParameter(3, java.sql.Types::VARCHAR) # part1 (object name)
+          cs.registerOutParameter(4, java.sql.Types::VARCHAR) # part2
+          cs.registerOutParameter(5, java.sql.Types::VARCHAR) # dblink
+          cs.registerOutParameter(6, java.sql.Types::NUMERIC) # part1_type
+          cs.registerOutParameter(7, java.sql.Types::NUMERIC) # object_number
+          cs.execute
+          [cs.getString(2), cs.getString(3)]
+        ensure
+          cs&.close
+        end
+
         class Cursor
           def initialize(connection, raw_statement, exec_sql = nil)
             @raw_connection = connection

lib/active_record/connection_adapters/oracle_enhanced/oci_connection.rb

@@ -109,6 +109,31 @@ def prepare(sql)
           Cursor.new(self, @raw_connection.parse(sql))
         end
 
+        # Resolve a schema object (table, view, synonym) to [owner, object_name]
+        # in a single round trip via DBMS_UTILITY.NAME_RESOLVE. Private and
+        # public synonyms are chased server-side, and Oracle raises ORA-01775
+        # natively on a looping chain.
+        def name_resolve(name)
+          cursor = @raw_connection.parse(<<~PLSQL)
+            DECLARE
+              l_part2   VARCHAR2(128);
+              l_dblink  VARCHAR2(128);
+              l_type    NUMBER;
+              l_obj_num NUMBER;
+            BEGIN
+              DBMS_UTILITY.NAME_RESOLVE(:name, 0, :out_schema, :out_name,
+                                        l_part2, l_dblink, l_type, l_obj_num);
+            END;
+          PLSQL
+          cursor.bind_param(":name", name)
+          cursor.bind_param(":out_schema", nil, String, 128)
+          cursor.bind_param(":out_name", nil, String, 128)
+          cursor.exec
+          [cursor[":out_schema"], cursor[":out_name"]]
+        ensure
+          cursor&.close
+        end
+
         class Cursor
           def initialize(connection, raw_cursor)
             @raw_connection = connection

lib/active_record/connection_adapters/oracle_enhanced/schema_statements.rb

@@ -912,64 +912,50 @@ def rebuild_primary_key_index_to_default_tablespace(table_name, options)
           end
 
           # Resolves an Oracle data-source name to its underlying [owner, table_name]
-          # by following synonyms through the catalog. Defaults the schema to
-          # `_connection.owner` (the adapter's configured default schema, taken
-          # from `config[:schema]` or `config[:username]`) when the name is not
-          # schema-qualified. This is distinct from
-          # `SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA')`, which can differ after
-          # `ALTER SESSION SET CURRENT_SCHEMA`.
-          # Raises OracleEnhanced::ConnectionException if the object does not
-          # exist or if synonym resolution produces a looping chain.
+          # via DBMS_UTILITY.NAME_RESOLVE, which chases private and public
+          # synonyms server-side in a single round trip. NAME_RESOLVE raises
+          # ORA-01775 ("looping chain of synonyms") natively on a cycle, which
+          # we let propagate as OracleEnhanced::ConnectionException.
+          #
+          # The PL/SQL call bypasses the adapter's select_one path, so we wrap
+          # it in a sql.active_record SCHEMA notification to keep describe
+          # visible to logging and instrumentation subscribers.
           def resolve_data_source_name(name)
-            visited = Set.new
-            loop do
-              schema, identifier = extract_schema_qualified_name(name)
-              real_name = schema ? "#{schema}.#{identifier}" : identifier
-              owner = schema || _connection.owner
-
-              unless visited.add?([owner, identifier])
-                raise OracleEnhanced::ConnectionException,
-                      %Q{"DESC #{name}" failed; looping chain of synonyms}
-              end
-
-              binds = [
-                bind_string("table_owner", owner),
-                bind_string("table_name", identifier),
-                bind_string("real_name", real_name),
-              ]
-              # Single-pass lookup against all_objects, ordered so the first row
-              # is the one the legacy 4-way UNION ALL (all_tables, all_views,
-              # owner synonym, public synonym) would have returned: prefer a
-              # match in the caller's schema over PUBLIC, and within a schema
-              # prefer TABLE over VIEW over SYNONYM.
-              result = select_one(<<~SQL.squish, "SCHEMA", binds)
-                SELECT owner, object_name table_name, object_type name_type
-                FROM all_objects
-                WHERE ((owner = :table_owner AND object_name = :table_name)
-                   OR (owner = 'PUBLIC' AND object_name = :real_name))
-                  AND object_type IN ('TABLE', 'VIEW', 'SYNONYM')
-                ORDER BY DECODE(owner, 'PUBLIC', 2, 1),
-                         DECODE(object_type, 'TABLE', 1, 'VIEW', 2, 'SYNONYM', 3)
-              SQL
-
-              raise OracleEnhanced::ConnectionException, %Q{"DESC #{name}" failed; does it exist?} unless result
-
-              if result["name_type"] == "SYNONYM"
-                synonym_binds = [
-                  bind_string("owner", result["owner"]),
-                  bind_string("synonym_name", result["table_name"]),
-                ]
-                syn = select_one(<<~SQL.squish, "SCHEMA", synonym_binds)
-                  SELECT table_owner, table_name
-                  FROM all_synonyms
-                  WHERE owner = :owner AND synonym_name = :synonym_name
-                SQL
-                raise OracleEnhanced::ConnectionException, %Q{"DESC #{name}" failed; does it exist?} unless syn
-                name = "#{syn['table_owner'] && "#{syn['table_owner']}."}#{syn['table_name']}"
-              else
-                return [result["owner"], result["table_name"]]
-              end
+            real_name = normalize_name_for_name_resolve(name)
+            instrumenter.instrument(
+              "sql.active_record",
+              sql: "DBMS_UTILITY.NAME_RESOLVE(#{real_name.inspect}, 0, ...)",
+              name: "SCHEMA",
+              connection: self,
+            ) do
+              _connection.name_resolve(real_name)
             end
+          rescue OracleEnhanced::ConnectionException, ArgumentError
+            raise
+          rescue => e
+            raise OracleEnhanced::ConnectionException,
+                  %Q{"DESC #{name}" failed; does it exist? (#{e.message})}
+          end
+
+          # Normalize a data-source name for DBMS_UTILITY.NAME_RESOLVE.
+          # NAME_RESOLVE uppercases unquoted identifiers, so mixed-case
+          # identifiers like `test_Mixed` must be wrapped in double quotes to
+          # preserve their case. Normalization is per-dotted-part: a valid
+          # unquoted identifier (all upper, no spaces, etc.) is upcased in
+          # place; any other part is wrapped in quotes. This lets
+          # `sys.test_Mixed` become `SYS."test_Mixed"` rather than the
+          # all-quoted `"sys"."test_Mixed"` (which would send Oracle hunting
+          # for a lowercase schema and miss SYS).
+          def normalize_name_for_name_resolve(name)
+            name = name.to_s
+            raise ArgumentError, "db link is not supported" if name.include?("@")
+
+            limit = max_identifier_length
+            return name.upcase if OracleEnhanced::Quoting.valid_table_name?(name, max_identifier_length: limit)
+
+            name.split(".").map do |part|
+              OracleEnhanced::Quoting.valid_table_name?(part, max_identifier_length: limit) ? part.upcase : %("#{part}")
+            end.join(".")
           end
 
           # Splits "schema.identifier" into its parts, returning [schema, identifier].

script/benchmark_describe.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# Benchmark for OracleEnhanced::SchemaStatements#resolve_data_source_name
+# (the method adapters use to resolve a table / view / synonym name to its
+# underlying [owner, object_name] pair -- formerly Connection#describe).
+#
+# Intent: compare the resolve_data_source_name implementations across
+#   - master: UNION ALL over all_tables/all_views/all_synonyms (select_one)
+#   - PR #2521 branch (add-describe-regression-test): single all_objects query
+#   - poc-dbms-utility-name-resolve: DBMS_UTILITY.NAME_RESOLVE
+#
+# The fixture models the production scenario from #2429: ~1000 objects in
+# the schema (700 tables, 100 views, 100 private synonyms, 100 public
+# synonyms).
+#
+# Usage (from repo root):
+#   bundle exec ruby script/benchmark_describe.rb                 # setup + run + teardown
+#   SKIP_SETUP=1 bundle exec ruby script/benchmark_describe.rb    # reuse previous fixtures
+#   SKIP_TEARDOWN=1 bundle exec ruby script/benchmark_describe.rb # keep fixtures for next run
+#
+# Environment variables honored (same defaults as spec_helper.rb):
+#   DATABASE_NAME, DATABASE_HOST, DATABASE_PORT, DATABASE_USER,
+#   DATABASE_PASSWORD, ITERATIONS, TABLE_COUNT, VIEW_COUNT, SYNONYM_COUNT.
+
+require "bundler/setup"
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "oci8" if RUBY_ENGINE == "ruby"
+require "active_record"
+require "active_record/connection_adapters/oracle_enhanced_adapter"
+
+TABLE_COUNT   = Integer(ENV["TABLE_COUNT"]   || 700)
+VIEW_COUNT    = Integer(ENV["VIEW_COUNT"]    || 100)
+SYNONYM_COUNT = Integer(ENV["SYNONYM_COUNT"] || 200) # half private, half public
+ITERATIONS    = Integer(ENV["ITERATIONS"]    || 1)
+SKIP_SETUP    = ENV["SKIP_SETUP"]    == "1"
+SKIP_TEARDOWN = ENV["SKIP_TEARDOWN"] == "1"
+
+ActiveRecord::Base.establish_connection(
+  adapter:  "oracle_enhanced",
+  database: ENV["DATABASE_NAME"]     || "XEPDB1",
+  host:     ENV["DATABASE_HOST"]     || "127.0.0.1",
+  port:     Integer(ENV["DATABASE_PORT"] || 1521),
+  username: ENV["DATABASE_USER"]     || "oracle_enhanced",
+  password: ENV["DATABASE_PASSWORD"] || "oracle_enhanced"
+)
+
+conn  = ActiveRecord::Base.connection
+owner = (ENV["DATABASE_USER"] || "oracle_enhanced").upcase
+
+def t(label)
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  yield
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+  printf("%-20s %8.2fs\n", label, elapsed)
+end
+
+def safe_exec(conn, sql)
+  conn.execute(sql)
+rescue ActiveRecord::StatementInvalid
+  # idempotent: ignore "already exists" / "does not exist"
+end
+
+table_names   = (1..TABLE_COUNT).map { |i| "bench_tbl_%04d" % i }
+view_names    = (1..VIEW_COUNT).map  { |i| "bench_vw_%04d"  % i }
+priv_syn_half = SYNONYM_COUNT / 2
+pub_syn_half  = SYNONYM_COUNT - priv_syn_half
+priv_synonyms = (1..priv_syn_half).map { |i| "bench_syn_%04d" % i }
+pub_synonyms  = (1..pub_syn_half).map  { |i| "bench_pub_%04d" % i }
+
+unless SKIP_SETUP
+  puts "==> Creating #{TABLE_COUNT} tables, #{VIEW_COUNT} views, " \
+       "#{priv_syn_half} private + #{pub_syn_half} public synonyms"
+  t("create tables") do
+    table_names.each { |n| safe_exec conn, "CREATE TABLE #{n} (id NUMBER)" }
+  end
+  t("create views") do
+    view_names.each_with_index do |vn, i|
+      safe_exec conn, "CREATE VIEW #{vn} AS SELECT * FROM #{table_names[i % TABLE_COUNT]}"
+    end
+  end
+  t("create synonyms") do
+    priv_synonyms.each_with_index do |sn, i|
+      safe_exec conn, "CREATE SYNONYM #{sn} FOR #{table_names[i % TABLE_COUNT]}"
+    end
+    pub_synonyms.each_with_index do |sn, i|
+      safe_exec conn, "CREATE PUBLIC SYNONYM #{sn} FOR #{owner}.#{table_names[i % TABLE_COUNT]}"
+    end
+  end
+end
+
+begin
+  all_names = table_names + view_names + priv_synonyms + pub_synonyms
+
+  # Warm-up pass so dictionary-cache / shared-pool state is primed; the
+  # first resolve_data_source_name after login otherwise dominates wall clock.
+  all_names.first(50).each { |n| conn.send(:resolve_data_source_name, n) }
+
+  head_branch = `git rev-parse --abbrev-ref HEAD`.strip
+  head_sha    = `git rev-parse --short HEAD`.strip
+  puts
+  puts "==> branch: #{head_branch} (#{head_sha})"
+  puts "==> fixtures: #{TABLE_COUNT} tables, #{VIEW_COUNT} views, " \
+       "#{priv_syn_half} private synonyms, #{pub_syn_half} public synonyms"
+  puts "==> resolve_data_source_name calls per pass: #{all_names.size}"
+  puts "==> passes: #{ITERATIONS}"
+  puts
+
+  printf("%-20s %10s %10s\n", "case", "wall(s)", "avg(ms)")
+  cases = {
+    "tables"          => table_names,
+    "views"           => view_names,
+    "private synonyms" => priv_synonyms,
+    "public synonyms"  => pub_synonyms,
+    "all mixed"        => all_names.shuffle,
+  }
+  cases.each do |label, names|
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    ITERATIONS.times { names.each { |n| conn.send(:resolve_data_source_name, n) } }
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+    per_call_ms = (elapsed * 1000.0) / (ITERATIONS * names.size)
+    printf("%-20s %10.3f %10.3f\n", label, elapsed, per_call_ms)
+  end
+ensure
+  unless SKIP_TEARDOWN
+    puts
+    puts "==> Dropping fixtures"
+    t("drop public syns") { pub_synonyms.each  { |n| safe_exec conn, "DROP PUBLIC SYNONYM #{n}" } }
+    t("drop private syns") { priv_synonyms.each { |n| safe_exec conn, "DROP SYNONYM #{n}" } }
+    t("drop views")        { view_names.each    { |n| safe_exec conn, "DROP VIEW #{n}" } }
+    t("drop tables")       { table_names.each   { |n| safe_exec conn, "DROP TABLE #{n} PURGE" } }
+  end
+end

spec/active_record/connection_adapters/oracle_enhanced/connection_spec.rb

@@ -799,10 +799,10 @@ def resolve(name)
     # Exercises all five catalog paths (table, view, materialized view,
     # private synonym, public synonym) for one underlying table in a single
     # run. The individual cases above use disjoint fixtures; this one proves
-    # the DECODE-ordered all_objects lookup + synonym follow-through stays
-    # consistent when a private and a public synonym to the same table
-    # coexist, and that a materialized view created on the same base table
-    # resolves to the MV name (not the base table) as a sibling data source.
+    # NAME_RESOLVE stays consistent when a private and a public synonym to
+    # the same table coexist, and that a materialized view created on the
+    # same base table resolves to the MV name (not the base table) as a
+    # sibling data source.
     it "resolves table, view, materialized view, private synonym and public synonym for the same underlying table" do
       @conn.execute "CREATE TABLE test_describe_all (id NUMBER)" rescue nil
       @conn.execute "CREATE VIEW test_describe_all_v AS SELECT * FROM test_describe_all" rescue nil
@@ -823,12 +823,28 @@ def resolve(name)
       @conn.execute "DROP TABLE test_describe_all" rescue nil
     end
 
+    # Mixed-case quoted identifiers need per-dotted-part quoting before
+    # reaching DBMS_UTILITY.NAME_RESOLVE: the schema should be upcased and
+    # left unquoted, but the case-preserving table name must be wrapped in
+    # double quotes so Oracle doesn't uppercase it away.
+    it "should resolve a mixed-case quoted table qualified with its owner" do
+      @conn.execute %{CREATE TABLE "test_Mixed_Case_Desc" (id NUMBER)} rescue nil
+      expect(resolve(%{#{@owner}.test_Mixed_Case_Desc})).to eq([@owner, "test_Mixed_Case_Desc"])
+    ensure
+      @conn.execute %{DROP TABLE "test_Mixed_Case_Desc"} rescue nil
+    end
+
+    # DBMS_UTILITY.NAME_RESOLVE chases synonyms server-side, so a circular
+    # chain surfaces as ORA-00980 ("synonym translation is no longer valid")
+    # rather than SQL's ORA-01775 ("looping chain of synonyms"). The thing
+    # that matters either way: no Ruby-side stack overflow, a clean
+    # ConnectionException.
     it "raises when synonym resolution produces a looping chain" do
       @conn.execute "CREATE SYNONYM test_cycle_a FOR test_cycle_b" rescue nil
       @conn.execute "CREATE SYNONYM test_cycle_b FOR test_cycle_a" rescue nil
       expect { resolve("test_cycle_a") }.to raise_error(
         ActiveRecord::ConnectionAdapters::OracleEnhanced::ConnectionException,
-        /looping chain of synonyms/
+        /ORA-00980/
       )
     ensure
       @conn.execute "DROP SYNONYM test_cycle_a" rescue nil
@@ -841,7 +857,7 @@ def resolve(name)
       @conn.execute "CREATE SYNONYM test_cycle_c FOR test_cycle_a" rescue nil
       expect { resolve("test_cycle_a") }.to raise_error(
         ActiveRecord::ConnectionAdapters::OracleEnhanced::ConnectionException,
-        /looping chain of synonyms/
+        /ORA-00980/
       )
     ensure
       @conn.execute "DROP SYNONYM test_cycle_a" rescue nil