Add dataset_run extension, for building SQL using datasets, and runni…

…ng with Database#run

This is mostly useful for easily using placeholders with raw SQL,
which the Dataset#run API does not support.

CHANGELOG

@@ -1,5 +1,7 @@
 === master
 
+* Add dataset_run extension, for building SQL using datasets, and running with Database#run (jeremyevans)
+
 * Switch default connection pool to timed_queue on Ruby 3.2+ (jeremyevans)
 
 === 5.84.0 (2024-09-01)

lib/sequel/extensions/dataset_run.rb

@@ -0,0 +1,41 @@
+# frozen-string-literal: true
+#
+# The dataset_run extension is designed for cases where you want
+# to use dataset methods to build a query, but want to run that
+# query without returning a result.  The most common need would
+# be to easily use placeholders in an SQL string, which Database#run
+# does not support directly.
+#
+# You can load this extension into specific datasets:
+#
+#   ds = DB["GRANT SELECT ON ? TO ?", :table, :user]
+#   ds = ds.extension(:dataset_run)
+#   ds.run
+#
+# Or you can load it into all of a database's datasets, which
+# is probably the desired behavior if you are using this extension:
+#
+#   DB.extension(:dataset_run)
+#   DB["GRANT SELECT ON ? TO ?", :table, :user].run
+#
+# Related module: Sequel::DatasetRun
+
+#
+module Sequel
+  module DatasetRun
+    # Run the dataset's SQL on the database.  Returns NULL.  This is
+    # useful when you want to run SQL without returning a result.
+    #
+    #   DB["GRANT SELECT ON ? TO ?", :table, :user].run
+    #   # GRANT SELECT ON "table" TO "user"
+    def run
+      if server = @opts[:server]
+        db.run(sql, :server=>server)
+      else
+        db.run(sql)
+      end
+    end
+  end
+
+  Dataset.register_extension(:dataset_run, DatasetRun)
+end

spec/extensions/dataset_run_spec.rb

@@ -0,0 +1,15 @@
+require_relative "spec_helper"
+
+describe "dataset_run extension" do
+  it "#run should run the SQL on the database" do
+    db = Sequel.mock
+    db["SQL with ?", "placeholder"].extension(:dataset_run).run.must_be_nil
+    db.sqls.must_equal ["SQL with 'placeholder'"]
+  end
+
+  it "#run should respect current server" do
+    db = Sequel.mock(:servers=>{:a=>{}})
+    db["SQL with ?", "placeholder"].extension(:dataset_run).server(:a).run.must_be_nil
+    db.sqls.must_equal ["SQL with 'placeholder' -- a"]
+  end
+end

www/pages/plugins.html.erb

@@ -807,6 +807,10 @@
 <span class="ul__span">Creates current Time/DateTime objects that are literalized as CURRENT_TIMESTAMP.</span>
 </li>
 <li class="ul__li ul__li--grid">
+<a class="a" href="rdoc-plugins/files/lib/sequel/extensions/dataset_run_rb.html">dataset_run</a>
+<span class="ul__span">Add Dataset#run for building SQL using datasets, but running via Database#run.</span>
+</li>
+<li class="ul__li ul__li--grid">
 <a class="a" href="rdoc-plugins/files/lib/sequel/extensions/dataset_source_alias_rb.html">dataset_source_alias </a>
 <span class="ul__span">Automatically aliases datasets to their source instead of using t1, t2, etc.</span>
 </li>