dekiru-data_migration 0.2.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2aedd5e4be5d28fb840f19ea8599d4398345b4ae861410719d550aa4342a55b
-  data.tar.gz: a36038e89f49f415b58556f190a1199882b58628df39671f6ca56dfc5ed57885
+  metadata.gz: 342d506a7d85aa5b54c2023c5bdd2f13d7ccc968e562bde836571461e67541c8
+  data.tar.gz: a30d3c9877ac51fac63dd7a0d69333750e453cd5020ae398b1361428d1185a68
 SHA512:
-  metadata.gz: d116ce6bb08682d5d23c3942b06e8f27dc898a4593d6520efb89c0d5dfa319ad317dec6adc2ef8816dd60fb39ce7f5f058762e0e48cdfc3e716601b3f54e039f
-  data.tar.gz: 5c6d29334eb32a2debd4d44e2c445431a5d6632de181a8cc05403dcb613264e66d1bef53755d3cfaaa1486d0d16c5bb8d5cb049250e97046229e5b269c43ea6d
+  metadata.gz: 19478e294f25f04c5757bd1118f9786bd285b1fbb802a9f91aed81db88fb37503c03ef954c30c6e3d1a7c4476c32a6378c499092a68f786ff5dfb17a4903f2d8
+  data.tar.gz: bc354a7e66c1960dde53c49ded487dd4ad4a8b9d6cd0e1852f82c8b94f20bdb08f6565329ee751de9622cefd984fa9f3a7771b9feeb71d945e9aa144874d0049

data/README.md

@@ -50,6 +50,60 @@ Dekiru::DataMigration::Operator.execute('Grant admin privileges to users') do
 end
 ```
 
+## Data Migration Class (Recommended)
+
+You can also define migration logic as a class, which makes testing easier:
+
+```ruby
+# scripts/20230118_demo_migration.rb
+class DemoMigration < Dekiru::DataMigration::Migration
+  def migration_targets
+    User.where("email LIKE '%sonicgarden%'").where(admin: false)
+  end
+
+  def migrate_record(user)
+    user.update!(admin: true)
+  end
+
+  def migrate
+    super
+    log "Updated user count: #{User.where(admin: true).count}"
+  end
+end
+
+DemoMigration.run
+```
+
+### Testing Migration Classes
+
+The class-based approach makes it easy to write unit tests:
+
+```ruby
+# spec/migrations/demo_migration_spec.rb
+RSpec.describe DemoMigration do
+  let(:migration) { described_class.new }
+
+  describe '#migration_targets' do
+    it 'returns correct migration targets' do
+      create_list(:user, 3, email: 'test@sonicgarden.jp', admin: false)
+      create_list(:user, 2, email: 'other@example.com', admin: false)
+
+      targets = migration.migration_targets
+      expect(targets.count).to eq(3)
+      expect(targets.all? { |u| u.email.include?('sonicgarden') }).to be true
+    end
+  end
+
+  describe '#migrate_record' do
+    it 'updates user to admin' do
+      user = create(:user, admin: false)
+      expect { migration.migrate_record(user) }
+        .to change { user.reload.admin }.from(false).to(true)
+    end
+  end
+end
+```
+
 Execution result:
 ```
 $ bin/rails r scripts/demo.rb
@@ -98,7 +152,7 @@ Are you sure to commit? (yes/no) > yes
 
 ## Generating Maintenance Scripts
 
-You can generate maintenance scripts that use `Dekiru::DataMigration::Operator` with the generator. The filename will be prefixed with the execution date.
+You can generate maintenance scripts that use `Dekiru::DataMigration::Migration` with the generator. The filename will be prefixed with the execution date.
 
 ```bash
 $ bin/rails g maintenance_script demo_migration
@@ -109,6 +163,29 @@ Generated file example:
 # scripts/20230118_demo_migration.rb
 # frozen_string_literal: true
 
+class DemoMigration < Dekiru::DataMigration::Migration
+  def migration_targets
+    # 移行対象を返すActiveRecord::Relationを定義
+    # 例: User.where(some_condition: true)
+    raise NotImplementedError, 'migration_targets method must be implemented'
+  end
+
+  def migrate_record(record)
+    # 個別レコードの更新処理を定義
+    # 例: record.update!(some_attribute: new_value)
+    raise NotImplementedError, 'migrate_record method must be implemented'
+  end
+end
+
+DemoMigration.run
+```
+
+### Legacy Block-based Approach
+
+For backward compatibility, you can still use the block-based approach:
+
+```ruby
+# scripts/legacy_demo.rb
 Dekiru::DataMigration::Operator.execute('demo_migration') do
   # write here
 end
@@ -213,3 +290,21 @@ Executes `find_each` with a progress bar for ActiveRecord scopes.
 
 ### `each_with_progress(enum, options = {}, &block)`
 Executes processing with a progress bar for any Enumerable objects.
+
+## Agent Skills
+
+This repository provides an agent skill for creating data migration scripts.
+
+### Available Skills
+
+#### `data-migration-script`
+
+Automatically creates data migration and deletion scripts using the `dekiru-data_migration` gem.
+
+**Triggers**: The agent will use this skill when you ask to "create a data migration script", "create a script to delete unnecessary records", or similar requests involving DB operations via scripts (bulk updates, deleting orphaned records, deleting ActiveStorage files, etc.).
+
+**Install**:
+
+```bash
+gh skill install SonicGarden/dekiru-data_migration
+```

data/lib/dekiru/data_migration/migration.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Dekiru
+  module DataMigration
+    # Base class for data migration with testable method separation
+    class Migration
+      def self.run(options = {})
+        migration = new
+        title = migration.title
+
+        Operator.execute(title, options) do
+          migration.instance_variable_set(:@operator_context, self)
+          migration.migrate
+        end
+      end
+
+      def title
+        self.class.name.demodulize.underscore.humanize
+      end
+
+      def migrate
+        targets = migration_targets
+
+        log "Target count: #{targets.count}"
+        confirm?
+
+        find_each_with_progress(targets) do |record|
+          migrate_record(record)
+        end
+
+        log "Migration completed"
+      end
+
+      def migration_targets
+        raise NotImplementedError, "#{self.class}#migration_targets must be implemented"
+      end
+
+      def migrate_record(record)
+        raise NotImplementedError, "#{self.class}#migrate_record must be implemented"
+      end
+
+      private
+
+      def confirm?
+        if @operator_context
+          @operator_context.send(:confirm?)
+        else
+          # Default behavior during test (no confirmation)
+          puts "Confirmation skipped in test mode"
+        end
+      end
+
+      def log(message)
+        if @operator_context
+          @operator_context.send(:log, message)
+        else
+          # Default behavior during test
+          puts message
+        end
+      end
+
+      def find_each_with_progress(scope, options = {}, &block)
+        if @operator_context
+          @operator_context.send(:find_each_with_progress, scope, options, &block)
+        else
+          # Default behavior during test (no progress bar)
+          scope.find_each(&block)
+        end
+      end
+
+      def each_with_progress(enum, options = {}, &block)
+        if @operator_context
+          @operator_context.send(:each_with_progress, enum, options, &block)
+        else
+          # Default behavior during test (no progress bar)
+          enum.each(&block)
+        end
+      end
+    end
+  end
+end

data/lib/dekiru/data_migration/version.rb

@@ -2,6 +2,6 @@
 
 module Dekiru
   module DataMigration
-    VERSION = "0.2.0"
+    VERSION = "1.1.0"
   end
 end

data/lib/dekiru/data_migration.rb

@@ -2,6 +2,7 @@
 
 require_relative "data_migration/version"
 require_relative "data_migration/transaction_provider"
+require_relative "data_migration/migration"
 require_relative "data_migration_operator"
 
 module Dekiru

data/lib/generators/maintenance_script/maintenance_script_generator.rb

@@ -14,8 +14,11 @@ class MaintenanceScriptGenerator < Rails::Generators::NamedBase
   source_root File.expand_path("templates", __dir__)
 
   def copy_maintenance_script_file
+    @filename_date = filename_date
+    @class_name = "#{name.classify}#{@filename_date}"
+
     template "maintenance_script.rb.erb",
-             "#{Dekiru::DataMigration.configuration.maintenance_script_directory}/#{filename_date}_#{file_name}.rb"
+             "#{Dekiru::DataMigration.configuration.maintenance_script_directory}/#{@filename_date}_#{file_name}.rb"
   end
 
   private

data/lib/generators/maintenance_script/templates/maintenance_script.rb.erb

@@ -2,6 +2,20 @@
 
 using Dekiru::DataMigration::DangerousMethodGuard
 
-Dekiru::DataMigration::Operator.execute('<%= @name %>') do
-  # write here
+class <%= @class_name %> < Dekiru::DataMigration::Migration
+  def title
+    '<%= @name %>'
+  end
+
+  def migration_targets
+    # Define ActiveRecord::Relation that returns the target migration
+    # User.where(some_condition: true)
+  end
+
+  def migrate_record(record)
+    # Define the update process for individual records
+    # user.update!(some_attribute: new_value)
+  end
 end
+
+<%= @class_name %>.run if __FILE__ == $PROGRAM_NAME

data/sig/dekiru/data_migration/migration.rbs

@@ -0,0 +1,23 @@
+module Dekiru
+  module DataMigration
+    class Migration
+      def self.run: (?Hash[Symbol, untyped] options) -> bool
+
+      def title: () -> String
+
+      def migrate: () -> void
+
+      def migration_targets: () -> untyped
+
+      def migrate_record: (untyped record) -> void
+
+      private
+
+      def log: (String message) -> void
+
+      def find_each_with_progress: (untyped scope, ?Hash[Symbol, untyped] options) { (untyped) -> void } -> void
+
+      def each_with_progress: [T] (Enumerable[T] enum, ?Hash[Symbol, untyped] options) { (T) -> void } -> void
+    end
+  end
+end

data/skills/data-migration-script/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: data-migration-script
+description: Skill for creating data migration and deletion scripts using the dekiru-data_migration gem in the social-apartment project. Always use this skill when asked to "create a script using dekiru-data_migration", "create a data migration script", "create a script to delete unnecessary records", or "turn this into a script". Use proactively for DB operations via scripts such as deleting orphaned records after feature removal or code changes, bulk data updates, and deleting ActiveStorage files.
+license: MIT
+---
+
+# Data Migration Script Creation
+
+Create data migration and deletion scripts using the `dekiru-data_migration` gem.
+
+## Preliminary Research
+
+Before writing a script, confirm the following:
+
+1. **Understand the changes**: Review related Issues and PRs to understand what was deleted or changed
+2. **Identify target records**: Check the schema (`db/schema.rb`) and current model code to identify the conditions for records that need to be deleted or updated
+
+## Script Creation Steps
+
+### 1. Generate a file with the generator
+
+```bash
+bin/rails generate maintenance_script <PascalCaseName>
+```
+
+- `<PascalCaseName>` is the name describing the operation in PascalCase (e.g., `DeleteDeliveryNotificationImages`)
+- Generated file: `scripts/YYYYMMDD_delete_delivery_notification_images.rb`
+- Today's date (8 digits) is automatically appended to the class name
+
+### 2. Edit the generated file
+
+Implement `migration_targets` and `migrate_record` in the generated file.
+
+### Common Operation Patterns
+
+**Deleting ActiveStorage attachments**:
+```ruby
+def migration_targets
+  ActiveStorage::Attachment.where(record_type: 'ModelName', name: 'attachment_name')
+end
+
+def migrate_record(record)
+  record.purge  # synchronously delete attachment and blob
+end
+```
+
+**Updating record attributes**:
+```ruby
+def migrate_record(record)
+  record.update!(attribute: new_value)
+end
+```
+
+**Deleting records**:
+```ruby
+def migrate_record(record)
+  record.destroy!
+end
+```
+
+**Conditional skip**:
+```ruby
+def migrate_record(record)
+  return if record.some_condition?
+  record.update!(...)
+end
+```
+
+## Execution and Verification Commands
+
+```bash
+# Check target record count (before execution)
+bin/rails runner "p TargetModel.where(...).count"
+
+# Run the script
+bin/rails runner scripts/YYYYMMDD_description.rb
+
+# Verify after execution
+bin/rails runner "p TargetModel.where(...).count"
+```
+
+## Notes
+
+- `purge` deletes synchronously (immediately removes from storage). Use `purge_later` for async deletion
+- `migration_targets` must return an ActiveRecord relation (processed in batches via `find_each`)
+- Always verify the target record count before running in production

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: dekiru-data_migration
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.1.0
 platform: ruby
 authors:
 - SonicGarden
 bindir: exe
 cert_chain: []
-date: 2025-06-24 00:00:00.000000000 Z
+date: 2026-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -54,6 +54,7 @@ files:
 - Rakefile
 - lib/dekiru/data_migration.rb
 - lib/dekiru/data_migration/dangerous_method_guard.rb
+- lib/dekiru/data_migration/migration.rb
 - lib/dekiru/data_migration/operator.rb
 - lib/dekiru/data_migration/transaction_provider.rb
 - lib/dekiru/data_migration/version.rb
@@ -62,7 +63,9 @@ files:
 - lib/generators/maintenance_script/maintenance_script_generator.rb
 - lib/generators/maintenance_script/templates/maintenance_script.rb.erb
 - sig/dekiru/data_migration.rbs
+- sig/dekiru/data_migration/migration.rbs
 - sig/dekiru/data_migration/operator.rbs
+- skills/data-migration-script/SKILL.md
 homepage: https://github.com/SonicGarden/dekiru-data_migration
 licenses:
 - MIT