Add DBMS_METADATA structure_dump backend, selectable via cattr toggle

Closes rsim#2513.

Adds a second `structure_dump` implementation built on Oracle's
`DBMS_METADATA.GET_DDL` / `GET_DEPENDENT_DDL` alongside the existing
data-dictionary (`ALL_*`) one. The new backend lives in a separate
file and installs via `prepend DbmsMetadata`, so the legacy path in
`structure_dump.rb` is untouched.

Selectable globally via `OracleEnhancedAdapter.structure_dump_method`:

- `:auto` (default) — `:dbms_metadata` on Oracle 12.1+,
  `:data_dictionary` otherwise. The 12.1 floor is a project-policy
  version gate (the IDENTITY / EDITIONABLE / modern
  SET_TRANSFORM_PARAM era), exposed as `use_dbms_metadata_dump?`.
- `:dbms_metadata` — force the new path; raises `ArgumentError` on
  pre-12.1 (mirrors PR rsim#2576's `identifier_max_length: :long`
  fail-fast policy).
- `:data_dictionary` — force the original implementation. Remains
  explicitly selectable on 12.1+ as well.

Implementation walks `ALL_OBJECTS` per object_type rather than
hand-rolling per-kind queries; this naturally picks up
MATERIALIZED VIEW / TYPE / TRIGGER / SYNONYM / etc. without separate
code paths. FK constraints (REF_CONSTRAINT) are emitted in a single
trailing block; cross-table dependency order is left to the user (or
to a fresh-schema reload) rather than tracked here.

Output is informed by `mysqldump --no-data` / `pg_dump --schema-only`:

- `STORAGE` / `TABLESPACE` / `SEGMENT_ATTRIBUTES` / `EMIT_SCHEMA`
  suppressed via `DBMS_METADATA.SET_TRANSFORM_PARAM` so the dump is
  portable across installations and schemas. Oracle honors these for
  TABLE / INDEX / SEQUENCE.
- `MATERIALIZED VIEW` DDL is an exception: Oracle does not honour the
  same suppression on MV (object_type-specific override does not work
  either), so MV DDL retains physical attributes (PCTFREE, TABLESPACE,
  SEGMENT CREATION, etc.) as Oracle emits them. Since MVs aren't
  creatable through Rails' standard migration helpers anyway, no
  post-processing pass is added — Oracle's output is used as-is.
- `REF_CONSTRAINTS` emitted as separate `ALTER TABLE … ADD
  CONSTRAINT` statements after all tables.
- Inline constraints via Oracle's `CONSTRAINTS=TRUE` default; UNIQUE
  backing indexes that DBMS_METADATA already inlines into the table
  DDL are filtered out so they aren't emitted twice.
- `STATEMENT_TOKEN` separation preserved (Oracle's `SQLTERMINATOR=FALSE`
  default) so `execute_structure_dump` splits as before.
- `primary_key_trigger:` (rsim#2615) row triggers picked up via the
  TRIGGER object_type pass.
- COMMENT ON TABLE / COMMENT ON COLUMN queried directly because
  `GET_DEPENDENT_DDL("COMMENT")` is unreliable.
- `structure_dump_db_stored_code` selects 'PROCEDURE', 'PACKAGE',
  'FUNCTION', 'TYPE' — `GET_DDL("PACKAGE", ...)` already returns
  spec + body, so selecting 'PACKAGE BODY' would emit the body twice.

Specs follow the `pg_dump` / `mysqldump` testing convention: assert
output shape rather than exact byte-level DDL. A schema-option spec
verifies that `:schema` connection-time switching is honored
(structure_dump walks `SYS_CONTEXT('userenv', 'current_schema')`,
not the connecting user). The existing `structure_dump_spec` pins
`:data_dictionary` in `before(:all)` so its exact-DDL assertions
still apply to the legacy backend.

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

Author: yahonda

lib/active_record/connection_adapters/oracle_enhanced/structure_dump/dbms_metadata.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "active_record/connection_adapters/oracle_enhanced/structure_dump"
+
+module ActiveRecord # :nodoc:
+  module ConnectionAdapters # :nodoc:
+    module OracleEnhanced # :nodoc:
+      module StructureDump # :nodoc:
+        module DbmsMetadata # :nodoc:
+          STRUCTURE_OBJECT_TYPES = [
+            "SEQUENCE",
+            "TABLE",
+            "INDEX",
+            "VIEW",
+            "MATERIALIZED VIEW",
+            "TRIGGER"
+          ].freeze
+
+          STORED_CODE_OBJECT_TYPES = [
+            "FUNCTION",
+            "PROCEDURE",
+            "PACKAGE",
+            "TYPE"
+          ].freeze
+
+          private_constant :STRUCTURE_OBJECT_TYPES, :STORED_CODE_OBJECT_TYPES
+
+          private
+            def dbms_metadata_structure_dump
+              dbms_metadata_with_transforms do
+                structure = []
+                table_names = list_schema_objects("TABLE", non_mview_only: true)
+                skip_indexes = constraint_backed_index_names
+
+                STRUCTURE_OBJECT_TYPES.each do |object_type|
+                  names = if object_type == "TABLE"
+                    table_names
+                  else
+                    list_schema_objects(object_type)
+                  end
+                  names.each do |name|
+                    next if object_type == "INDEX" && skip_indexes.include?(name.upcase)
+                    ddl = dbms_metadata_get_ddl(object_type.tr(" ", "_"), name)
+                    structure << ddl if ddl
+                  end
+                end
+
+                table_names.each do |table_name|
+                  structure.concat(dbms_metadata_structure_dump_table_comments(table_name))
+                  structure.concat(dbms_metadata_structure_dump_column_comments(table_name))
+                end
+
+                fk_statements = table_names.flat_map do |table_name|
+                  fk_ddl = dbms_metadata_get_dependent_ddl("REF_CONSTRAINT", table_name)
+                  fk_ddl ? split_dbms_metadata_ddl(fk_ddl) : []
+                end
+
+                join_with_statement_token(structure) << join_with_statement_token(fk_statements)
+              end
+            end
+
+            def dbms_metadata_structure_dump_db_stored_code
+              dbms_metadata_with_transforms do
+                structure = STORED_CODE_OBJECT_TYPES.flat_map do |object_type|
+                  list_schema_objects(object_type).filter_map do |name|
+                    dbms_metadata_get_ddl(object_type, name)
+                  end
+                end
+                structure << dbms_metadata_structure_dump_synonyms
+                join_with_statement_token(structure)
+              end
+            end
+
+            def dbms_metadata_structure_dump_synonyms
+              dbms_metadata_with_transforms do
+                structure = list_schema_objects("SYNONYM").filter_map do |synonym_name|
+                  dbms_metadata_get_ddl("SYNONYM", synonym_name)
+                end
+                join_with_statement_token(structure)
+              end
+            end
+
+            def dbms_metadata_with_transforms
+              configure_dbms_metadata_transforms
+              yield
+            ensure
+              reset_dbms_metadata_transforms
+            end
+
+            def list_schema_objects(object_type, non_mview_only: false)
+              binds = [bind_string("object_type", object_type)]
+              # MV / MV log surface as TABLE in all_objects.
+              mview_filter = if non_mview_only
+                <<~SQL.squish
+                  AND NOT EXISTS (SELECT 1 FROM all_mviews mv
+                                  WHERE mv.owner = o.owner AND mv.mview_name = o.object_name)
+                  AND NOT EXISTS (SELECT 1 FROM all_mview_logs mvl
+                                  WHERE mvl.log_owner = o.owner AND mvl.log_table = o.object_name)
+                SQL
+              else
+                ""
+              end
+              select_values(<<~SQL.squish, "SCHEMA", binds)
+                SELECT object_name FROM all_objects o
+                WHERE owner = SYS_CONTEXT('userenv', 'current_schema')
+                AND object_type = :object_type
+                AND object_name NOT LIKE 'BIN$%'
+                #{mview_filter}
+                ORDER BY object_name
+              SQL
+            end
+
+            # PRIMARY KEY / UNIQUE constraint backing indexes are already inlined by CONSTRAINTS=TRUE.
+            def constraint_backed_index_names
+              select_values(<<~SQL.squish, "SCHEMA").map(&:upcase).to_set
+                SELECT index_name FROM all_constraints
+                WHERE owner = SYS_CONTEXT('userenv', 'current_schema')
+                AND constraint_type IN ('P', 'U')
+                AND index_name IS NOT NULL
+              SQL
+            end
+
+            # GET_DEPENDENT_DDL("COMMENT", ...) returns an empty CLOB; query directly.
+            def dbms_metadata_structure_dump_table_comments(table_name)
+              comment = table_comment(table_name)
+              return [] if comment.nil?
+              ["COMMENT ON TABLE #{quote_table_name(table_name)} IS '#{quote_string(comment)}'"]
+            end
+
+            def dbms_metadata_structure_dump_column_comments(table_name)
+              comments = []
+              columns = select_values(<<~SQL.squish, "SCHEMA", [bind_string("table_name", table_name)])
+                SELECT column_name FROM all_tab_columns
+                WHERE owner = SYS_CONTEXT('userenv', 'current_schema')
+                AND table_name = :table_name ORDER BY column_id
+              SQL
+              columns.each do |column|
+                comment = column_comment(table_name, column)
+                unless comment.nil?
+                  comments << "COMMENT ON COLUMN #{quote_table_name(table_name)}.#{quote_column_name(column)} IS '#{quote_string(comment)}'"
+                end
+              end
+              comments
+            end
+
+            # Suppress installation-specific output, in spirit of
+            # `pg_dump --schema-only --no-owner --no-tablespaces`. Oracle
+            # honors these for TABLE / INDEX / SEQUENCE; MATERIALIZED VIEW
+            # ignores them and emits its own physical attributes regardless.
+            def configure_dbms_metadata_transforms
+              execute(<<~SQL)
+                BEGIN
+                  DBMS_METADATA.SET_TRANSFORM_PARAM(DBMS_METADATA.SESSION_TRANSFORM, 'STORAGE', FALSE);
+                  DBMS_METADATA.SET_TRANSFORM_PARAM(DBMS_METADATA.SESSION_TRANSFORM, 'TABLESPACE', FALSE);
+                  DBMS_METADATA.SET_TRANSFORM_PARAM(DBMS_METADATA.SESSION_TRANSFORM, 'SEGMENT_ATTRIBUTES', FALSE);
+                  DBMS_METADATA.SET_TRANSFORM_PARAM(DBMS_METADATA.SESSION_TRANSFORM, 'EMIT_SCHEMA', FALSE);
+                  DBMS_METADATA.SET_TRANSFORM_PARAM(DBMS_METADATA.SESSION_TRANSFORM, 'REF_CONSTRAINTS', FALSE);
+                END;
+              SQL
+            end
+
+            def reset_dbms_metadata_transforms
+              execute(<<~SQL)
+                BEGIN
+                  DBMS_METADATA.SET_TRANSFORM_PARAM(DBMS_METADATA.SESSION_TRANSFORM, 'DEFAULT');
+                END;
+              SQL
+            end
+
+            def dbms_metadata_get_ddl(object_type, object_name)
+              binds = [
+                bind_string("object_type", object_type),
+                bind_string("object_name", object_name)
+              ]
+              result = select_value(
+                "SELECT DBMS_METADATA.GET_DDL(:object_type, :object_name) FROM DUAL",
+                "SCHEMA",
+                binds
+              )
+              clean_dbms_metadata_ddl(result)
+            rescue ActiveRecord::StatementInvalid => e
+              # ORA-31603: object not found (race vs another session dropping
+              # the object between the ALL_OBJECTS scan and GET_DDL).
+              raise unless e.message.include?("ORA-31603")
+              nil
+            end
+
+            def dbms_metadata_get_dependent_ddl(dependent_type, base_object_name)
+              binds = [
+                bind_string("dependent_type", dependent_type),
+                bind_string("base_object_name", base_object_name)
+              ]
+              result = select_value(
+                "SELECT DBMS_METADATA.GET_DEPENDENT_DDL(:dependent_type, :base_object_name) FROM DUAL",
+                "SCHEMA",
+                binds
+              )
+              clean_dbms_metadata_ddl(result)
+            rescue ActiveRecord::StatementInvalid => e
+              # ORA-31608: dependent object not found (e.g. no triggers / no FKs).
+              raise unless e.message.include?("ORA-31608")
+              nil
+            end
+
+            def clean_dbms_metadata_ddl(ddl)
+              return nil if ddl.nil?
+              result = ddl.to_s.strip
+              result.empty? ? nil : result
+            end
+
+            # GET_DEPENDENT_DDL can return multiple DDL statements concatenated
+            # in a single CLOB. Split on blank-line boundaries.
+            def split_dbms_metadata_ddl(ddl)
+              return [] if ddl.nil?
+              ddl.split(/\n\s*\n/).map(&:strip).reject(&:empty?)
+            end
+        end
+      end
+    end
+  end
+end

lib/active_record/connection_adapters/oracle_enhanced/structure_dump/dispatcher.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "active_record/connection_adapters/oracle_enhanced/structure_dump"
+require "active_record/connection_adapters/oracle_enhanced/structure_dump/dbms_metadata"
+
+module ActiveRecord # :nodoc:
+  module ConnectionAdapters # :nodoc:
+    module OracleEnhanced # :nodoc:
+      module StructureDump # :nodoc:
+        # `OracleEnhancedAdapter.structure_dump_method` accepts:
+        #
+        # * `:auto` (default) — DBMS_METADATA on Oracle 12.1+, otherwise
+        #   data-dictionary.
+        # * `:dbms_metadata` — force DBMS_METADATA; raises `ArgumentError`
+        #   on pre-12.1 (mirrors PR #2576's `identifier_max_length: :long`
+        #   policy).
+        # * `:data_dictionary` — force the implementation that assembles
+        #   DDL from the ALL_* static data dictionary views in Ruby.
+        module Dispatcher # :nodoc:
+          def structure_dump
+            case resolved_structure_dump_method
+            when :dbms_metadata then dbms_metadata_structure_dump
+            when :data_dictionary then super
+            end
+          end
+
+          def structure_dump_db_stored_code
+            case resolved_structure_dump_method
+            when :dbms_metadata then dbms_metadata_structure_dump_db_stored_code
+            when :data_dictionary then super
+            end
+          end
+
+          def structure_dump_synonyms
+            case resolved_structure_dump_method
+            when :dbms_metadata then dbms_metadata_structure_dump_synonyms
+            when :data_dictionary then super
+            end
+          end
+
+          private
+            def resolved_structure_dump_method
+              case OracleEnhancedAdapter.structure_dump_method
+              when :auto
+                use_dbms_metadata_dump? ? :dbms_metadata : :data_dictionary
+              when :dbms_metadata
+                unless use_dbms_metadata_dump?
+                  raise ArgumentError,
+                    "structure_dump_method: :dbms_metadata requires Oracle 12.1 or later " \
+                    "(connected server reports #{database_version}). " \
+                    "Use :auto to fall back to :data_dictionary on older releases."
+                end
+                :dbms_metadata
+              when :data_dictionary
+                :data_dictionary
+              else
+                raise ArgumentError,
+                  "Unknown structure_dump_method " \
+                  "#{OracleEnhancedAdapter.structure_dump_method.inspect}; " \
+                  "expected :auto, :dbms_metadata, or :data_dictionary."
+              end
+            end
+        end
+
+        include DbmsMetadata
+        prepend Dispatcher
+      end
+    end
+  end
+end

lib/active_record/connection_adapters/oracle_enhanced_adapter.rb

@@ -49,6 +49,8 @@
 require "active_record/connection_adapters/oracle_enhanced/dbms_output"
 require "active_record/connection_adapters/oracle_enhanced/type_metadata"
 require "active_record/connection_adapters/oracle_enhanced/structure_dump"
+require "active_record/connection_adapters/oracle_enhanced/structure_dump/dbms_metadata"
+require "active_record/connection_adapters/oracle_enhanced/structure_dump/dispatcher"
 require "active_record/connection_adapters/oracle_enhanced/lob"
 
 require "active_record/type/oracle_enhanced/raw"
@@ -357,6 +359,43 @@ def use_shorter_identifier=(value)
       cattr_accessor :permissions
       self.permissions = ["unlimited tablespace", "create session", "create table", "create view", "create sequence"]
 
+      ##
+      # :singleton-method:
+      # Selects which `structure_dump` backend the adapter uses. Accepts:
+      #
+      # * +:auto+ (default) — pick +:dbms_metadata+ on Oracle 12.1 and later,
+      #   fall back to +:data_dictionary+ on earlier releases. The
+      #   +:dbms_metadata+ path relies on constructs Oracle only emits
+      #   completely from 12.1 onward (notably +IDENTITY+ columns and
+      #   +EDITIONABLE+ keywords); +:auto+ keeps the new backend opt-in by
+      #   capability, not by user action.
+      # * +:dbms_metadata+ — force Oracle's
+      #   <tt>DBMS_METADATA.GET_DDL</tt> / <tt>GET_DEPENDENT_DDL</tt>. The
+      #   Oracle-native equivalent of <tt>pg_dump --schema-only</tt> /
+      #   <tt>mysqldump --no-data</tt>. Raises +ArgumentError+ at dump time
+      #   when the connected server is older than 12.1.
+      # * +:data_dictionary+ — force the original implementation that
+      #   assembles DDL from the <tt>ALL_*</tt> static data dictionary views
+      #   in Ruby. Retained as a fallback while the +:dbms_metadata+ backend
+      #   stabilises; may be removed in a future release. If
+      #   <tt>DBMS_METADATA</tt> does not produce usable DDL for your schema,
+      #   please open an issue at https://github.com/rsim/oracle-enhanced/issues
+      #   so the new backend can be fixed before the +:data_dictionary+ one
+      #   is removed.
+      #
+      # Set globally (e.g. in <tt>config/initializers/oracle_enhanced.rb</tt>):
+      #
+      #   ActiveRecord::ConnectionAdapters::OracleEnhancedAdapter.structure_dump_method = :data_dictionary
+      #
+      # The toggle is intentionally a Rails-app-global setting rather than a
+      # per-connection +database.yml+ key — the choice of structure-dump
+      # backend is an implementation strategy, not something that varies
+      # across the databases an app connects to.
+      STRUCTURE_DUMP_METHODS = %i[auto dbms_metadata data_dictionary].freeze
+
+      cattr_accessor :structure_dump_method
+      self.structure_dump_method = :auto
+
       ##
       # :singleton-method:
       # Specify default sequence start with value (by default 1 if not explicitly set), e.g.:
@@ -480,6 +519,18 @@ def supports_identity_columns? # :nodoc:
         database_version >= "12"
       end
 
+      # Whether `structure_dump_method: :auto` resolves to +:dbms_metadata+
+      # on this connection. `DBMS_METADATA.GET_DDL` itself exists since
+      # Oracle 9i, but the constructs the backend depends on (`IDENTITY`
+      # columns, `EDITIONABLE` keywords, the modern set of
+      # `SET_TRANSFORM_PARAM` options) only land in Oracle 12.1, so older
+      # releases fall back to +:data_dictionary+ under +:auto+. The 12.1
+      # floor is a project policy choice, not a strict database capability
+      # check; +:data_dictionary+ remains explicitly selectable on 12.1+.
+      def use_dbms_metadata_dump? # :nodoc:
+        database_version >= "12.1"
+      end
+
       def supports_json?
         # Oracle Database 12.1 or higher version supports JSON.
         # However, Oracle enhanced adapter has limited support for JSON data type.