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  |

Numbers measured against an out-of-tree benchmark script (kept on the
POC branch rsim#2566); the gem itself does not ship a benchmark file.

Implementation:

- OUT-bind plumbing on both the OCI8 path (anonymous PL/SQL block
  with named binds) and the JDBC path (`CallableStatement` +
  `registerOutParameter`). Both wrap the call in `with_retry` so a
  stale connection is marked dead consistently with the rest of the
  adapter.
- `normalize_name_for_name_resolve` preserves case for already-quoted
  identifiers (e.g. `"test_Mixed_Case_Desc"`) and doubles embedded
  `"` characters in unquoted parts (Oracle's `""` escape). Without
  this, `%("#{part}")` would re-quote an already-quoted part,
  producing `""test_Mixed""` and raising ORA-01741.
- `split_dotted_name` is a quote-aware splitter so `"Foo.Bar"`
  (quoted dot) survives intact, including the `""` escape sequence
  inside a quoted identifier.
- Malformed identifiers raise `ArgumentError` up-front instead of
  being silently mangled and rejected by Oracle as an unhelpful
  `ConnectionException`. Three shapes are caught:
  * empty parts (`schema..table`, `.foo`, `foo.`)
  * three or more parts (`schema."table".extra` — NAME_RESOLVE with
    `context = 0` only accepts `schema.object`)
  * half-quoted parts (`"foo`, `foo"` — opens a quoted identifier
    that never closes, or vice versa). Embedded `"` mid-part
    (`Test"x`) is still allowed; it goes through the quote-and-
    double-escape branch.
- DB-link names (`name@db_link`) are rejected up-front with
  `ArgumentError` — `data_source_exists?` is not the right entry
  point for resolving remote objects.
- Circular synonyms surface as ORA-00980 from NAME_RESOLVE, wrapped
  as `OracleEnhanced::ConnectionException`. No Ruby-side stack
  overflow, clean error.
- `resolve_data_source_name` keeps master's contract: raise
  `OracleEnhanced::ConnectionException` for a non-existent name so
  `data_source_exists?`'s `rescue` returns false.
- The new path runs through an anonymous PL/SQL block (OCI) /
  `CallableStatement` (JDBC), bypassing `select_one`. The
  `sql.active_record` SCHEMA notification is preserved via explicit
  `instrumenter.instrument`, so logging and other subscribers keep
  seeing the describe call.

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

@@ -967,64 +967,99 @@ 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)
+            if parts.empty? || parts.any?(&:empty?) || parts.length > 2
+              raise ArgumentError, "malformed identifier: #{name.inspect}"
+            end
+
+            parts.map do |part|
+              if part.start_with?('"') && part.end_with?('"') && part.size >= 2
+                part
+              elsif part.start_with?('"') || part.end_with?('"')
+                # Half-quoted: opens with `"` but never closes (or vice versa).
+                # `Test"x` (embedded `"` mid-identifier) is allowed via the
+                # quote-and-double-escape branch below; `"foo` is not.
+                raise ArgumentError, "malformed identifier: #{name.inspect}"
+              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].

spec/active_record/connection_adapters/oracle_enhanced/connection_spec.rb

@@ -972,10 +972,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)"
       @conn.execute "CREATE VIEW test_describe_all_v AS SELECT * FROM test_describe_all"
@@ -996,12 +996,81 @@ def resolve(name)
       @conn.drop_table("test_describe_all", if_exists: true)
     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)}
+      expect(resolve(%{#{@owner}.test_Mixed_Case_Desc})).to eq([@owner, "test_Mixed_Case_Desc"])
+    ensure
+      @conn.drop_table "test_Mixed_Case_Desc", if_exists: true
+    end
+
+    # Local objects shadow same-named public synonyms — the precedence the
+    # legacy SQL encoded explicitly (ORDER BY DECODE(owner, 'PUBLIC', 2, 1)).
+    # NAME_RESOLVE relies on Oracle's parser rules for the same outcome.
+    # CREATE statements are not rescued so a future identifier-too-long
+    # regression cannot silently turn this into a no-op (see the sibling
+    # private-vs-public spec for the full story).
+    it "prefers a local table over a same-named public synonym" do
+      @conn.execute "CREATE TABLE test_prec_local (id NUMBER)"
+      @conn.execute "CREATE PUBLIC SYNONYM test_prec_local FOR sys.dual"
+      expect(resolve("test_prec_local")).to eq([@owner, "TEST_PREC_LOCAL"])
+    ensure
+      @conn.drop_if_exists("PUBLIC SYNONYM", "test_prec_local")
+      @conn.drop_table("test_prec_local", if_exists: true)
+    end
+
+    # Local objects (and private synonyms in the current schema) shadow
+    # same-named public synonyms — the precedence the legacy SQL encoded
+    # explicitly. NAME_RESOLVE relies on Oracle's parser rules for the
+    # same outcome.
+    #
+    # Identifiers are kept under 30 characters so the spec works on Oracle
+    # 11g XE (identifier max length 30) as well as 12.2+ (max 128). CREATE
+    # statements are not rescued — a `rescue nil` here previously hid a
+    # silent ORA-00972 (identifier too long) on 11g, which left only the
+    # PUBLIC SYNONYM in place and made resolve return [SYS, DUAL].
+    it "prefers a private synonym over a same-named public synonym" do
+      @conn.execute "CREATE TABLE test_prec_target (id NUMBER)"
+      @conn.execute "CREATE SYNONYM test_prec_syn FOR test_prec_target"
+      @conn.execute "CREATE PUBLIC SYNONYM test_prec_syn FOR sys.dual"
+      expect(resolve("test_prec_syn")).to eq([@owner, "TEST_PREC_TARGET"])
+    ensure
+      @conn.drop_if_exists("PUBLIC SYNONYM", "test_prec_syn")
+      @conn.drop_if_exists("SYNONYM", "test_prec_syn")
+      @conn.drop_table("test_prec_target", if_exists: true)
+    end
+
+    it "raises ArgumentError for malformed identifiers with empty parts" do
+      expect { resolve("schema..table") }.to raise_error(ArgumentError, /malformed identifier/)
+    end
+
+    it "raises ArgumentError for an unbalanced double quote" do
+      expect { resolve(%{"foo}) }.to raise_error(ArgumentError, /malformed identifier/)
+    end
+
+    it "raises ArgumentError for a three-part name" do
+      expect { resolve(%{schema."table".extra}) }.to raise_error(ArgumentError, /malformed identifier/)
+    end
+
+    it "doubles embedded double-quote characters when wrapping an unquoted identifier" do
+      result = @conn.send(:normalize_name_for_name_resolve, %{Test"x})
+      expect(result).to eq(%{"Test""x"})
+    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"
       @conn.execute "CREATE SYNONYM test_cycle_b FOR test_cycle_a"
       expect { resolve("test_cycle_a") }.to raise_error(
         ActiveRecord::ConnectionAdapters::OracleEnhanced::ConnectionException,
-        /looping chain of synonyms/
+        /ORA-00980/
       )
     ensure
       @conn.drop_if_exists("SYNONYM", "test_cycle_a")
@@ -1014,7 +1083,7 @@ def resolve(name)
       @conn.execute "CREATE SYNONYM test_cycle_c FOR test_cycle_a"
       expect { resolve("test_cycle_a") }.to raise_error(
         ActiveRecord::ConnectionAdapters::OracleEnhanced::ConnectionException,
-        /looping chain of synonyms/
+        /ORA-00980/
       )
     ensure
       @conn.drop_if_exists("SYNONYM", "test_cycle_a")
@@ -1026,11 +1095,28 @@ def resolve(name)
       expect { resolve("test@db_link") }.to raise_error(ArgumentError, /db link is not supported/)
     end
 
-    # The previous Connection#describe path bypassed the adapter's query machinery
-    # by driving a raw cursor, so its catalog lookup produced no sql.active_record
-    # event. Routing through select_one(..., "SCHEMA", ...) makes the lookup
-    # participate in logging, instrumentation, and the query cache. Lock that in
-    # so a future refactor can't silently regress to the raw-cursor path.
+    it "raises ConnectionException for a non-existent object" do
+      expect { resolve("test_nonexistent_object_xyz") }.to raise_error(
+        ActiveRecord::ConnectionAdapters::OracleEnhanced::ConnectionException,
+        /does it exist/
+      )
+    end
+
+    it "preserves dots inside a quoted identifier" do
+      result = @conn.send(:normalize_name_for_name_resolve, %{"Foo.Bar"})
+      expect(result).to eq(%{"Foo.Bar"})
+    end
+
+    it "preserves dots inside the quoted part of a schema-qualified name" do
+      result = @conn.send(:normalize_name_for_name_resolve, %{SCHEMA."Foo.Bar"})
+      expect(result).to eq(%{SCHEMA."Foo.Bar"})
+    end
+
+    # The lookup runs DBMS_UTILITY.NAME_RESOLVE wrapped in
+    # `instrumenter.instrument` (sql.active_record, name: "SCHEMA"),
+    # so it shows up in logging and instrumentation subscribers.
+    # Lock that in so a future refactor can't silently drop the
+    # instrumentation.
     it "emits a SCHEMA sql.active_record event for the catalog lookup" do
       @conn.execute "CREATE TABLE test_employees (first_name VARCHAR2(20))"
       events = []