Resolve describe() via DBMS_UTILITY.NAME_RESOLVE

yahonda · claude · yahonda · commit 4a29929102a3 · 2026-05-04T01:10:04.000+09:00
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>
diff --git a/lib/active_record/connection_adapters/oracle_enhanced/jdbc_connection.rb b/lib/active_record/connection_adapters/oracle_enhanced/jdbc_connection.rb
@@ -325,6 +325,25 @@ 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-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
diff --git a/lib/active_record/connection_adapters/oracle_enhanced/oci_connection.rb b/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
diff --git a/lib/active_record/connection_adapters/oracle_enhanced/schema_statements.rb b/lib/active_record/connection_adapters/oracle_enhanced/schema_statements.rb
@@ -931,64 +931,56 @@ 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']}"
+            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|
+              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
-                return [result["owner"], result["table_name"]]
+                %("#{part}")
               end
-            end
+            end.join(".")
           end
 
           # Splits "schema.identifier" into its parts, returning [schema, identifier].
diff --git a/script/benchmark_describe.rb b/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
diff --git a/spec/active_record/connection_adapters/oracle_enhanced/connection_spec.rb b/spec/active_record/connection_adapters/oracle_enhanced/connection_spec.rb
@@ -961,10 +961,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
@@ -985,12 +985,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
@@ -1003,7 +1019,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
