has_aux_table/backlog/docs/project_overview.md

ActiveRecord Auxiliary Table - Project Overview

Purpose

This gem extends ActiveRecord's Single Table Inheritance (STI) capabilities by allowing developers to define auxiliary tables that are automatically joined to subclasses. This solves the fundamental RDBMS limitation where subclasses cannot have additional columns with their own indexes beyond what's defined in the parent table.

Key Benefits

1. Reduced Schema Bloat: Subclass-specific columns are stored in separate auxiliary tables
2. Improved Index Performance: Each auxiliary table can have its own optimized indexes
3. Better Query Performance: Queries against subclass-specific columns are more efficient
4. Easier Maintenance: Adding new subclass columns doesn't require altering the parent table

Architecture

The gem works by:

1. Allowing subclasses to define auxiliary tables via aux_table method
2. Automatically creating associations between the main STI table and auxiliary tables
3. Providing transparent attribute access to auxiliary columns
4. Extending ActiveRecord's query methods to handle auxiliary table joins

Example Usage

class Vehicle < ActiveRecord::Base
  include HasAuxTable
end

class Car < Vehicle
  aux_table :car_aux do |t|
    t.decimal :engine_size, precision: 3, scale: 1
    t.string :fuel_type, limit: 50
    t.timestamps
  end
end

# Usage
car = Car.create!(name: "Toyota", engine_size: 2.5, fuel_type: "gasoline")
fast_cars = Car.where(engine_size: 3.0..8.0)

Implementation Phases

1. Phase 1: Core functionality - basic auxiliary table support
2. Phase 2: Advanced features - query optimization, validation support
3. Phase 3: Migration tools and performance enhancements

Technical Stack

• Ruby 3.1+
• ActiveRecord 7.0+
• RSpec for testing
• Sorbet for type checking