POC: resolve describe() via DBMS_UTILITY.NAME_RESOLVE

Per the suggestion in
rsim#2521 (comment),
replace the UNION ALL query against all_tables / all_views / all_synonyms
with a single DBMS_UTILITY.NAME_RESOLVE call. The package resolves private
and public synonyms internally, so the manual synonym recursion is removed.

DBMS_UTILITY.NAME_RESOLVE is documented for Oracle 8i (released 1999),
so version support is not a concern for any software being written in
2026. 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

OUT-bind plumbing is added on both the OCI8 path (anonymous PL/SQL block
with named binds) and the JDBC path (CallableStatement + registerOutParameter)
so the POC can be exercised on both MRI and JRuby.

Two subtleties the spec suite surfaced:

  1. NAME_RESOLVE's context parameter matters. context=1 is PL/SQL objects
     only and raises ORA-04047 for tables / views; context=0 covers
     tables, views, and synonyms (verified empirically against Oracle 23ai).

  2. NAME_RESOLVE uppercases unquoted input, so case-preserving (quoted)
     identifiers like "test_Mixed_Comments" failed with ORA-06564. Each
     dotted part of the name is wrapped in double quotes when the
     original identifier was not upcase-normalized by valid_table_name?.

With those in place the full rspec suite is green on CRuby 4.0.2 and
JRuby 10.0.5.0 (423 examples, 0 failures, 6 pending on both).

The regression test and PUBLIC SYNONYM grants from PR rsim#2521 are included
as the acceptance bar.

Open questions this POC exists to answer:
- Readability: anonymous PL/SQL block vs. SQL against all_* dictionaries.
- Consistency: the rest of the adapter reads from all_* dictionaries;
  a PL/SQL call is a style break.

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

Author: yahonda

lib/active_record/connection_adapters/oracle_enhanced/connection.rb

@@ -19,51 +19,27 @@ def self.create(config)
         attr_reader :raw_connection
 
         private
-          # Used always by JDBC connection as well by OCI connection when describing tables over database link
+          # POC: resolve object name via DBMS_UTILITY.NAME_RESOLVE instead of
+          # querying all_tables / all_views / all_synonyms. NAME_RESOLVE follows
+          # private and public synonyms for us, so no manual recursion is needed.
+          # See https://github.com/rsim/oracle-enhanced/pull/2521#issuecomment-4242585736
           def describe(name)
             name = name.to_s
             if name.include?("@")
               raise ArgumentError "db link is not supported"
-            else
-              default_owner = @owner
-            end
-            real_name = OracleEnhanced::Quoting.valid_table_name?(name) ? name.upcase : name
-            if real_name.include?(".")
-              table_owner, table_name = real_name.split(".")
-            else
-              table_owner, table_name = default_owner, real_name
             end
-            sql = <<~SQL.squish
-              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
-            if result = _select_one(sql, "CONNECTION", [table_owner, table_name, table_owner, table_name, table_owner, table_name, real_name])
-              case result["name_type"]
-              when "SYNONYM"
-                describe("#{result['owner'] && "#{result['owner']}."}#{result['table_name']}")
-              else
-                [result["owner"], result["table_name"]]
-              end
+            if OracleEnhanced::Quoting.valid_table_name?(name)
+              _resolve_name(name.upcase)
             else
-              raise OracleEnhanced::ConnectionException, %Q{"DESC #{name}" failed; does it exist?}
+              # case-preserving (quoted) identifier: wrap each dotted part
+              # in double quotes so DBMS_UTILITY.NAME_RESOLVE doesn't
+              # uppercase it internally.
+              _resolve_name(name.split(".").map { |p| %("#{p}") }.join("."))
             end
+          rescue OracleEnhanced::ConnectionException
+            raise
+          rescue => e
+            raise OracleEnhanced::ConnectionException, %Q{"DESC #{name}" failed; does it exist? (#{e.message})}
           end
 
           # Oracle column names by default are case-insensitive, but treated as upcase;

lib/active_record/connection_adapters/oracle_enhanced/jdbc_connection.rb

@@ -322,6 +322,23 @@ def database_version
           @database_version ||= (md = raw_connection.getMetaData) && [md.getDatabaseMajorVersion, md.getDatabaseMinorVersion]
         end
 
+        # POC: call DBMS_UTILITY.NAME_RESOLVE via JDBC CallableStatement with
+        # registered OUT parameters. Returns [schema, object_name].
+        def _resolve_name(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 rescue nil
+        end
+
         class Cursor
           def initialize(connection, raw_statement, exec_sql = nil)
             @raw_connection = connection

lib/active_record/connection_adapters/oracle_enhanced/oci_connection.rb

@@ -101,6 +101,31 @@ def exec(sql, *bindvars, allow_retry: false, &block)
           with_retry(allow_retry: allow_retry) { @raw_connection.exec(sql, *bindvars, &block) }
         end
 
+        # POC: call DBMS_UTILITY.NAME_RESOLVE via anonymous PL/SQL block with
+        # OUT binds. Returns [schema, object_name]; synonyms are followed by
+        # the package itself.
+        def _resolve_name(name)
+          plsql = <<~SQL
+            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;
+          SQL
+          cursor = @raw_connection.parse(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 rescue nil
+        end
+
         def with_retry(allow_retry: false, &block)
           @raw_connection.with_retry(allow_retry: allow_retry, &block)
         end

spec/active_record/connection_adapters/oracle_enhanced/connection_spec.rb

@@ -599,6 +599,23 @@ def connection_id_from_server(conn)
       expect(@conn.describe("all_tables")).to eq(["SYS", "ALL_TABLES"])
     end
 
+    it "should describe table, view, private synonym and public synonym for the same underlying table" do
+      @conn.exec "CREATE TABLE test_describe_all (id NUMBER)" rescue nil
+      @conn.exec "CREATE VIEW test_describe_all_v AS SELECT * FROM test_describe_all" rescue nil
+      @conn.exec "CREATE SYNONYM test_describe_all_syn FOR test_describe_all" rescue nil
+      @conn.exec "CREATE PUBLIC SYNONYM test_describe_all_pub FOR #{@owner}.test_describe_all" rescue nil
+
+      expect(@conn.describe("test_describe_all")).to eq([@owner, "TEST_DESCRIBE_ALL"])
+      expect(@conn.describe("test_describe_all_v")).to eq([@owner, "TEST_DESCRIBE_ALL_V"])
+      expect(@conn.describe("test_describe_all_syn")).to eq([@owner, "TEST_DESCRIBE_ALL"])
+      expect(@conn.describe("test_describe_all_pub")).to eq([@owner, "TEST_DESCRIBE_ALL"])
+    ensure
+      @conn.exec "DROP PUBLIC SYNONYM test_describe_all_pub" rescue nil
+      @conn.exec "DROP SYNONYM test_describe_all_syn" rescue nil
+      @conn.exec "DROP VIEW test_describe_all_v" rescue nil
+      @conn.exec "DROP TABLE test_describe_all" rescue nil
+    end
+
     if defined?(OCI8)
       context "OCI8 adapter" do
         it "should not fallback to SELECT-based logic when querying non-existent table information" do

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;