POC: resolve describe() via DBMS_UTILITY.NAME_RESOLVE

yahonda · claude · yahonda · commit 2e9f613af2ee · 2026-04-21T08:42:05.000+09:00
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>
diff --git a/lib/active_record/connection_adapters/oracle_enhanced/jdbc_connection.rb b/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
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
@@ -735,57 +735,49 @@ 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("table_owner", owner),
-                bind_string("table_name", identifier),
-                bind_string("table_owner", owner),
-                bind_string("table_name", identifier),
-                bind_string("real_name", real_name),
-              ]
-              result = select_one(<<~SQL.squish, "SCHEMA", binds)
-                SELECT owner, table_name, 'TABLE' name_type
-                FROM all_tables WHERE owner = :table_owner AND table_name = :table_name
-                UNION ALL
-                SELECT owner, view_name table_name, 'VIEW' name_type
-                FROM all_views WHERE owner = :table_owner AND view_name = :table_name
-                UNION ALL
-                SELECT table_owner, table_name, 'SYNONYM' name_type
-                FROM all_synonyms WHERE owner = :table_owner AND synonym_name = :table_name
-                UNION ALL
-                SELECT table_owner, table_name, 'SYNONYM' name_type
-                FROM all_synonyms WHERE owner = 'PUBLIC' AND synonym_name = :real_name
-              SQL
-
-              raise OracleEnhanced::ConnectionException, %Q{"DESC #{name}" failed; does it exist?} unless result
-
-              if result["name_type"] == "SYNONYM"
-                name = "#{result['owner'] && "#{result['owner']}."}#{result['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?("@")
+
+            return name.upcase if OracleEnhanced::Quoting.valid_table_name?(name)
+
+            name.split(".").map do |part|
+              OracleEnhanced::Quoting.valid_table_name?(part) ? part.upcase : %("#{part}")
+            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
@@ -734,12 +734,28 @@ def resolve(name)
       expect(resolve("all_tables")).to eq(["SYS", "ALL_TABLES"])
     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
@@ -752,7 +768,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
diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb
@@ -205,3 +205,10 @@ def dump_table_schema(table, connection = ActiveRecord::Base.connection)
 ENV["TZ"] ||= config["timezone"] || "Europe/Riga"
 
 ActiveRecord::Base.logger = ActiveSupport::Logger.new("debug.log", 0, 100 * 1024 * 1024)
+
+RSpec.configure do |config|
+  config.before(:suite) do
+    ActiveRecord::Base.establish_connection(CONNECTION_PARAMS)
+    ActiveRecord::Base.connection.execute("PURGE RECYCLEBIN")
+  end
+end
diff --git a/spec/support/create_oracle_enhanced_users.sql b/spec/support/create_oracle_enhanced_users.sql
@@ -4,10 +4,12 @@ CREATE USER oracle_enhanced IDENTIFIED BY oracle_enhanced;
 
 GRANT unlimited tablespace, create session, create table, create sequence,
 create procedure, create trigger, create view, create materialized view,
-create database link, create synonym, create type, ctxapp TO oracle_enhanced;
+create database link, create synonym, create public synonym, create type, ctxapp TO oracle_enhanced;
+GRANT drop public synonym TO oracle_enhanced;
 
 CREATE USER oracle_enhanced_schema IDENTIFIED BY oracle_enhanced_schema;
 
 GRANT unlimited tablespace, create session, create table, create sequence,
 create procedure, create trigger, create view, create materialized view,
-create database link, create synonym, create type, ctxapp TO oracle_enhanced_schema;
+create database link, create synonym, create public synonym, create type, ctxapp TO oracle_enhanced_schema;
+GRANT drop public synonym TO oracle_enhanced_schema;
