arql 0.4.13 → 0.4.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b67b593bb1bb99cb10e911067353ee07d3e3bd63736d115bb449550b2c2e395
-  data.tar.gz: 7e586dab61df6eb6c71ea37ac60b2e2dc76b00ccb363964d32b2e986972d637c
+  metadata.gz: 2e298f643cc8cba53568449f235fed8f490cb93b35f6238477f3031bac708cf4
+  data.tar.gz: 5a575e23be87acd3031bcc870d6ed538c651b75f3bbdc7ffd258730bd1008ea7
 SHA512:
-  metadata.gz: d21f517315f2abbecca08d19d0bce1879b8cd2a6eda19d2e70ccc6ee7ff8623c774b8e89211d85711fe1d991cb001235331a03b830c6bdb9ab27fd6a9e525e71
-  data.tar.gz: 616dd1c78f257532c7999800ee2e966e6942e06eaafa2a519dde2c6d8938e780f8a7634c4ce29d260880ad26bf8fc70b4d8dd5306098d9a82bd51eb294535239
+  metadata.gz: c0de2dc777e08f079a7a52ab1423a5139b42bbf12fb7b315fe3ce4f44d525ab699629fdedde4bbd661fe98409692c36ab3800c232272e61d0b49a8b1ff2d1ced
+  data.tar.gz: c1e1aca6d3ead4305fd70dee0fbd5cb00e68ed87c39db856b2d6bf5080c4b7d3b2adc1fa20e5519e6b7bad295487e1fcd0604310ee6f7b3403cc218db179646f

data/Gemfile.lock

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

data/README-zh_CN.org

@@ -199,6 +199,40 @@
         建的常量别名（Arql 默认也会按照一定的规则自动为生成的模型类创建别名，如果这里指定了别名，将会使用用户提供的值作
         为别名）
     12. =ignored_columns=: 一个列名的数组，在生成模型时将忽略这些列，默认为空数组
+    13. =rename_columns=: 一个 Hash，用于将数据库列名映射为新的名称。当列名与 ActiveRecord 内置方法冲突时（例如 =model_name=、
+        =valid=、=connection=、=type= 等），会导致 =ActiveRecord::DangerousAttributeError= 错误。使用此配置项可以重命名这些冲突列。
+        重命名后，原始列名将被隐藏，只能通过新名称访问。新名称同样可用于查询（例如 =where(new_name: 'value')=
+        会自动翻译为 =WHERE old_name = 'value'=）。arql 会在启动时校验新名称，确保其不与已有列名、ActiveRecord 保留方法名
+        或 arql 内置方法名冲突。如果新名称是 ActiveRecord 保留方法名，arql 将在启动时报错。
+
+    =rename_columns= 配置项示例:
+
+    #+BEGIN_SRC yaml
+        development:
+          adapter: mysql2
+          host: localhost
+          database: myapp
+          rename_columns:
+            model_name: record_model_name
+            valid: is_valid
+            type: biz_type
+    #+END_SRC
+
+    使用以上配置后:
+
+    #+begin_example
+    ARQL@dev(main) [1] ❯ Attachment.last
+    => #<I::Attachment:0xabc id: 1, record_model_name: "SomeModel", is_valid: true, biz_type: "image">
+
+    ARQL@dev(main) [2] ❯ Attachment.where(record_model_name: "SomeModel").to_sql
+    => "SELECT `attachments`.* FROM `attachments` WHERE `attachments`.`model_name` = 'SomeModel'"
+
+    ARQL@dev(main) [3] ❯ Attachment.last.is_valid
+    => true
+
+    ARQL@dev(main) [4] ❯ Attachment.last.model_name
+    => NoMethodError (原始名称已被隐藏)
+    #+end_example
 
     =model_names= 配置项的例子:
     

data/README.org

@@ -226,6 +226,41 @@
         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
+    13. =rename_columns= : A hash mapping original column names to new names. When a column name conflicts with an ActiveRecord
+        built-in method (e.g., =model_name=, =valid=, =connection=, =type=), it causes =ActiveRecord::DangerousAttributeError=.
+        Use this option to rename conflicting columns. The original column name will be hidden and only the new name will be
+        accessible. The new name also works in queries (e.g., =where(new_name: 'value')= translates to =WHERE old_name = 'value'=).
+        Arql validates that the new name does not conflict with existing columns, ActiveRecord reserved methods, or arql
+        built-in methods. If the new name is an ActiveRecord reserved method, arql will raise an error at startup.
+
+    Example of =rename_columns= configuration:
+
+    #+BEGIN_SRC yaml
+        development:
+          adapter: mysql2
+          host: localhost
+          database: myapp
+          rename_columns:
+            model_name: record_model_name
+            valid: is_valid
+            type: biz_type
+    #+END_SRC
+
+    With the above configuration:
+
+    #+begin_example
+    ARQL@dev(main) [1] ❯ Attachment.last
+    => #<I::Attachment:0xabc id: 1, record_model_name: "SomeModel", is_valid: true, biz_type: "image">
+
+    ARQL@dev(main) [2] ❯ Attachment.where(record_model_name: "SomeModel").to_sql
+    => "SELECT `attachments`.* FROM `attachments` WHERE `attachments`.`model_name` = 'SomeModel'"
+
+    ARQL@dev(main) [3] ❯ Attachment.last.is_valid
+    => true
+
+    ARQL@dev(main) [4] ❯ Attachment.last.model_name
+    => NoMethodError (original name is hidden)
+    #+end_example
 
     =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
@@ -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,40 @@ 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
+
+          rename_map = rename_columns.transform_keys(&:to_s)
+          define_method(:pretty_print) do |pp|
+            pp.object_address_group(self) do
+              if defined?(@attributes) && @attributes
+                attr_names = self.class.attribute_names.select { |name| _has_attribute?(name) }
+                pp.seplist(attr_names, proc { pp.text ',' }) do |attr_name|
+                  display_name = rename_map.fetch(attr_name, attr_name)
+                  pp.breakable ' '
+                  pp.group(1) do
+                    pp.text display_name
+                    pp.text ':'
+                    pp.breakable
+                    value = _read_attribute(attr_name)
+                    value = inspection_filter.filter_param(attr_name, value) unless value.nil?
+                    pp.pp value
+                  end
+                end
+              else
+                pp.breakable ' '
+                pp.text 'not initialized'
+              end
+            end
+          end
+        end
       end
     end
 
@@ -179,13 +271,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 +309,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 +337,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.16"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: arql
 version: !ruby/object:Gem::Version
-  version: 0.4.13
+  version: 0.4.16
 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