Merge branch '338535-loose-fk-definition' into 'master'

Add AR concern for defining loose foreign keys

See merge request gitlab-org/gitlab!69060

app/models/concerns/loose_foreign_key.rb

+# frozen_string_literal: true
+
+module LooseForeignKey
+  extend ActiveSupport::Concern
+
+  # This concern adds loose foreign key support to ActiveRecord models.
+  # Loose foreign keys allow delayed processing of associated database records
+  # with similar guarantees than a database foreign key.
+  #
+  # TODO: finalize this later once the async job is in place
+  #
+  # Prerequisites:
+  #
+  # To start using the concern, you'll need to install a database trigger to the parent
+  # table in a standard DB migration (not post-migration).
+  #
+  # > add_loose_foreign_key_support(:projects, :gitlab_main)
+  #
+  # Usage:
+  #
+  # > class Ci::Build < ApplicationRecord
+  # >
+  # >   loose_foreign_key :security_scans, :build_id, on_delete: :async_delete, gitlab_schema: :gitlab_main
+  # >
+  # >   # associations can be still defined, the dependent options is no longer necessary:
+  # >   has_many :security_scans, class_name: 'Security::Scan'
+  # >
+  # > end
+  #
+  # Options for on_delete:
+  #
+  # - :async_delete - deletes the children rows via an asynchronous process.
+  # - :async_nullify - sets the foreign key column to null via an asynchronous process.
+  #
+  # Options for gitlab_schema:
+  #
+  # - :gitlab_ci
+  # - :gitlab_main
+  #
+  # The value can be determined by calling `Model.gitlab_schema` where the Model represents
+  # the model for the child table.
+  #
+  # How it works:
+  #
+  # When adding loose foreign key support to the table, a DELETE trigger is installed
+  # which tracks the record deletions (stores primary key value of the deleted row) in
+  # a database table.
+  #
+  # These deletion records are processed asynchronously and records are cleaned up
+  # according to the loose foreign key definitions described in the model.
+  #
+  # The cleanup happens in batches, which reduces the likelyhood of statement timeouts.
+  #
+  # When all associations related to the deleted record are cleaned up, the record itself
+  # is deleted.
+  included do
+    class_attribute :loose_foreign_key_definitions, default: []
+  end
+
+  class_methods do
+    def loose_foreign_key(to_table, column, options)
+      symbolized_options = options.symbolize_keys
+
+      unless base_class?
+        raise <<~MSG
+        loose_foreign_key can be only used on base classes, inherited classes are not supported.
+        Please define the loose_foreign_key on the #{base_class.name} class.
+        MSG
+      end
+
+      on_delete_options = %i[async_delete async_nullify]
+      gitlab_schema_options = [ApplicationRecord.gitlab_schema, Ci::ApplicationRecord.gitlab_schema]
+
+      unless on_delete_options.include?(symbolized_options[:on_delete]&.to_sym)
+        raise "Invalid on_delete option given: #{symbolized_options[:on_delete]}. Valid options: #{on_delete_options.join(', ')}"
+      end
+
+      unless gitlab_schema_options.include?(symbolized_options[:gitlab_schema]&.to_sym)
+        raise "Invalid gitlab_schema option given: #{symbolized_options[:gitlab_schema]}. Valid options: #{gitlab_schema_options.join(', ')}"
+      end
+
+      definition = ActiveRecord::ConnectionAdapters::ForeignKeyDefinition.new(
+        table_name.to_s,
+        to_table.to_s,
+        {
+          column: column.to_s,
+          on_delete: symbolized_options[:on_delete].to_sym,
+          gitlab_schema: symbolized_options[:gitlab_schema].to_sym
+        }
+      )
+
+      self.loose_foreign_key_definitions += [definition]
+    end
+  end
+end

spec/models/concerns/loose_foreign_key_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe LooseForeignKey do
+  let(:project_klass) do
+    Class.new(ApplicationRecord) do
+      include LooseForeignKey
+
+      self.table_name = 'projects'
+
+      loose_foreign_key :issues, :project_id, on_delete: :async_delete, gitlab_schema: :gitlab_main
+      loose_foreign_key 'merge_requests', 'project_id', 'on_delete' => 'async_nullify', 'gitlab_schema' => :gitlab_main
+    end
+  end
+
+  it 'exposes the loose foreign key definitions' do
+    definitions = project_klass.loose_foreign_key_definitions
+
+    tables = definitions.map(&:to_table)
+    expect(tables).to eq(%w[issues merge_requests])
+  end
+
+  it 'casts strings to symbol' do
+    definition = project_klass.loose_foreign_key_definitions.last
+
+    expect(definition.from_table).to eq('projects')
+    expect(definition.to_table).to eq('merge_requests')
+    expect(definition.column).to eq('project_id')
+    expect(definition.on_delete).to eq(:async_nullify)
+    expect(definition.options[:gitlab_schema]).to eq(:gitlab_main)
+  end
+
+  context 'validation' do
+    context 'on_delete validation' do
+      let(:invalid_class) do
+        Class.new(ApplicationRecord) do
+          include LooseForeignKey
+
+          self.table_name = 'projects'
+
+          loose_foreign_key :issues, :project_id, on_delete: :async_delete, gitlab_schema: :gitlab_main
+          loose_foreign_key :merge_requests, :project_id, on_delete: :async_nullify, gitlab_schema: :gitlab_main
+          loose_foreign_key :merge_requests, :project_id, on_delete: :destroy, gitlab_schema: :gitlab_main
+        end
+      end
+
+      it 'raises error when invalid `on_delete` option was given' do
+        expect { invalid_class }.to raise_error /Invalid on_delete option given: destroy/
+      end
+    end
+
+    context 'gitlab_schema validation' do
+      let(:invalid_class) do
+        Class.new(ApplicationRecord) do
+          include LooseForeignKey
+
+          self.table_name = 'projects'
+
+          loose_foreign_key :merge_requests, :project_id, on_delete: :async_nullify, gitlab_schema: :unknown
+        end
+      end
+
+      it 'raises error when invalid `gitlab_schema` option was given' do
+        expect { invalid_class }.to raise_error /Invalid gitlab_schema option given: unknown/
+      end
+    end
+
+    context 'inheritance validation' do
+      let(:inherited_project_class) do
+        Class.new(Project) do
+          include LooseForeignKey
+
+          loose_foreign_key :issues, :project_id, on_delete: :async_delete, gitlab_schema: :gitlab_main
+        end
+      end
+
+      it 'raises error when loose_foreign_key is defined in a child ActiveRecord model' do
+        expect { inherited_project_class }.to raise_error /Please define the loose_foreign_key on the Project class/
+      end
+    end
+  end
+end