Status: <%= run.status %>
Started: <%= run.started_at %>
Processed 250 out of 1,000 items (25%).
``` -------------------------------- ### Controller Actions for Task Index and Show Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/task-data.md Provides example controller actions for displaying a list of tasks and preparing a specific task for display, including handling parameters and arguments. ```ruby class TasksController < ApplicationController def index @available_tasks = MaintenanceTasks::TaskDataIndex.available_tasks @grouped_tasks = @available_tasks.group_by(&:category) end def show @task = MaintenanceTasks::TaskDataShow.prepare( params[:id], runs_cursor: params[:cursor], arguments: params.permit!.to_h ) end end ``` -------------------------------- ### Example Task with Custom Count Method Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/task.md This example shows a task that defines a custom `count` method for progress estimation. ```ruby class Maintenance::CustomCountTask < MaintenanceTasks::Task def collection User.all end def count User.count # Optional: return nil to skip progress estimation end def process(user) user.touch end end ``` -------------------------------- ### BatchCsvCollectionBuilder Task Example Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/collection-builders.md Example of configuring a task to use `csv_collection` with batch processing and specific CSV options. ```ruby class Maintenance::ImportTask < MaintenanceTasks::Task csv_collection in_batches: 100, encoding: 'UTF-8' def process(batch) records = batch.map(&:to_h) User.insert_all(records) end end ``` -------------------------------- ### Example Task Reporting Specific Exceptions Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/task.md This example demonstrates using `report_on` to handle `Timeout::Error` and `ApiError` during API synchronization. ```ruby class Maintenance::ApiSyncTask < MaintenanceTasks::Task report_on(Timeout::Error, ApiError) def collection Record.all end def process(record) record.sync_with_api # May raise ApiError end end ``` -------------------------------- ### Task.after_start Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/task.md Registers a callback to run after the task starts. This allows for custom logic to be executed at the beginning of a task. ```APIDOC ## Task.after_start ### Description Register a callback to run after the task starts. ### Method Instance Method ### Parameters #### Path Parameters - **filter_list** (Array) - Optional - List of filters - **block** (Proc) - Required - Callback block ``` -------------------------------- ### Notification Event Subscription Example Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/types.md Example of subscribing to ActiveSupport notifications for maintenance tasks using a regular expression to match event names. ```ruby ActiveSupport::Notifications.subscribe /\.maintenance_tasks\z/ do |name, start, finish, id, payload| # name: "succeeded.maintenance_tasks" # payload: {run_id, job_id, task_name, arguments, metadata, time_running, ...} end ``` -------------------------------- ### Specific Notification Event Subscription Example Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/types.md Example of subscribing to a specific 'succeeded.maintenance_tasks' event to log task completion details. ```ruby ActiveSupport::Notifications.subscribe "succeeded.maintenance_tasks" do |name, start, finish, id, payload| TaskCompletionLog.create!( task_name: payload[:task_name], duration: payload[:time_running] ) end ``` -------------------------------- ### Error Context Subscription Example Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/types.md Example of subscribing to errors using `Rails.error.subscribe` to access the error context payload. ```ruby # Subscribing to errors Rails.error.subscribe do |error, handled:, context:| puts "Task: #{context[:task_name]}" puts "Run: #{context[:run_id]}" if context[:errored_element] puts "Failed on: #{context[:errored_element]}" end end ``` -------------------------------- ### Controller Usage Example Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/runs-page.md Illustrates how to use RunsPage within a Rails controller to fetch and paginate run records. ```ruby class TasksController < ApplicationController def show runs = MaintenanceTasks::Run .where(task_name: params[:id]) .order(created_at: :desc) @page = MaintenanceTasks::RunsPage.new(runs, params[:cursor]) @runs = @page.records @has_next = !@page.last? @next_cursor = @page.next_cursor if @has_next end end ``` -------------------------------- ### Migrate Database Source: https://github.com/shopify/maintenance_tasks/blob/main/README.md Run this command after installing or reinstalling migrations to update the database schema. ```sh-session bin/rails db:migrate ``` -------------------------------- ### NullCollectionBuilder Override Example: collection Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/collection-builders.md Example of overriding the `collection` method in a custom task to define how to retrieve a collection. ```ruby class CustomTask < MaintenanceTasks::Task def collection User.all end end ``` -------------------------------- ### on_start Method Implementation Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/task-job.md Called when the iteration begins. It calculates the total count, updates the Run record, and triggers Task's start callbacks. ```ruby def on_start -> void ``` -------------------------------- ### Query Optimization Example Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/runs-page.md Demonstrates query optimization techniques for forward-only pagination, including loading extra records to detect the next page and checking for its existence without loading the full result set. ```ruby # Loads 21 records to check for next page runs_after_cursor = runs.where("id < ?", cursor).limit(21) # Returns first 20 records = runs_after_cursor.take(20) # Checks if 21st exists without loading full result set has_more = runs_after_cursor.length > 20 ``` -------------------------------- ### Example: Determine if Next Page Exists Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/runs-page.md Demonstrates how to use the `last?` method to determine if a 'Next Page' link should be displayed. ```ruby @page = MaintenanceTasks::RunsPage.new(runs, cursor: params[:cursor]) @show_next = !@page.last? ``` -------------------------------- ### BatchCsvCollectionBuilder Example: Accessing BatchCsv Struct Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/collection-builders.md Example showing how to obtain and access the fields of the BatchCsv struct returned by the `collection` method. ```ruby batch_csv = builder.collection(task) # batch_csv.csv = CSV object ``` -------------------------------- ### Example of Triggering Callbacks on Transition Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/types.md Shows how transitioning a run's status and persisting the transition triggers associated Task callbacks, such as `after_complete`. ```ruby # When run transitions to :succeeded, calls task.run_callbacks(:complete) run.status = :succeeded run.persist_transition # Triggers Task's after_complete callbacks ``` -------------------------------- ### Example Task Class within tasks_module Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/configuration.md Demonstrates defining a task class within the configured `tasks_module` namespace and loading it by name. ```ruby MaintenanceTasks.tasks_module = "Maintenance" # Task files go in: # app/tasks/maintenance/backfill_task.rb class Maintenance::BackfillTask < MaintenanceTasks::Task def collection User.all end def process(user) user.update!(state: "active") end end # Load task by name: task = MaintenanceTasks::Task.named("Maintenance::BackfillTask") ``` -------------------------------- ### Example: Iterate Through Records Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/runs-page.md Shows how to iterate through the records of a RunsPage object and display their task name and status. ```ruby page.records.each do |run| puts "#{run.task_name}: #{run.status}" end ``` -------------------------------- ### Example Custom TaskJob with Conditional Queuing Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/configuration.md Illustrates a custom task job class with queueing logic that depends on the Rails environment. ```ruby class CustomTaskJob < ActiveJob::Base include MaintenanceTasks::TaskJobConcern queue_as { Rails.env.production? ? :production : :default } def on_error(error) Sentry.capture_exception(error) super end end MaintenanceTasks.job = "CustomTaskJob" ``` -------------------------------- ### Instantiate BatchCsv Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/types.md Example of how to instantiate the BatchCsv struct with a CSV object and a batch size. This is typically used with the BatchCsvCollectionBuilder. ```ruby batch_csv = MaintenanceTasks::BatchCsvCollectionBuilder::BatchCsv.new( csv: CSV.new(content, headers: true), batch_size: 100 ) ``` -------------------------------- ### Example: Custom Error Handling with `report_errors_as_handled = false` Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/configuration.md Demonstrates how to subscribe to Rails errors and differentiate between task-handled and unexpected errors when `report_errors_as_handled` is set to false. ```ruby # Report errors as unhandled for better error tracking MaintenanceTasks.report_errors_as_handled = false Rails.error.subscribe do |error, handled:, context:| if context&.dig(:source) == "maintenance-tasks" if handled # Task handled this error with rescue_from logger.info("Task recovered from: #{error}") else # Unexpected error Sentry.capture_exception(error) end end end ``` -------------------------------- ### NullCollectionBuilder Override Example: count Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/collection-builders.md Example of overriding the `count` method in a custom task to define how to count items in a collection. ```ruby class CustomTask < MaintenanceTasks::Task def count User.count end end ``` -------------------------------- ### Example of Catching Task NotFoundError Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/types.md Demonstrates how to use a begin-rescue block to catch `MaintenanceTasks::Task::NotFoundError` when attempting to find a non-existent task. ```ruby begin MaintenanceTasks::Task.named("NonexistentTask") rescue MaintenanceTasks::Task::NotFoundError => e puts "Task not found: #{e.message}" end ``` -------------------------------- ### Check if Run has Started Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/run.md Returns whether the run has begun its execution. Useful for determining if a task is still waiting to be picked up. ```ruby if !run.started? puts "Still waiting to be picked up" end ``` -------------------------------- ### Example Custom TaskJob with Queuing Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/configuration.md Define a custom Active Job class for tasks, including custom queuing logic and error handling. ```ruby class MyTaskJob < MaintenanceTasks::TaskJob queue_as :maintenance_high_priority end MaintenanceTasks.job = "MyTaskJob" ``` -------------------------------- ### Example: Using Complex Cursors with JSON Serialization Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/configuration.md Illustrates defining a task that uses multiple cursor columns when `serialize_cursors_as_json` is enabled. ```ruby MaintenanceTasks.serialize_cursors_as_json = true # Now cursors can be complex structures class Maintenance::CompositeKeyTask < MaintenanceTasks::Task def cursor_columns [:user_id, :created_at, :id] # Multiple columns end def process(record) record.touch end end ``` -------------------------------- ### Run.with_attached_csv Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/run.md Eagerly loads the associated CSV file attachment if Active Storage is installed. ```APIDOC ## Run.with_attached_csv ### Description Eagerly loads associated CSV file attachment if Active Storage is installed. ### Method `Run.with_attached_csv` ### Parameters None ### Response Returns an `ActiveRecord::Relation` of `Run` objects with the CSV attachment loaded. ### Request Example ```ruby runs = MaintenanceTasks::Run.with_attached_csv.limit(10) ``` ``` -------------------------------- ### Install Maintenance Task Migrations Source: https://github.com/shopify/maintenance_tasks/blob/main/README.md Use this command to copy the gem's migrations to your db/migrate folder, especially if previous migrations were deleted. ```sh-session bin/rails maintenance_tasks:install:migrations ``` -------------------------------- ### CsvCollectionBuilder Example: Processing CSV Content Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/collection-builders.md Demonstrates how to retrieve and iterate over a CSV object obtained from the task's content. ```ruby csv_content = "name,email\nAlice,alice@example.com\nBob,bob@example.com" task.csv_content = csv_content csv = task.collection_builder_strategy.collection(task) csv.each do |row| # row = {"name" => "Alice", "email" => "alice@example.com"} end ``` -------------------------------- ### Example: Conditional Logic for Stale Tasks Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/task-data.md Demonstrates using the `stale?` method to conditionally hide tasks from the main list and show them in an archive. ```ruby if task_data.stale? # Hide from main list, show in archive end ``` -------------------------------- ### Example of Valid and Invalid Status Transitions Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/types.md Illustrates how to set run statuses and the expected outcome, including a valid transition and an invalid one that raises `ActiveRecord::RecordInvalid`. ```ruby run.status = :running run.status = :paused # Valid run.save! run.status = :cancelled # Invalid (paused → cancelled not allowed) run.save! # Raises ActiveRecord::RecordInvalid ``` -------------------------------- ### Example Task Using NoCollectionBuilder Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/collection-builders.md Demonstrates how to use `no_collection` within a Maintenance::Task subclass to perform a single operation, such as clearing and warming the cache. ```ruby class Maintenance::CacheWarmer < MaintenanceTasks::Task no_collection def process Rails.cache.clear Rails.cache.warm_up end end ``` -------------------------------- ### Example CSV Data Source: https://github.com/shopify/maintenance_tasks/blob/main/README.md Sample data for a CSV file used with a CSV Maintenance Task. It includes headers and rows for importing posts. ```csv title,content My Title,Hello World! ``` -------------------------------- ### Initialize TaskDataShow Instance Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/task-data.md Creates a TaskDataShow instance. Accepts task name, an optional runs cursor for pagination, and optional arguments. ```ruby TaskDataShow.new(name, runs_cursor: nil, arguments: nil) ``` -------------------------------- ### Get Task Instance from Run Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/run.md Returns a Task instance with arguments assigned from the run. CSV content is not populated here and must be loaded separately. ```ruby task = run.task puts task.class.name ``` -------------------------------- ### TaskDataShow.new Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/task-data.md Creates a TaskDataShow instance with the specified name, runs cursor, and arguments. ```APIDOC ## TaskDataShow.new ### Description Creates a TaskDataShow instance. ### Method Instance Method ### Signature `TaskDataShow.new(name, runs_cursor: nil, arguments: nil)` ### Parameters #### Arguments - **name** (String) - Task class name - **runs_cursor** (String, nil) - Cursor for run pagination - **arguments** (Hash, nil) - Arguments to assign to Task ``` -------------------------------- ### Run a Maintenance Task in Rails Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/api-reference/cli.md Install the gem and run maintenance tasks from your Rails application directory. The CLI automatically loads the Rails environment. ```bash cd myapp bundle exec maintenance_tasks perform Maintenance::MyTask ``` -------------------------------- ### Example ERB for Task Show Page Source: https://github.com/shopify/maintenance_tasks/blob/main/_autodocs/endpoints.md This ERB template displays task details, including its name, source code (if available), active runs, and run history. It utilizes instance variables like `@task` and its associated objects. ```erb<%= @task.code %>