arql 0.4.13 → 0.4.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b67b593bb1bb99cb10e911067353ee07d3e3bd63736d115bb449550b2c2e395
-  data.tar.gz: 7e586dab61df6eb6c71ea37ac60b2e2dc76b00ccb363964d32b2e986972d637c
+  metadata.gz: d444bc5ecc11b4c15db01b52b413341e85525d71d82f24e994315418b728a989
+  data.tar.gz: 1e69014e37aafa3974c3aae3be52c37c7f3c27db2c7b59d169caa8b4de5ce6d7
 SHA512:
-  metadata.gz: d21f517315f2abbecca08d19d0bce1879b8cd2a6eda19d2e70ccc6ee7ff8623c774b8e89211d85711fe1d991cb001235331a03b830c6bdb9ab27fd6a9e525e71
-  data.tar.gz: 616dd1c78f257532c7999800ee2e966e6942e06eaafa2a519dde2c6d8938e780f8a7634c4ce29d260880ad26bf8fc70b4d8dd5306098d9a82bd51eb294535239
+  metadata.gz: 0dd50276ddff1a65d3d01bc7eb8ec05dbdd59d441eb8fe2555ca3ccaf2b951650ace6b7bf5908f4eccb2f38a0dec7000130f41c63f62df74e4a8ef4c6504897d
+  data.tar.gz: ada7756d3e50fbff30e8b6581b1eceaebff35fdacb7bf76bf504348410fd7152398515799de35f355e91c3d3cb87d87646a401901da3003bb4b16c2ead88bfd5

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    arql (0.4.13)
+    arql (0.4.15)
       activerecord (>= 6.1.5, < 7.1.0)
       activesupport (>= 6.1.5, < 7.1.0)
       caxlsx (~> 3.3.0)

data/docs/plans/2026-04-02-rename-columns-design.md

@@ -0,0 +1,275 @@
+# rename_columns Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add `rename_columns` config option that creates AR-level attribute aliases for columns with conflicting names (e.g., `model_name`).
+
+**Architecture:** In `lib/arql/definition.rb`, add `rename_columns_mapping` accessor, modify `make_model_class` to merge renamed columns into `ignored_columns` and call `alias_attribute`, and add `validate_rename_columns!` for three-layer conflict detection at startup.
+
+**Tech Stack:** Ruby, ActiveRecord `alias_attribute`, `ignored_columns`, `ActiveRecord::AttributeMethods.dangerous_attribute_methods`
+
+---
+
+### Task 1: Add `rename_columns_mapping` accessor method
+
+**Files:**
+- Modify: `lib/arql/definition.rb:95-97` (after `model_names_mapping`)
+
+**Step 1: Add the method**
+
+After line 97 (`end` of `model_names_mapping`), add:
+
+```ruby
+    def rename_columns_mapping
+      @rename_columns_mapping ||= @options[:rename_columns] || {}
+    end
+```
+
+This follows the exact same pattern as `model_names_mapping` on line 95.
+
+**Step 2: Verify syntax**
+
+Run: `ruby -c lib/arql/definition.rb`
+Expected: `Syntax OK`
+
+**Step 3: Commit**
+
+```bash
+git add lib/arql/definition.rb
+git commit -m "feat: add rename_columns_mapping accessor"
+```
+
+---
+
+### Task 2: Modify `make_model_class` to handle column renaming
+
+**Files:**
+- Modify: `lib/arql/definition.rb:150-175` (the `make_model_class` method)
+
+**Step 1: Implement the rename logic inside the Class.new block**
+
+Replace lines 150-175 with:
+
+```ruby
+    def make_model_class(table_name, primary_keys)
+      options = @options
+      rename_columns = rename_columns_mapping
+      Class.new(@base_model) do
+        include Arql::Extension
+        if primary_keys.is_a?(Array) && primary_keys.size > 1
+          self.primary_keys = primary_keys
+        else
+          self.primary_key = primary_keys&.first
+        end
+        self.table_name = table_name
+        self.inheritance_column = nil
+
+        # Merge renamed column original names into ignored_columns
+        ignored = Array(options[:ignored_columns])
+        rename_columns.each do |old_name, new_name|
+          ignored << old_name.to_s
+        end
+        self.ignored_columns = ignored.uniq if ignored.present?
+
+        ActiveRecord.default_timezone = :local
+        if options[:created_at].present?
+          define_singleton_method :timestamp_attributes_for_create do
+            options[:created_at]
+          end
+        end
+
+        if options[:updated_at].present?
+          define_singleton_method :timestamp_attributes_for_update do
+            options[:updated_at]
+          end
+        end
+
+        # Create alias attributes for renamed columns
+        rename_columns.each do |old_name, new_name|
+          alias_attribute new_name.to_sym, old_name.to_sym
+        end
+      end
+    end
+```
+
+Key changes from the original:
+1. `ignored_columns` now merges both `options[:ignored_columns]` and all `rename_columns` original names
+2. `alias_attribute` is called for each rename mapping inside the `Class.new` block
+
+**Step 2: Verify syntax**
+
+Run: `ruby -c lib/arql/definition.rb`
+Expected: `Syntax OK`
+
+**Step 3: Commit**
+
+```bash
+git add lib/arql/definition.rb
+git commit -m "feat: integrate rename_columns into make_model_class with ignored_columns merge and alias_attribute"
+```
+
+---
+
+### Task 3: Add `validate_rename_columns!` with three-layer conflict detection
+
+**Files:**
+- Modify: `lib/arql/definition.rb` (add new method after `rename_columns_mapping`)
+
+**Step 1: Add the validation method**
+
+After the `rename_columns_mapping` method, add:
+
+```ruby
+    ARQL_EXTENSION_INSTANCE_METHODS = %i[v t vd to_insert_sql to_upsert_sql dump write_csv write_excel].freeze
+
+    def validate_rename_columns!(table_name, model_class)
+      rename_columns = rename_columns_mapping
+      table_column_names = model_class.column_names.map(&:to_s)
+      ar_reserved = ActiveRecord::AttributeMethods.dangerous_attribute_methods
+
+      rename_columns.each do |old_name, new_name|
+        old_name = old_name.to_s
+        new_name = new_name.to_s
+
+        # Check: original column must exist in the table
+        unless table_column_names.include?(old_name)
+          warn "rename_columns: column '#{old_name}' not found in table '#{table_name}', skipping"
+          next
+        end
+
+        # Check: new name must not conflict with existing column names
+        if table_column_names.include?(new_name) && new_name != old_name
+          warn "rename_columns: new name '#{new_name}' conflicts with existing column in table '#{table_name}', skipping rename of '#{old_name}'"
+          next
+        end
+
+        # Check: new name must not be an ActiveRecord reserved attribute method
+        if ar_reserved.include?(new_name)
+          raise ActiveRecord::DangerousAttributeError,
+            "rename_columns: new name '#{new_name}' is a reserved ActiveRecord method, cannot use as column alias"
+        end
+
+        # Check: new name must not conflict with arql Extension instance methods
+        if ARQL_EXTENSION_INSTANCE_METHODS.include?(new_name.to_sym)
+          warn "rename_columns: new name '#{new_name}' conflicts with an arql method in table '#{table_name}', skipping rename of '#{old_name}'"
+          next
+        end
+      end
+    end
+```
+
+**Step 2: Verify syntax**
+
+Run: `ruby -c lib/arql/definition.rb`
+Expected: `Syntax OK`
+
+**Step 3: Commit**
+
+```bash
+git add lib/arql/definition.rb
+git commit -m "feat: add validate_rename_columns! with three-layer conflict detection"
+```
+
+---
+
+### Task 4: Wire up validation in `define_model_from_table` and `redefine`
+
+**Files:**
+- Modify: `lib/arql/definition.rb:99-114` (`define_model_from_table`)
+- Modify: `lib/arql/definition.rb:39-53` (`redefine`)
+
+**Step 1: Add validation call in `define_model_from_table`**
+
+In `define_model_from_table`, after line 113 (the return hash), add the validation call. The method should become:
+
+```ruby
+    def define_model_from_table(table_name, primary_keys)
+      model_name = make_model_name(table_name)
+      return unless model_name
+
+      model_class = make_model_class(table_name, primary_keys)
+      validate_rename_columns!(table_name, model_class)
+      @namespace_module.const_set(model_name, model_class)
+      abbr_name = make_model_abbr_name(model_name, table_name)
+      @namespace_module.const_set(abbr_name, model_class)
+
+      { model: model_class, abbr: "#@namespace::#{abbr_name}", table: table_name }
+    end
+```
+
+Only change: added `validate_rename_columns!(table_name, model_class)` after `make_model_class` and before `const_set`.
+
+**Step 2: Verify `redefine` already works**
+
+The `redefine` method (line 39) calls `define_model_from_table`, so it automatically picks up the validation. No changes needed to `redefine`.
+
+**Step 3: Verify syntax**
+
+Run: `ruby -c lib/arql/definition.rb`
+Expected: `Syntax OK`
+
+**Step 4: Commit**
+
+```bash
+git add lib/arql/definition.rb
+git commit -m "feat: wire up validate_rename_columns! in define_model_from_table"
+```
+
+---
+
+### Task 5: Manual verification
+
+**Files:** None (testing only)
+
+**Step 1: Verify with a real database**
+
+Create a test SQLite database with a `model_name` column, configure `rename_columns`, and verify:
+
+```bash
+# Create test DB
+sqlite3 /tmp/arql_test.db "CREATE TABLE test_table (id INTEGER PRIMARY KEY, model_name TEXT, name TEXT); INSERT INTO test_table VALUES (1, 'TestModel', 'Alice');"
+
+# Create config
+cat > /tmp/arql_test.yml << 'EOF'
+default:
+  adapter: sqlite3
+  database: /tmp/arql_test.db
+  rename_columns:
+    model_name: record_model_name
+EOF
+
+# Run arql
+arql -c /tmp/arql_test.yml -E 'puts TestTable.last.record_model_name'
+```
+
+Expected output: `TestModel`
+
+**Step 2: Verify query aliasing**
+
+```bash
+arql -c /tmp/arql_test.yml -S -E 'puts TestTable.where(record_model_name: "TestModel").to_sql'
+```
+
+Expected output contains: `WHERE "test_table"."model_name" = 'TestModel'`
+
+**Step 3: Verify conflict detection**
+
+```bash
+cat > /tmp/arql_test_bad.yml << 'EOF'
+default:
+  adapter: sqlite3
+  database: /tmp/arql_test.db
+  rename_columns:
+    model_name: save
+EOF
+
+arql -c /tmp/arql_test_bad.yml -E 'puts "hello"'
+```
+
+Expected: `ActiveRecord::DangerousAttributeError` with message about `save` being reserved.
+
+**Step 4: Cleanup**
+
+```bash
+rm /tmp/arql_test.db /tmp/arql_test.yml /tmp/arql_test_bad.yml
+```

data/lib/arql/definition.rb

@@ -2,7 +2,6 @@ require 'arql/concerns'
 require 'arql/vd'
 
 module Arql
-
   class BaseModel < ::ActiveRecord::Base
     self.abstract_class = true
 
@@ -24,9 +23,10 @@ module Arql
 
     def self.method_missing(method_name, *args, &block)
       if method_name.to_s =~ /^(.+)_like$/
-        attr_name = $1.to_sym
+        attr_name = ::Regexp.last_match(1).to_sym
         return super unless has_attribute?(attr_name)
-        send(:like, $1 => args.first)
+
+        send(:like, ::Regexp.last_match(1) => args.first)
       else
         super
       end
@@ -34,7 +34,7 @@ module Arql
   end
 
   class Definition
-    attr :connection, :ssh_proxy, :options, :models, :namespace_module, :namespace
+    attr_reader :connection, :ssh_proxy, :options, :models, :namespace_module, :namespace
 
     def redefine
       @models.each do |model|
@@ -78,16 +78,14 @@ module Arql
       end
 
       order_column = @options[:order_column]
-      if order_column
-        @models.each do |model|
-          model_class = model[:model]
-          model_class.define_singleton_method(:implicit_order_column) do
-            if column_names.include?(order_column)
-              order_column
-            else
-              nil
-            end
-          end
+      return unless order_column
+
+      @models.each do |model|
+        model_class = model[:model]
+        model_class.define_singleton_method(:implicit_order_column) do
+          return unless column_names.include?(order_column)
+
+          order_column
         end
       end
     end
@@ -96,11 +94,59 @@ module Arql
       @model_names_mapping ||= @options[:model_names] || {}
     end
 
+    def rename_columns_mapping
+      @rename_columns_mapping ||= @options[:rename_columns] || {}
+    end
+
+    ARQL_EXTENSION_INSTANCE_METHODS = %i[v t vd to_insert_sql to_upsert_sql dump write_csv write_excel].freeze
+
+    def validate_rename_columns!(table_name, model_class)
+      table_column_names_set = model_class.column_names.to_set
+      return unless table_column_names_set.intersect?(rename_columns_mapping.keys.map(&:to_s).to_set)
+
+      ar_reserved = ActiveRecord::AttributeMethods.dangerous_attribute_methods
+
+      rename_columns_mapping.each do |old_name, new_name|
+        next unless table_column_names_set.include?(old_name.to_s)
+
+        new_name = new_name.to_s
+
+        if table_column_names_set.include?(new_name) && new_name != old_name.to_s
+          warn "rename_columns: new name '#{new_name}' already exists in table '#{table_name}', skipping rename of '#{old_name}'"
+          next
+        end
+
+        if ar_reserved.include?(new_name)
+          raise ActiveRecord::DangerousAttributeError,
+                "rename_columns: new name '#{new_name}' is a reserved ActiveRecord method"
+        end
+
+        if ARQL_EXTENSION_INSTANCE_METHODS.include?(new_name.to_sym)
+          warn "rename_columns: new name '#{new_name}' conflicts with an arql method in table '#{table_name}', skipping rename of '#{old_name}'"
+          next
+        end
+      end
+    end
+
     def define_model_from_table(table_name, primary_keys)
       model_name = make_model_name(table_name)
       return unless model_name
 
       model_class = make_model_class(table_name, primary_keys)
+      if rename_columns_mapping.present?
+        validate_rename_columns!(table_name, model_class)
+        relevant_old_names = rename_columns_mapping.keys.select { |n| model_class.column_names.include?(n.to_s) }
+        if relevant_old_names.any?
+          model_class.define_attribute_methods
+          mod = model_class.send(:generated_attribute_methods)
+          relevant_old_names.each do |old_name|
+            old_name = old_name.to_s
+            [old_name.to_sym, :"#{old_name}=", :"#{old_name}?"].each do |m|
+              mod.send(:remove_method, m) if mod.method_defined?(m)
+            end
+          end
+        end
+      end
       @namespace_module.const_set(model_name, model_class)
       abbr_name = make_model_abbr_name(model_name, table_name)
       @namespace_module.const_set(abbr_name, model_class)
@@ -110,7 +156,7 @@ module Arql
       #   Object.const_set(abbr_name, model_class)
       # end
 
-      { model: model_class, abbr: "#@namespace::#{abbr_name}", table: table_name }
+      { model: model_class, abbr: "#{@namespace}::#{abbr_name}", table: table_name }
     end
 
     def make_model_abbr_name(model_name, table_name)
@@ -149,6 +195,8 @@ module Arql
 
     def make_model_class(table_name, primary_keys)
       options = @options
+      rename_columns = rename_columns_mapping
+      renamed_old_names = rename_columns.keys.map(&:to_s)
       Class.new(@base_model) do
         include Arql::Extension
         if primary_keys.is_a?(Array) && primary_keys.size > 1
@@ -160,6 +208,16 @@ module Arql
         self.inheritance_column = nil
         self.ignored_columns = options[:ignored_columns] if options[:ignored_columns].present?
         ActiveRecord.default_timezone = :local
+
+        if renamed_old_names.any?
+          define_singleton_method(:instance_method_already_implemented?) do |method_name|
+            name = method_name.to_s.sub(/[=?\z]/, '')
+            return false if renamed_old_names.include?(name)
+
+            super(method_name)
+          end
+        end
+
         if options[:created_at].present?
           define_singleton_method :timestamp_attributes_for_create do
             options[:created_at]
@@ -171,6 +229,26 @@ module Arql
             options[:updated_at]
           end
         end
+
+        if rename_columns.present?
+          rename_columns.each do |old_name, new_name|
+            new_sym = new_name.to_sym
+            define_method(new_sym) { read_attribute(old_name.to_s) }
+            define_method(:"#{new_sym}=") { |value| write_attribute(old_name.to_s, value) }
+            define_method(:"#{new_sym}?") { !!read_attribute(old_name.to_s) }
+          end
+          self.attribute_aliases = rename_columns.transform_keys(&:to_sym).invert
+
+          original_inspect = instance_method(:inspect)
+          rename_columns_for_inspect = rename_columns.dup
+          define_method(:inspect) do
+            result = original_inspect.bind(self).call
+            rename_columns_for_inspect.each do |old_name, new_name|
+              result = result.sub(/\b#{Regexp.escape(old_name.to_s)}(?=:)/, new_name.to_s)
+            end
+            result
+          end
+        end
       end
     end
 
@@ -179,13 +257,14 @@ module Arql
       Arql::SSHProxy.new(
         ssh_config.slice(:host, :user, :port, :password)
           .merge(forward_host: @options[:host],
-            forward_port: @options[:port],
-            local_port: ssh_config[:local_port]))
+                 forward_port: @options[:port],
+                 local_port: ssh_config[:local_port])
+      )
     end
 
     def get_connection_options
       connect_conf = @options.slice(:adapter, :host, :username, :password,
-                                :database, :encoding, :pool, :port, :socket)
+                                    :database, :encoding, :pool, :port, :socket)
       connect_conf.merge!(@ssh_proxy.database_host_port) if @ssh_proxy
       connect_conf
     end
@@ -216,8 +295,7 @@ module Arql
     def create_namespace_module(namespace)
       definition = self
 
-      Object.const_set(namespace, Module.new {
-
+      Object.const_set(namespace, Module.new do
         define_singleton_method(:config) do
           definition.options
         end
@@ -245,7 +323,7 @@ module Arql
         define_singleton_method(:dump) do |filename, no_create_db = false|
           Arql::Mysqldump.new(definition.options).dump_database(filename, no_create_db)
         end
-      })
+      end)
     end
   end
 end

data/lib/arql/version.rb

@@ -1,3 +1,3 @@
 module Arql
-  VERSION = "0.4.13"
+  VERSION = "0.4.15"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arql
 version: !ruby/object:Gem::Version
-  version: 0.4.13
+  version: 0.4.15
 platform: ruby
 authors:
 - Liu Xiang
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-29 00:00:00.000000000 Z
+date: 2026-04-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mysql2
@@ -330,6 +330,7 @@ files:
 - custom-configurations.org
 - define-associations-zh_CN.org
 - define-associations.org
+- docs/plans/2026-04-02-rename-columns-design.md
 - exe/arql
 - exe/arql_setsid_wrapper
 - fuzzy-field-query-zh_CN.org