arql 0.4.12 → 0.4.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f7af1980c009f6041437078a7b84dba13650e0ab830863e4919202c00500d5c
-  data.tar.gz: a7f073340c540117a418c32372e5c15f4e64137884203c6455def54ee8888479
+  metadata.gz: d444bc5ecc11b4c15db01b52b413341e85525d71d82f24e994315418b728a989
+  data.tar.gz: 1e69014e37aafa3974c3aae3be52c37c7f3c27db2c7b59d169caa8b4de5ce6d7
 SHA512:
-  metadata.gz: b9f78949749ba61a27f51b8d4654e4937da950586901561d3bdc478558dcec4a56dd797569cfa0908de075eaec2c654811b98d107a78fa3c6c5807253c61e680
-  data.tar.gz: 7d8b8f8f0f63de906caaecab8732094727469f59c642ed163275f809ea050276976570d0354311b3cf5a81f1658246e7e38b6b114d49c21c644a0da250bd1865
+  metadata.gz: 0dd50276ddff1a65d3d01bc7eb8ec05dbdd59d441eb8fe2555ca3ccaf2b951650ace6b7bf5908f4eccb2f38a0dec7000130f41c63f62df74e4a8ef4c6504897d
+  data.tar.gz: ada7756d3e50fbff30e8b6581b1eceaebff35fdacb7bf76bf504348410fd7152398515799de35f355e91c3d3cb87d87646a401901da3003bb4b16c2ead88bfd5

data/Gemfile.lock

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

data/README-zh_CN.org

@@ -198,6 +198,7 @@
         除了可以是表示模型名称的字符串外，还可以是一个字符串数组，数组的第一个元素表示模型名称，第二个元素表示为该模型创
         建的常量别名（Arql 默认也会按照一定的规则自动为生成的模型类创建别名，如果这里指定了别名，将会使用用户提供的值作
         为别名）
+    12. =ignored_columns=: 一个列名的数组，在生成模型时将忽略这些列，默认为空数组
 
     =model_names= 配置项的例子:
     

data/README.org

@@ -225,6 +225,7 @@
         representing the constant alias (Arql) created for the model By default, aliases are also automatically created for
         the generated model class according to certain rules, and if an alias is specified here, the user-provided value
         will be used as the alias)
+    12. =ignored_columns= : An array of column names to be ignored when generating the model, default is an empty array
 
     =model_names= Examples of configuration items:
 

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
@@ -158,7 +206,18 @@ module Arql
         end
         self.table_name = table_name
         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]
@@ -170,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
 
@@ -178,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
@@ -215,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
@@ -244,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.12"
+  VERSION = "0.4.15"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arql
 version: !ruby/object:Gem::Version
-  version: 0.4.12
+  version: 0.4.15
 platform: ruby
 authors:
 - Liu Xiang
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-04 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