Resolve describe() via DBMS_UTILITY.NAME_RESOLVE

Replaces the catalog-based `resolve_data_source_name` (single
all_objects query + secondary all_synonyms lookup since rsim#2521) with a
`DBMS_UTILITY.NAME_RESOLVE` call. NAME_RESOLVE chases private and
public synonyms inside the PL/SQL engine and returns
`[owner, object_name]` in one round trip, so the work does not depend
on `ALL_*` dictionary-view cost — the failure mode that rsim#2521's
secondary `all_synonyms` lookup leaves behind on synonym-heavy
schemas.

Now that PR rsim#2513 has landed `DBMS_METADATA.GET_DDL` in the adapter,
using another `DBMS_*` package is no longer a style break.

Benchmark on Oracle 23ai with a 1000-object fixture (700 tables +
100 views + 100 private synonyms + 100 public synonyms):

| case             | master   | this PR  | speedup |
|------------------|---------:|---------:|--------:|
| tables           |  0.384ms |  0.300ms |   1.3x  |
| views            |  0.364ms |  0.303ms |   1.2x  |
| private synonyms | 13.031ms |  0.447ms |    29x  |
| public synonyms  |  1.723ms |  0.454ms |   3.8x  |
| all mixed        |  0.578ms |  0.265ms |   2.2x  |

Implementation:
- OUT-bind plumbing on both the OCI8 path (anonymous PL/SQL block
  with named binds) and the JDBC path (`CallableStatement` +
  `registerOutParameter`).
- `normalize_name_for_name_resolve` preserves case for already-quoted
  identifiers (e.g. `"test_Mixed"`). Previously `%("#{part}")` would
  re-quote an already-quoted part, producing `""test_Mixed""` and
  raising ORA-01741.
- `resolve_data_source_name` keeps master's contract: raise
  `OracleEnhanced::ConnectionException` for a non-existent name so
  `data_source_exists?`'s `rescue` returns false.

Benchmark script (`script/benchmark_describe.rb`) carried over from
the POC reference at rsim#2566.

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

Author: yahonda

lib/active_record/connection_adapters/oracle_enhanced/jdbc_connection.rb

@@ -325,6 +325,30 @@ def database_version
           end
         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-00980
+        # ("synonym translation is no longer valid") natively on a looping chain.
+        def name_resolve(name)
+          with_retry do
+            # Parameters 4-7 are required by NAME_RESOLVE's signature but unused here.
+            cs = @raw_connection.prepareCall("BEGIN DBMS_UTILITY.NAME_RESOLVE(?, 0, ?, ?, ?, ?, ?, ?); END;")
+            begin
+              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
+          end
+        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,36 @@ 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-00980
+        # ("synonym translation is no longer valid") natively on a looping chain.
+        def name_resolve(name)
+          with_retry do
+            # l_part2 / l_dblink / l_type / l_obj_num are required by NAME_RESOLVE's signature but unused here.
+            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
+            begin
+              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
+          end
+        end
+
         class Cursor
           def initialize(connection, raw_cursor)
             @raw_connection = connection

lib/active_record/connection_adapters/oracle_enhanced/schema_statements.rb

@@ -931,64 +931,92 @@ 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 surfaces
+          # circular synonym chains as ORA-00980 ("synonym translation is no
+          # longer valid"), 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}
+            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)
+
+            parts = split_dotted_name(name)
+            raise ArgumentError, "malformed identifier: #{name.inspect}" if parts.empty? || parts.any?(&:empty?)
+
+            parts.map do |part|
+              if part.start_with?('"') && part.end_with?('"') && part.size >= 2
+                part
+              elsif OracleEnhanced::Quoting.valid_table_name?(part, max_identifier_length: limit)
+                part.upcase
+              else
+                # Oracle quoted identifier syntax: an embedded `"` must be doubled.
+                %("#{part.gsub('"', '""')}")
               end
+            end.join(".")
+          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']}"
+          # Splits a dotted Oracle name on `.` boundaries while leaving dots
+          # that appear inside double-quoted identifiers untouched. Honours
+          # the `""` escape sequence Oracle uses for an embedded `"` inside
+          # a quoted identifier.
+          def split_dotted_name(name)
+            parts = []
+            current = +""
+            in_quotes = false
+            i = 0
+            while i < name.length
+              char = name[i]
+              if char == '"'
+                if in_quotes && name[i + 1] == '"'
+                  current << '""'
+                  i += 2
+                  next
+                end
+                in_quotes = !in_quotes
+                current << char
+              elsif char == "." && !in_quotes
+                parts << current
+                current = +""
               else
-                return [result["owner"], result["table_name"]]
+                current << char
               end
+              i += 1
             end
+            parts << current
+            parts
           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