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?`,
  not a strict database capability check.
- `: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.

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.
- `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
  `GET_DEPENDENT_DDL("TRIGGER", table_name)`.
- COMMENT ON TABLE / COMMENT ON COLUMN queried directly because
  `GET_DEPENDENT_DDL("COMMENT")` is unreliable.
- `structure_dump_db_stored_code` selects `'PROCEDURE', 'PACKAGE',
  'FUNCTION', 'TRIGGER', 'TYPE'` only — `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 (`CREATE TABLE` / `CREATE INDEX` / `ALTER TABLE … ADD
CONSTRAINT` / `COMMENT` / no `STORAGE` / `TABLESPACE` / `PCTFREE`)
rather than exact byte-level DDL. 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,283 @@
+# 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:
+        # DBMS_METADATA-backed implementation of `structure_dump`,
+        # `structure_dump_db_stored_code`, and `structure_dump_synonyms`.
+        # Selected by `OracleEnhancedAdapter.structure_dump_method`:
+        #
+        # * `:auto` (default) — `:dbms_metadata` on Oracle 12.1+, otherwise
+        #   `:data_dictionary`.
+        # * `:dbms_metadata` — force the new path; raises `ArgumentError`
+        #   on pre-12.1 servers (mirrors PR #2576's `identifier_max_length:
+        #   :long` policy).
+        # * `:data_dictionary` — delegate to `super` (the original `ALL_*`
+        #   implementation).
+        #
+        # Output shape is informed by mysqldump / pg_dump --schema-only:
+        # statements are reloadable on a fresh database, machine-specific
+        # noise (storage / tablespace / segment attributes / schema qualifiers)
+        # is suppressed, and statements are separated by the same
+        # `STATEMENT_TOKEN` the dictionary-views implementation uses so that
+        # `execute_structure_dump` can split and apply them.
+        module DbmsMetadata # :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
+
+            def dbms_metadata_structure_dump
+              configure_dbms_metadata_transforms
+              structure = []
+
+              sequence_names = select_values(<<~SQL.squish, "SCHEMA")
+                SELECT sequence_name FROM all_sequences
+                WHERE sequence_owner = SYS_CONTEXT('userenv', 'current_schema')
+                ORDER BY 1
+              SQL
+              sequence_names.each do |seq_name|
+                ddl = dbms_metadata_get_ddl("SEQUENCE", seq_name)
+                structure << ddl if ddl
+              end
+
+              tables = select_values(<<~SQL.squish, "SCHEMA")
+                SELECT table_name FROM all_tables t
+                WHERE owner = SYS_CONTEXT('userenv', 'current_schema') AND secondary = 'N'
+                AND NOT EXISTS (SELECT mv.mview_name FROM all_mviews mv
+                                WHERE mv.owner = t.owner AND mv.mview_name = t.table_name)
+                AND NOT EXISTS (SELECT mvl.log_table FROM all_mview_logs mvl
+                                WHERE mvl.log_owner = t.owner AND mvl.log_table = t.table_name)
+                ORDER BY 1
+              SQL
+              tables.each do |table_name|
+                ddl = dbms_metadata_get_ddl("TABLE", table_name)
+                structure << ddl if ddl
+
+                # `CONSTRAINTS=TRUE` already inlines PK/UNIQUE constraint DDL
+                # (and their backing indexes) into the table DDL, so emitting
+                # `GET_DDL("INDEX", ...)` for those would duplicate them.
+                constraint_index_names = constraint_backed_index_names(table_name)
+                indexes(table_name).each do |idx|
+                  next if constraint_index_names.include?(idx.name.upcase)
+                  idx_ddl = dbms_metadata_get_ddl("INDEX", idx.name.upcase)
+                  structure << idx_ddl if idx_ddl
+                end
+
+                # `primary_key_trigger:` (#2615) emits a row trigger named
+                # `<table>_pkt`; pick those up via GET_DEPENDENT_DDL('TRIGGER').
+                trg_ddl = dbms_metadata_get_dependent_ddl("TRIGGER", table_name)
+                structure.concat(split_dbms_metadata_ddl(trg_ddl)) if trg_ddl
+
+                structure.concat(dbms_metadata_structure_dump_table_comments(table_name))
+                structure.concat(dbms_metadata_structure_dump_column_comments(table_name))
+              end
+
+              fk_statements = []
+              tables.each do |table_name|
+                fk_ddl = dbms_metadata_get_dependent_ddl("REF_CONSTRAINT", table_name)
+                fk_statements.concat(split_dbms_metadata_ddl(fk_ddl)) if fk_ddl
+              end
+
+              view_names = select_values(<<~SQL.squish, "SCHEMA")
+                SELECT view_name FROM all_views
+                WHERE owner = SYS_CONTEXT('userenv', 'current_schema')
+                ORDER BY view_name ASC
+              SQL
+              view_names.each do |view_name|
+                ddl = dbms_metadata_get_ddl("VIEW", view_name)
+                structure << ddl if ddl
+              end
+
+              join_with_statement_token(structure) <<
+                join_with_statement_token(fk_statements)
+            ensure
+              reset_dbms_metadata_transforms
+            end
+
+            def dbms_metadata_structure_dump_db_stored_code
+              configure_dbms_metadata_transforms
+              structure = []
+
+              # `GET_DDL("PACKAGE", ...)` returns *both* the spec and body, and
+              # likewise for TYPE. Selecting 'PACKAGE BODY' / 'TYPE BODY' here
+              # would dump the body a second time.
+              all_source = select_all(<<~SQL.squish, "SCHEMA")
+                SELECT DISTINCT name, type
+                FROM all_source
+                WHERE type IN ('PROCEDURE', 'PACKAGE', 'FUNCTION', 'TRIGGER', 'TYPE')
+                AND name NOT LIKE 'BIN$%'
+                AND owner = SYS_CONTEXT('userenv', 'current_schema') ORDER BY type
+              SQL
+              all_source.each do |source|
+                ddl = dbms_metadata_get_ddl(source["type"], source["name"])
+                structure << ddl if ddl
+              end
+
+              structure << dbms_metadata_structure_dump_synonyms
+
+              join_with_statement_token(structure)
+            ensure
+              reset_dbms_metadata_transforms
+            end
+
+            def dbms_metadata_structure_dump_synonyms
+              configure_dbms_metadata_transforms
+              structure = []
+              synonym_names = select_values(<<~SQL.squish, "SCHEMA")
+                SELECT synonym_name FROM all_synonyms
+                WHERE owner = SYS_CONTEXT('userenv', 'current_schema')
+              SQL
+              synonym_names.each do |synonym_name|
+                ddl = dbms_metadata_get_ddl("SYNONYM", synonym_name)
+                structure << ddl if ddl
+              end
+              join_with_statement_token(structure)
+            ensure
+              reset_dbms_metadata_transforms
+            end
+
+            def constraint_backed_index_names(table_name)
+              select_values(<<~SQL.squish, "SCHEMA", [bind_string("table_name", table_name)])
+                SELECT index_name FROM all_constraints
+                WHERE owner = SYS_CONTEXT('userenv', 'current_schema')
+                AND table_name = :table_name
+                AND constraint_type IN ('P', 'U')
+                AND index_name IS NOT NULL
+              SQL
+            end
+
+            # COMMENT ON is not reliably available via
+            # DBMS_METADATA.GET_DEPENDENT_DDL('COMMENT'), so 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`.
+            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)
+              result = select_value(
+                "SELECT DBMS_METADATA.GET_DDL(#{quote(object_type)}, #{quote(object_name)}) FROM DUAL",
+                "SCHEMA"
+              )
+              clean_dbms_metadata_ddl(result)
+            rescue ActiveRecord::StatementInvalid => e
+              # ORA-31603: object not found — e.g., constraint-backing index names
+              # returned by `indexes()` that DBMS_METADATA classifies as
+              # CONSTRAINT, not INDEX. The constraint DDL is already inlined in
+              # the parent TABLE GET_DDL output, so silently skipping is correct.
+              raise unless e.message.include?("ORA-31603")
+              nil
+            end
+
+            def dbms_metadata_get_dependent_ddl(dependent_type, base_object_name)
+              result = select_value(
+                "SELECT DBMS_METADATA.GET_DEPENDENT_DDL(#{quote(dependent_type)}, #{quote(base_object_name)}) FROM DUAL",
+                "SCHEMA"
+              )
+              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
+
+        prepend DbmsMetadata
+      end
+    end
+  end
+end

lib/active_record/connection_adapters/oracle_enhanced_adapter.rb

@@ -49,6 +49,7 @@
 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/lob"
 
 require "active_record/type/oracle_enhanced/raw"
@@ -357,6 +358,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 +518,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.