pg_sql_caller 0.2.3 → 1.0.0

data/lib/pg_sql_caller/model.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/module/delegation'
+
+module PgSqlCaller
+  # Wraps a single ActiveRecord class and runs raw SQL through its connection.
+  # Positional `?` placeholders are bound and sanitized by ActiveRecord, so values
+  # are never interpolated into the SQL string.
+  #
+  #   sql = PgSqlCaller::Model.new(ApplicationRecord)
+  #   sql.select_value('SELECT count(*) FROM users WHERE active = ?', true) # => 42
+  #   sql.select_values('SELECT email FROM users WHERE dept_id = ?', 5)     # => ['a@x', 'b@x']
+  #   sql.select_all('SELECT id, name FROM users')  # => [{ 'id' => 1, 'name' => 'Jo' }, ...]
+  #   sql.transaction { sql.execute('UPDATE users SET active = false') }
+  #
+  # The `*_serialized` variants additionally cast each value back to its Ruby type
+  # using the result's column types (e.g. timestamp -> Time, int[] -> Array), and
+  # key rows by Symbol:
+  #
+  #   sql.select_all_serialized('SELECT id, created_at FROM users')
+  #   # => [{ id: 1, created_at: 2026-06-08 12:00:00 +0000 }, ...]
+  class Model
+    class << self
+      # Define a single connection-backed SQL instance method named +name+.
+      #
+      # @param name [Symbol] the connection method to wrap (e.g. +:select_value+)
+      # @return [Symbol] the name of the defined method
+      def define_sql_method(name)
+        define_method(name) do |sql, *bindings|
+          sql = sanitize_sql_array(sql, *bindings) if bindings.any?
+          connection.public_send(name, sql)
+        end
+      end
+
+      # Define several connection-backed SQL instance methods at once — a thin wrapper
+      # over {.define_sql_method}, kept for backward compatibility.
+      #
+      # @param names [Array<Symbol>] the connection methods to wrap
+      # @return [Array<Symbol>] +names+, unchanged
+      def define_sql_methods(*names)
+        names.each { |name| define_sql_method(name) }
+      end
+    end
+
+    # @!method select_value(sql, *bindings)
+    #   Run +sql+ and return the value of the first column of the first row.
+    #   @param sql [String] SQL statement, optionally containing `?` placeholders
+    #   @param bindings [Array<Object>] values bound, in order, to the `?` placeholders
+    #   @return [Object, nil] the single value, or nil when no row matches
+    define_sql_method :select_value
+
+    # @!method select_values(sql, *bindings)
+    #   Run +sql+ and return the first column of every row.
+    #   @param sql [String] SQL statement, optionally containing `?` placeholders
+    #   @param bindings [Array<Object>] values bound, in order, to the `?` placeholders
+    #   @return [Array<Object>]
+    define_sql_method :select_values
+
+    # @!method execute(sql, *bindings)
+    #   Execute +sql+ (e.g. INSERT/UPDATE/DELETE/DDL) and return the raw adapter result.
+    #   @param sql [String] SQL statement, optionally containing `?` placeholders
+    #   @param bindings [Array<Object>] values bound, in order, to the `?` placeholders
+    #   @return [PG::Result] the raw PostgreSQL result (e.g. +#cmd_tuples+ for affected rows)
+    define_sql_method :execute
+
+    # @!method select_all(sql, *bindings)
+    #   Run +sql+ and return every row.
+    #   @param sql [String] SQL statement, optionally containing `?` placeholders
+    #   @param bindings [Array<Object>] values bound, in order, to the `?` placeholders
+    #   @return [ActiveRecord::Result] rows as String-keyed hashes
+    define_sql_method :select_all
+
+    # @!method select_rows(sql, *bindings)
+    #   Run +sql+ and return rows as arrays of column values (no column names).
+    #   @param sql [String] SQL statement, optionally containing `?` placeholders
+    #   @param bindings [Array<Object>] values bound, in order, to the `?` placeholders
+    #   @return [Array<Array>]
+    define_sql_method :select_rows
+
+    # @return [Class<ActiveRecord::Base>] the ActiveRecord class this instance wraps
+    attr_reader :model_class
+
+    # @!method connection
+    #   The ActiveRecord connection adapter of {#model_class}; every SQL method runs through it.
+    #   @return [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+    delegate :connection, to: :model_class
+
+    # @!method quote_column_name(name)
+    #   Quote a column-name identifier for safe inclusion in SQL (delegated to the
+    #   {#connection}, since the model class itself does not expose it).
+    #   @param name [String, Symbol] the column name to quote
+    #   @return [String] the quoted identifier
+    delegate :quote_column_name, to: :connection
+
+    # @!method quote_table_name(name)
+    #   Quote a table-name identifier for safe inclusion in SQL (delegated to the
+    #   {#connection}, since the model class itself does not expose it).
+    #   @param name [String, Symbol] the table name to quote
+    #   @return [String] the quoted identifier
+    delegate :quote_table_name, to: :connection
+
+    # @param model_class [Class<ActiveRecord::Base>] the class whose connection is used
+    #   to run statements and to sanitize/typecast values
+    def initialize(model_class)
+      @model_class = model_class
+    end
+
+    # Whether a database transaction is currently open on the connection.
+    #
+    # @return [Boolean]
+    def transaction_open?
+      connection.send(:transaction_open?)
+    end
+
+    # Like {#select_all}, but cast each value back to its Ruby type (using the result's
+    # column types) and key every row by Symbol.
+    #
+    # @param sql [String] SQL statement, optionally containing `?` placeholders
+    # @param bindings [Array<Object>] values bound, in order, to the `?` placeholders
+    # @return [Array<Hash{Symbol => Object}>]
+    def select_all_serialized(sql, *bindings)
+      result = select_all(sql, *bindings)
+      result.map do |row|
+        row.to_h { |key, value| [key.to_sym, deserialize_result(result, key, value)] }
+      end
+    end
+
+    # Like {#select_value}, but cast the value back to its Ruby type.
+    #
+    # @param sql [String] SQL statement, optionally containing `?` placeholders
+    # @param bindings [Array<Object>] values bound, in order, to the `?` placeholders
+    # @return [Object, nil] the type-cast value, or nil when no row matches
+    def select_value_serialized(sql, *bindings)
+      result = select_all(sql, *bindings)
+      key = result.first&.keys&.first
+      return if key.nil?
+
+      value = result.first.values.first
+      deserialize_result(result, key, value)
+    end
+
+    # Run +sql+ and return each row as an array of its type-cast column values.
+    #
+    # @param sql [String] SQL statement, optionally containing `?` placeholders
+    # @param bindings [Array<Object>] values bound, in order, to the `?` placeholders
+    # @return [Array<Array>] one inner array per row
+    def select_values_serialized(sql, *bindings)
+      result = select_all(sql, *bindings)
+      result.map do |row|
+        row.map { |key, value| deserialize_result(result, key, value) }
+      end
+    end
+
+    # The next value of the table's `<table_name>_id_seq` sequence (its current
+    # last_value + 1), read without consuming the sequence.
+    #
+    # @param table_name [String, Symbol]
+    # @return [Integer]
+    def next_sequence_value(table_name)
+      sequence_name = quote_table_name("#{table_name}_id_seq")
+      # `sequence_name` is an identifier escaped via quote_table_name (identifiers cannot use `?`
+      # bindings), so the interpolation below is injection-safe.
+      # nosemgrep: pg-sql-caller-interpolated-raw-sql
+      select_value("SELECT last_value FROM #{sequence_name}") + 1
+    end
+
+    # Total on-disk size of the table including indexes and TOAST, in bytes
+    # (PostgreSQL `pg_total_relation_size`).
+    #
+    # @param table_name [String, Symbol]
+    # @return [Integer] size in bytes
+    def table_full_size(table_name)
+      select_value('SELECT pg_total_relation_size(?)', table_name)
+    end
+
+    # On-disk size of the table's main data fork only, in bytes
+    # (PostgreSQL `pg_relation_size`).
+    #
+    # @param table_name [String, Symbol]
+    # @return [Integer] size in bytes
+    def table_data_size(table_name)
+      select_value('SELECT pg_relation_size(?)', table_name)
+    end
+
+    # Run +sql+ and return the first row as an array of column values.
+    #
+    # @param sql [String] SQL statement, optionally containing `?` placeholders
+    # @param bindings [Array<Object>] values bound, in order, to the `?` placeholders
+    # @return [Array, nil] the first row, or nil when no row matches
+    def select_row(sql, *bindings)
+      select_rows(sql, *bindings)[0]
+    end
+
+    # Run the given block inside a database transaction, committing on success and
+    # rolling back if it raises.
+    #
+    # @yield executes within the open transaction
+    # @return [Object] the block's return value
+    # @raise [ArgumentError] if no block is given
+    def transaction(&)
+      raise ArgumentError, 'block must be given' unless block_given?
+
+      connection.transaction(&)
+    end
+
+    # Run `EXPLAIN ANALYZE` for +sql+ and return the query plan as text.
+    #
+    # @param sql [String] the statement to analyze
+    # @return [String] the plan, one line per row, prefixed with a +QUERY_PLAN+ header
+    def explain_analyze(sql)
+      # `sql` is the statement to analyze; the caller owns the full SQL by contract (like #execute),
+      # so there is no boundary to bind across.
+      # nosemgrep: pg-sql-caller-interpolated-raw-sql
+      result = select_values("EXPLAIN ANALYZE #{sql}")
+      ['QUERY_PLAN', *result].join("\n")
+    end
+
+    # Encode a Ruby array into a PostgreSQL array literal for the given attribute type,
+    # ready to bind as a single `?` value.
+    #
+    # @param values [Array] the Ruby values to encode
+    # @param type [Symbol] an ActiveRecord attribute type (e.g. +:integer+, +:string+, +:datetime+)
+    # @return [String] a PostgreSQL array literal, e.g. +"{1,2,3}"+
+    def typecast_array(values, type:)
+      type = ActiveRecord::Type.lookup(type, array: true)
+      data = type.serialize(values)
+      data.encoder.encode(data.values)
+    end
+
+    # Interpolate `?` placeholders in +sql+ with +bindings+ through ActiveRecord's
+    # sanitizer (values are quoted/escaped, never raw-interpolated).
+    #
+    # @param sql [String] SQL containing `?` placeholders
+    # @param bindings [Array<Object>] values bound, in order, to the placeholders
+    # @return [String] the safe, ready-to-run SQL
+    def sanitize_sql_array(sql, *bindings)
+      model_class.send :sanitize_sql_array, bindings.unshift(sql)
+    end
+
+    # @return [String] the name of the currently connected database (`current_database()`)
+    def current_database
+      select_value('SELECT current_database();')
+    end
+
+    # Capture PostgreSQL NOTICE output (e.g. from +RAISE NOTICE+) emitted while the block
+    # runs, passing each message to +callback+. Lowers +client_min_messages+ to +notice+
+    # for the duration (see {#with_min_messages}) and restores the previous notice
+    # processor afterward.
+    #
+    #   sql.with_notice_processor(->(msg) { logger.info(msg) }) do
+    #     sql.execute("DO $$ BEGIN RAISE NOTICE 'hi'; END $$")
+    #   end
+    #
+    # @param callback [#call] invoked with each notice message (a chomped String)
+    # @yield runs with the notice processor installed
+    # @return [Object] the block's return value
+    def with_notice_processor(callback)
+      with_min_messages('notice') do
+        old_processor = connection.raw_connection.set_notice_processor { |result| callback.call(result.to_s.chomp) }
+        yield
+      ensure
+        connection.raw_connection.set_notice_processor(&old_processor)
+      end
+    end
+
+    # Temporarily set the connection's +client_min_messages+ to +level+ for the duration
+    # of the block, restoring the previous value afterward.
+    #
+    # @param level [String] one of: debug5, debug4, debug3, debug2, debug1, log, notice, warning, error
+    # @yield runs with the level applied
+    # @return [Object] the block's return value
+    def with_min_messages(level)
+      old_level = select_value('SHOW client_min_messages')
+      execute('SET client_min_messages TO ?', level)
+      yield
+    ensure
+      execute('SET client_min_messages TO ?', old_level) unless old_level.nil?
+    end
+
+    # Quote and escape a value as a SQL literal, safe to inline into a statement.
+    #
+    # @param value [Object] the value to quote (e.g. String, Numeric, nil, Time)
+    # @return [String] the quoted SQL literal (e.g. +"'O''Brien'"+)
+    def quote_value(value)
+      connection.quote(value)
+    end
+
+    private
+
+    # Cast a raw result value back to its Ruby type using the result set's column types.
+    #
+    # @param result [ActiveRecord::Result] the result the value came from (carries column types)
+    # @param column_name [String] the column the value belongs to
+    # @param raw_value [Object] the raw value as returned by the adapter
+    # @return [Object] the type-cast value, or +raw_value+ unchanged when the column type is unknown
+    def deserialize_result(result, column_name, raw_value)
+      column_type = result.column_types[column_name]
+      return raw_value if column_type.nil?
+
+      column_type.deserialize(raw_value)
+    end
+  end
+end

data/lib/pg_sql_caller/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgSqlCaller
-  VERSION = '0.2.3'
+  VERSION = '1.0.0'
 end

data/lib/pg_sql_caller.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require 'pg_sql_caller/version'
+require 'pg_sql_caller/model'
 require 'pg_sql_caller/base'
+require 'pg_sql_caller/bulk_update'
 
 module PgSqlCaller
   # Your code goes here...

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pg_sql_caller
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 1.0.0
 platform: ruby
 authors:
 - Denis Talakevich
-autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2025-02-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,50 +15,56 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '7.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-description: Postgresql Sql Caller for ActiveRecord.
+        version: '7.1'
+description: 'PgSqlCaller is a small, focused wrapper for running raw SQL against
+  PostgreSQL through ActiveRecord. It exposes a stable, documented API on an ActiveRecord-backed
+  class you name, covering the queries the query builder makes awkward: single-scalar
+  and single-column SELECTs, raw rows, ActiveRecord::Result reads, and type-cast (serialized)
+  variants that decode PostgreSQL arrays and custom column types into Ruby objects.
+  Every ? placeholder is bound and escaped through the ActiveRecord sanitizer, so
+  statements stay injection-safe with no manual quoting. On top of that it adds PostgreSQL-specific
+  helpers — non-consuming sequence peeking, table and relation sizes, EXPLAIN ANALYZE,
+  NOTICE capture, and quoting/sanitizing utilities — plus a fast, injection-safe bulk
+  update that partially updates many existing rows in a single UPDATE ... FROM unnest(...)
+  statement and round-trip. The reader API is extensible via define_sql_method, and
+  the gem runs on Ruby 3.2+ with Rails 7.1 through 8.1.'
 email:
 - senid231@gmail.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- CHANGELOG.md
+- README.md
 files:
-- ".gitignore"
-- ".rspec"
-- ".rubocop.yml"
-- ".travis.yml"
-- CODE_OF_CONDUCT.md
-- Gemfile
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- bin/console
-- bin/setup
 - lib/pg_sql_caller.rb
 - lib/pg_sql_caller/base.rb
+- lib/pg_sql_caller/bulk_update.rb
+- lib/pg_sql_caller/model.rb
 - lib/pg_sql_caller/version.rb
-- sql_caller.gemspec
 homepage: https://github.com/didww/pg_sql_caller
 licenses:
 - MIT
@@ -67,7 +72,6 @@ metadata:
   homepage_uri: https://github.com/didww/pg_sql_caller
   source_code_uri: https://github.com/didww/pg_sql_caller
   changelog_uri: https://github.com/didww/pg_sql_caller
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -75,15 +79,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Postgresql Sql Caller for ActiveRecord
 test_files: []

data/.gitignore

@@ -1,14 +0,0 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-/pkg/
-/spec/reports/
-/tmp/
-
-# rspec failure tracking
-.rspec_status
-
-/Gemfile.lock
-/spec/config/database.yml

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,71 +0,0 @@
-AllCops:
-  DisplayCopNames: true
-  TargetRubyVersion: 2.5
-  Exclude:
-    - vendor/**/*
-    - tmp/**/*
-
-Layout/LineLength:
-  Max: 180
-
-Style/SymbolArray:
-  EnforcedStyle: brackets
-
-Style/Lambda:
-  EnforcedStyle: literal
-
-Naming/MethodParameterName:
-  AllowedNames:
-    - id
-
-Style/HashEachMethods:
-  Enabled: true
-
-Style/HashTransformKeys:
-  Enabled: true
-
-Style/HashTransformValues:
-  Enabled: true
-
-Style/Documentation:
-  Enabled: false
-
-Metrics/PerceivedComplexity:
-  Enabled: false
-
-Metrics/MethodLength:
-  Enabled: false
-
-Metrics/AbcSize:
-  Enabled: false
-
-Metrics/ModuleLength:
-  Enabled: false
-
-Metrics/BlockLength:
-  Enabled: false
-
-Metrics/ClassLength:
-  Enabled: false
-
-Metrics/CyclomaticComplexity:
-  Enabled: false
-
-Layout/MultilineOperationIndentation:
-  Enabled: false
-
-Layout/FirstHashElementIndentation:
-  Enabled: false
-
-Layout/FirstArrayElementIndentation:
-  Enabled: false
-
-Layout/FirstArgumentIndentation:
-  Enabled: false
-
-Layout/ClosingParenthesisIndentation:
-  Enabled: false
-
-Layout/ArgumentAlignment:
-  Enabled: false
-

data/.travis.yml

@@ -1,12 +0,0 @@
----
-sudo: false
-language: ruby
-cache: bundler
-services:
-  - postgresql
-rvm:
-  - 2.5.7
-before_install: gem install bundler -v 2.1.4
-before_script:
-  - psql -c 'CREATE DATABASE pg_sql_caller_test;' -U postgres
-  - cp -v spec/config/database.travis.yml spec/config/database.yml

data/CODE_OF_CONDUCT.md

@@ -1,74 +0,0 @@
-# Contributor Covenant Code of Conduct
-
-## Our Pledge
-
-In the interest of fostering an open and welcoming environment, we as
-contributors and maintainers pledge to making participation in our project and
-our community a harassment-free experience for everyone, regardless of age, body
-size, disability, ethnicity, gender identity and expression, level of experience,
-nationality, personal appearance, race, religion, or sexual identity and
-orientation.
-
-## Our Standards
-
-Examples of behavior that contributes to creating a positive environment
-include:
-
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
-
-Examples of unacceptable behavior by participants include:
-
-* The use of sexualized language or imagery and unwelcome sexual attention or
-advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
-  address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
-  professional setting
-
-## Our Responsibilities
-
-Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
-
-Project maintainers have the right and responsibility to remove, edit, or
-reject comments, commits, code, wiki edits, issues, and other contributions
-that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
-threatening, offensive, or harmful.
-
-## Scope
-
-This Code of Conduct applies both within project spaces and in public spaces
-when an individual is representing the project or its community. Examples of
-representing a project or community include using an official project e-mail
-address, posting via an official social media account, or acting as an appointed
-representative at an online or offline event. Representation of a project may be
-further defined and clarified by project maintainers.
-
-## Enforcement
-
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at senid231@gmail.com. All
-complaints will be reviewed and investigated and will result in a response that
-is deemed necessary and appropriate to the circumstances. The project team is
-obligated to maintain confidentiality with regard to the reporter of an incident.
-Further details of specific enforcement policies may be posted separately.
-
-Project maintainers who do not follow or enforce the Code of Conduct in good
-faith may face temporary or permanent repercussions as determined by other
-members of the project's leadership.
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at [https://contributor-covenant.org/version/1/4][version]
-
-[homepage]: https://contributor-covenant.org
-[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-source 'https://rubygems.org'
-
-# Specify your gem's dependencies in pg_sql_caller.gemspec
-gemspec
-
-gem 'database_cleaner'
-gem 'pg'
-gem 'rake', '~> 12.0'
-gem 'rspec', '~> 3.0'
-gem 'rubocop', '~> 0.80.1'

data/Rakefile

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'rubocop/rake_task'
-
-RSpec::Core::RakeTask.new(:spec)
-RuboCop::RakeTask.new(:rubocop)
-
-task default: [:rubocop, :spec]

data/bin/console

@@ -1,15 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-require 'bundler/setup'
-require 'pg_sql_caller'
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require 'irb'
-IRB.start(__FILE__)

data/bin/setup

@@ -1,8 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-IFS=$'\n\t'
-set -vx
-
-bundle install
-
-# Do any other automated setup that you need to do here