appquery 0.3.0 → 0.4.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64e74167bbafa7217db5f9c0bab6efc8b55655abbbcb7e2fccefca3dfe1afae8
-  data.tar.gz: 16f6870106206b547ed307fb6cbcd8d9250610239ccf9dc046e6e6c9719d76dd
+  metadata.gz: 585ecafd973b1dd9fc8c944b93c64998a8b983438250cbd1ec81317d9e2362d4
+  data.tar.gz: 8197dc68853e7299266a0f8c2dd7fa102bbbf7e743680786bce4c7c2eedcd719
 SHA512:
-  metadata.gz: 74ce3c5a8d22b2b41bc477069e9720c7b91cad52909ee3e4db8533c0a6f357227ec7e9485f513b8306a0d4994b53556971ae09284c72c2c5370bee45a0c244e3
-  data.tar.gz: 61b01b05753f3a6f27194e47b40bb91aa822c5c263dbe78d0328f1b09aad02d95acbfc7ba191d4fb773b536c1b1ad03465e05c87c4ecf1dc279ed3e461ba97b2
+  metadata.gz: 37b5baf0f42dbad9ee1f356e0541b5677cb93a934d38ad851931142f79a041337f77cbbd4f56c1e880b4db9140460237afa8627eb0f6f9c73461fc1f6b3843cb
+  data.tar.gz: 3edc3e28e09a648a3d14634beab10cdde1be8d1b31c6c8163fd2f19844fab31a5ecf762ddcef9311f18d1356fe6e2c765f99dd2d08706284c687e94d21c36261

data/.irbrc

@@ -0,0 +1,20 @@
+puts "Loading #{__FILE__}"
+# put overrides/additions in '_irbrc'
+
+IRB.conf[:HISTORY_FILE] = "#{ENV["PROJECT_ROOT"]}/tmp/.irb_history"
+
+# Custom IRB prompt showing database adapter
+db_indicator = begin
+  adapter = ActiveRecord::Base.connection.adapter_name.downcase
+  "\e[33m[#{adapter}]\e[0m "
+rescue ActiveRecord::ConnectionNotEstablished, NameError
+  "\e[34m[no-db]\e[0m "
+end
+
+IRB.conf[:PROMPT][:APPQUERY] = {
+  PROMPT_I: "#{db_indicator}appquery> ",
+  PROMPT_S: "#{db_indicator}appquery%l ",
+  PROMPT_C: "#{db_indicator}appquery* ",
+  RETURN: "=> %s\n"
+}
+IRB.conf[:PROMPT_MODE] = :APPQUERY

data/Appraisals

@@ -1,15 +1,25 @@
 appraise "rails-70" do
-  gem "rails", "~> 7.0"
+  gem "rails", "~> 7.0.0"
+  gem "sqlite3", "~> 1.4"
 end
 
 appraise "rails-71" do
-  gem "rails", "~> 7.1"
+  gem "rails", "~> 7.1.0"
 end
 
 appraise "rails-72" do
-  gem "rails", "~> 7.2"
+  gem "rails", "~> 7.2.0"
 end
 
 appraise "rails-80" do
-  gem "rails", "~> 8.0"
+  gem "rails", "~> 8.0.0"
+end
+
+appraise "rails-81" do
+  gem "rails", "~> 8.1.0"
+end
+
+appraise "rails-head" do
+  gem "activerecord", github: "rails/rails"
+  gem "rails", github: "rails/rails"
 end

data/README.md

@@ -95,60 +95,65 @@ Testdriving can be easily done from the console. Either by cloning this reposito
   ```
 </details>
 
-The following examples assume PostgreSQL (SQLite where stated):
+The prompt indicates what adapter the example uses:
 
 ```ruby
 # showing select_(all|one|value)
-> AppQuery(%{select date('now') as today}).select_all.to_a
+[postgresql]> AppQuery(%{select date('now') as today}).select_all.to_a
 => [{"today" => "2025-05-10"}]
-> AppQuery(%{select date('now') as today}).select_one
+[postgresql]> AppQuery(%{select date('now') as today}).select_one
 => {"today" => "2025-05-10"}
-> AppQuery(%{select date('now') as today}).select_value
+[postgresql]> AppQuery(%{select date('now') as today}).select_value
 => "2025-05-10"
 
 # binds
 # positional binds
-> AppQuery(%{select now() - ($1)::interval as date}).select_value(binds: ['2 days'])
+[postgresql]> AppQuery(%{select now() - ($1)::interval as date}).select_value(binds: ['2 days'])
 # named binds
-> AppQuery(%{select now() - (:interval)::interval as date}).select_value(binds: {interval: '2 days'})
+[postgresql]> AppQuery(%{select now() - (:interval)::interval as date}).select_value(binds: {interval: '2 days'})
 
 # casting
-> AppQuery(%{select date('now') as today}).select_all(cast: true).to_a
+[postgresql]> AppQuery(%{select date('now') as today}).select_all(cast: true).to_a
 => [{"today" => Sat, 10 May 2025}]
 
 ## SQLite doesn't have a notion of dates or timestamp's so casting won't do anything:
-sqlite> AppQuery(%{select date('now') as today}).select_one(cast: true)
+[sqlite]> AppQuery(%{select date('now') as today}).select_one(cast: true)
 => {"today" => "2025-05-12"}
 ## Providing per-column-casts fixes this:
 casts = {"today" => ActiveRecord::Type::Date.new}
-sqlite> AppQuery(%{select date('now') as today}).select_one(cast: casts)
+[sqlite]> AppQuery(%{select date('now') as today}).select_one(cast: casts)
 => {"today" => Mon, 12 May 2025}
 
+
 # rewriting queries (using CTEs)
-q = AppQuery(<<~SQL)
-  WITH articles(id,title,published_on) AS (
-    values(1, 'Some title', '2024-3-31'),
-          (2, 'Other title', '2024-10-31'),
-          (3, 'Same title?', '2024-3-31'))
+[postgresql]> articles = [
+  [1, "Using my new static site generator", 2.months.ago.to_date],
+  [2, "Let's learn SQL", 1.month.ago.to_date],
+  [3, "Another article", 2.weeks.ago.to_date]
+]
+[postgresql]> q = AppQuery(<<~SQL, cast: {"published_on" => ActiveRecord::Type::Date.new}).render(articles:)
+  WITH articles(id,title,published_on) AS (<%= values(articles) %>)
   select * from articles order by id DESC
 SQL
 
 ## query the articles-CTE
-q.select_all(select: %{select * from articles where id < 2}).to_a
+[postgresql]> q.select_all(select: %{select * from articles where id < 2}).to_a
 
 ## query the end-result (available as the CTE named '_')
-q.select_one(select: %{select * from _ limit 1})
+[postgresql]> q.select_one(select: %{select * from _ limit 1})
 
 ## ERB templating
 # Extract a query from q that can be sorted dynamically:
-q2 = q.with_select("select id,title,published_on::date from articles <%= order_by(order) %>")
-q2.render(order: {"published_on::date": :desc, 'lower(title)': "asc"}).select_all.entries
+[postgresql]> q2 = q.with_select("select id,title,published_on::date from articles <%= order_by(order) %>")
+[postgresql]> q2.render(order: {"published_on::date": :desc, 'lower(title)': "asc"}).select_all.entries
+
 # shows latest articles first, and titles sorted alphabetically
 # for articles published on the same date.
 # order_by raises when it's passed something that would result in just `ORDER BY`:
-q2.render(order: {})
+[postgresql]> q2.render(order: {})
+
 # doing a select using a query that should be rendered, a `AppQuery::UnrenderedQueryError` will be raised:
-q2.select_all.entries
+[postgresql]> q2.select_all.entries
 
 # NOTE you can use both `order` and `@order`: local variables like `order` are required,
 # while instance variables like `@order` are optional.
@@ -249,7 +254,8 @@ AppQuery[:recent_articles].select_all.entries
 # we can provide a different cut off date via binds^1:
 AppQuery[:recent_articles].select_all(binds: [1.month.ago]).entries
 
-1) note that SQLite can deal with unbound parameters, i.e. when no binds are provided it assumes null for $1 and $2 (which our query can deal with).
+1) note that SQLite can deal with unbound parameters, i.e. when no binds are provided it assumes null for
+  $1 and $2 (which our query can deal with).
   For Postgres you would always need to provide 2 values, e.g. `binds: [nil, nil]`.
 ```
 
@@ -567,8 +573,8 @@ query.replace_cte("recent_articles as (select values(1, 'Some article'))")
 ## Compatibility
 
 - 💾 tested with **SQLite** and **PostgreSQL**
-- 🚆 tested with Rails **v6.1**, **v7** and **v8.0**
-- 💎 requires Ruby **>v3.2**  
+- 🚆 tested with Rails v7.x and v8.x (might still work with v6.1, but is no longer included in the test-matrix)
+- 💎 requires Ruby **>=v3.2**  
   Goal is to support [maintained Ruby versions](https://www.ruby-lang.org/en/downloads/branches/).
 
 ## Development
@@ -581,11 +587,14 @@ Using [mise](https://mise.jdx.dev/) for env-vars recommended.
 
 The [console-script](./bin/console) is setup such that it's easy to connect with a database and experiment with the library:
 ```bash
-$ ./bin/console sqlite3::memory:
-$ ./bin/console postgres://localhost:5432/some_db
+$ bin/console sqlite3::memory:
+$ bin/console postgres://localhost:5432/some_db
 
 # more details
-$ ./bin/console -h
+$ bin/console -h
+
+# when needing an appraisal, use bin/run (this ensures signals are handled correctly):
+$ bin/run rails_head console
 ```
 
 ### various

data/lib/app_query/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AppQuery
-  VERSION = "0.3.0"
+  VERSION = "0.4.0.rc1"
 end

data/lib/app_query.rb

@@ -122,7 +122,16 @@ module AppQuery
 
     def render(vars)
       vars ||= {}
-      with_sql(to_erb.result(render_helper(vars).get_binding))
+      helper = render_helper(vars)
+      sql = to_erb.result(helper.get_binding)
+      collected = helper.collected_binds
+
+      with_sql(sql).tap do |q|
+        # Merge collected binds with existing binds (convert array to hash if needed)
+        existing = @binds.is_a?(Hash) ? @binds : {}
+        new_binds = existing.merge(collected)
+        q.instance_variable_set(:@binds, new_binds) if new_binds.any?
+      end
     end
 
     def to_erb
@@ -134,11 +143,84 @@ module AppQuery
       Module.new do
         extend self
 
+        @collected_binds = {}
+        @placeholder_counter = 0
+
         vars.each do |k, v|
           define_method(k) { v }
           instance_variable_set(:"@#{k}", v)
         end
 
+        def collect_bind(value)
+          @placeholder_counter += 1
+          key = :"b#{@placeholder_counter}"
+          @collected_binds[key] = value
+          ":#{key}"
+        end
+
+        attr_reader :collected_binds
+
+        # Examples
+        #   quote("Let's learn Ruby") #=> 'Let''s learn Ruby'
+        def quote(...)
+          ActiveRecord::Base.connection.quote(...)
+        end
+
+        # Examples
+        #   <%= bind(title) %> #=> :b1 (with title added to binds)
+        def bind(value)
+          collect_bind(value)
+        end
+
+        # Examples
+        #   <%= values([[1, "Some video"], [2, "Another video"]]) %>
+        #   #=> VALUES (:b1, :b2), (:b3, :b4) with binds {b1: 1, b2: "Some video", ...}
+        #
+        #   <%= values([{id: 1, title: "Some video"}]) %>
+        #   #=> (id, title) VALUES (:b1, :b2) with binds {b1: 1, b2: "Some video"}
+        #
+        #   <%= values([{title: "A"}, {title: "B", published_on: "2024-01-01"}]) %>
+        #   #=> (title, published_on) VALUES (:b1, NULL), (:b2, :b3)
+        #
+        # Skip column names (e.g. for UNION ALL or CTEs):
+        #   with articles as(
+        #     <%= values([[1, "title"]], skip_columns: true) %>
+        #   )
+        #   #=> with articles as (VALUES (:b1, :b2))
+        #
+        # With block (mix bind() and quote()):
+        #   <%= values(videos) { |v| [bind(v[:id]), quote(v[:title]), 'now()'] } %>
+        #   #=> VALUES (:b1, 'Some title', now()), (:b2, 'Other title', now())
+        def values(coll, skip_columns: false, &block)
+          first = coll.first
+
+          # For hash collections, collect all unique keys
+          if first.is_a?(Hash) && !block
+            all_keys = coll.flat_map(&:keys).uniq
+
+            rows = coll.map do |row|
+              vals = all_keys.map { |k| row.key?(k) ? collect_bind(row[k]) : "NULL" }
+              "(#{vals.join(", ")})"
+            end
+
+            columns = skip_columns ? "" : "(#{all_keys.join(", ")}) "
+            "#{columns}VALUES #{rows.join(",\n")}"
+          else
+            # Arrays or block - current behavior
+            rows = coll.map do |item|
+              vals = if block
+                block.call(item)
+              elsif item.is_a?(Array)
+                item.map { |v| collect_bind(v) }
+              else
+                [collect_bind(item)]
+              end
+              "(#{vals.join(", ")})"
+            end
+            "VALUES #{rows.join(",\n")}"
+          end
+        end
+
         # Examples
         #   <%= order_by({year: :desc, month: :desc}) %>
         #   #=> ORDER BY year DESC, month DESC
@@ -164,22 +246,86 @@ module AppQuery
     end
     private :render_helper
 
-    def select_all(binds: [], select: nil, cast: self.cast)
-      binds = binds.presence || @binds
+    # TODO: have aliases for common casts: select_all(cast: {"today" => :date})
+    def select_all(binds: nil, select: nil, cast: self.cast)
       with_select(select).render({}).then do |aq|
+        # Support both positional (array) and named (hash) binds
+        if binds.is_a?(Array)
+          if @binds.is_a?(Hash) && @binds.any?
+            raise ArgumentError, "Cannot use positional binds (Array) when query has collected named binds from values()/bind() helpers. Use named binds (Hash) instead."
+          end
+          # Positional binds using $1, $2, etc.
+          ActiveRecord::Base.connection.select_all(aq.to_s, name, binds).then do |result|
+            Result.from_ar_result(result, cast)
+          end
+        else
+          # Named binds - merge collected binds with explicitly passed binds
+          merged_binds = (@binds.is_a?(Hash) ? @binds : {}).merge(binds || {})
+          if merged_binds.any?
+            sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
+              Arel.sql(aq.to_s, **merged_binds)
+            else
+              ActiveRecord::Base.sanitize_sql_array([aq.to_s, **merged_binds])
+            end
+            ActiveRecord::Base.connection.select_all(sql, name).then do |result|
+              Result.from_ar_result(result, cast)
+            end
+          else
+            ActiveRecord::Base.connection.select_all(aq.to_s, name).then do |result|
+              Result.from_ar_result(result, cast)
+            end
+          end
+        end
+      end
+    rescue NameError => e
+      # Prevent any subclasses, e.g. NoMethodError
+      raise e unless e.instance_of?(NameError)
+      raise UnrenderedQueryError, "Query is ERB. Use #render before select-ing."
+    end
+
+    def select_one(binds: nil, select: nil, cast: self.cast)
+      select_all(binds:, select:, cast:).first
+    end
+
+    def select_value(binds: nil, select: nil, cast: self.cast)
+      select_one(binds:, select:, cast:)&.values&.first
+    end
+
+    # Examples
+    #   AppQuery(<<~SQL).insert(binds: ["Let's learn SQL!"])
+    #     INSERT INTO videos(title, created_at, updated_at) values($1, now(), now())
+    #   SQL
+    #
+    #   articles = [
+    #     {title: "First article"}
+    #   ].map { it.merge(created_at: Time.current)}
+    #   AppQuery(<<~SQL).render(articles:)
+    #     INSERT INTO articles(title, created_at) <%= values(articles) %>
+    #   SQL
+    def insert(binds: [], returning: nil)
+      # ActiveRecord::Base.connection.insert(sql, name, _pk = nil, _id_value = nil, _sequence_name = nil, binds, returning: nil)
+      if returning && ActiveRecord::VERSION::STRING.to_f < 7.1
+        raise ArgumentError, "The 'returning' option requires Rails 7.1+. Current version: #{ActiveRecord::VERSION::STRING}"
+      end
+
+      binds = binds.presence || @binds
+      render({}).then do |aq|
         if binds.is_a?(Hash)
           sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
             Arel.sql(aq.to_s, **binds)
           else
             ActiveRecord::Base.sanitize_sql_array([aq.to_s, **binds])
           end
-          ActiveRecord::Base.connection.select_all(sql, name).then do |result|
-            Result.from_ar_result(result, cast)
+          if ActiveRecord::VERSION::STRING.to_f >= 7.1
+            ActiveRecord::Base.connection.insert(sql, name, returning:)
+          else
+            ActiveRecord::Base.connection.insert(sql, name)
           end
+        elsif ActiveRecord::VERSION::STRING.to_f >= 7.1
+          # pk is the less flexible returning
+          ActiveRecord::Base.connection.insert(aq.to_s, name, _pk = nil, _id_value = nil, _sequence_name = nil, binds, returning:)
         else
-          ActiveRecord::Base.connection.select_all(aq.to_s, name, binds).then do |result|
-            Result.from_ar_result(result, cast)
-          end
+          ActiveRecord::Base.connection.insert(aq.to_s, name, _pk = nil, _id_value = nil, _sequence_name = nil, binds)
         end
       end
     rescue NameError => e
@@ -188,12 +334,46 @@ module AppQuery
       raise UnrenderedQueryError, "Query is ERB. Use #render before select-ing."
     end
 
-    def select_one(binds: [], select: nil, cast: self.cast)
-      select_all(binds:, select:, cast:).first
+    # Examples:
+    #   AppQuery("UPDATE videos SET title = 'New' WHERE id = :id").update(binds: {id: 1})
+    def update(binds: [])
+      binds = binds.presence || @binds
+      render({}).then do |aq|
+        if binds.is_a?(Hash)
+          sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
+            Arel.sql(aq.to_s, **binds)
+          else
+            ActiveRecord::Base.sanitize_sql_array([aq.to_s, **binds])
+          end
+          ActiveRecord::Base.connection.update(sql, name)
+        else
+          ActiveRecord::Base.connection.update(aq.to_s, name, binds)
+        end
+      end
+    rescue NameError => e
+      raise e unless e.instance_of?(NameError)
+      raise UnrenderedQueryError, "Query is ERB. Use #render before updating."
     end
 
-    def select_value(binds: [], select: nil, cast: self.cast)
-      select_one(binds:, select:, cast:)&.values&.first
+    # Examples:
+    #   AppQuery("DELETE FROM videos WHERE id = :id").delete(binds: {id: 1})
+    def delete(binds: [])
+      binds = binds.presence || @binds
+      render({}).then do |aq|
+        if binds.is_a?(Hash)
+          sql = if ActiveRecord::VERSION::STRING.to_f >= 7.1
+            Arel.sql(aq.to_s, **binds)
+          else
+            ActiveRecord::Base.sanitize_sql_array([aq.to_s, **binds])
+          end
+          ActiveRecord::Base.connection.delete(sql, name)
+        else
+          ActiveRecord::Base.connection.delete(aq.to_s, name, binds)
+        end
+      end
+    rescue NameError => e
+      raise e unless e.instance_of?(NameError)
+      raise UnrenderedQueryError, "Query is ERB. Use #render before deleting."
     end
 
     def tokens

data/rakelib/gem.rake

@@ -0,0 +1,25 @@
+namespace :gem do
+  task "write_version", [:version] do |_task, args|
+    if args[:version]
+      version = args[:version].split("=").last
+      version_file = File.expand_path("../../lib/app_query/version.rb", __FILE__)
+
+      system(<<~CMD, exception: true)
+        ruby -pi -e 'gsub(/VERSION = ".*"/, %{VERSION = "#{version}"})' #{version_file}
+      CMD
+      Bundler.ui.confirm "Version #{version} written to #{version_file}."
+    else
+      Bundler.ui.warn "No version provided, keeping version.rb as is."
+    end
+  end
+
+  desc "Build [version]"
+  task "build", [:version] => %w[write_version] do
+    Rake::Task["build"].invoke
+  end
+
+  desc "Build and push [version] to rubygems"
+  task "release", [:version] => %w[build] do
+    Rake::Task["release:rubygem_push"].invoke
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: appquery
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0.rc1
 platform: ruby
 authors:
 - Gert Goet
@@ -40,6 +40,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".irbrc"
 - ".rspec"
 - ".standard.yml"
 - Appraisals
@@ -61,6 +62,7 @@ files:
 - lib/rails/generators/rspec/templates/query_spec.rb.tt
 - mise.local.toml.example
 - mise.toml
+- rakelib/gem.rake
 - sig/appquery.rbs
 homepage: https://github.com/eval/appquery
 licenses:
@@ -83,7 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: "raw SQL \U0001F966, cooked \U0001F372 or: make working with raw SQL queries
   in Rails convenient by improving their introspection and testability."