rails_psql_jsonb 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 20375e29b24d21edfb8eb5a7160048ec5bbc3c214d9db32636df59c8cf3353ba
+  data.tar.gz: c3d5751129d850e27f98108280a660e63f3e87c8f38d6b7db1abfe16dd5adb8f
+SHA512:
+  metadata.gz: 6ad4396fecd958c4bfffd7703052476ccbde5f9ae1502da302d51ca33bd213b6e24c76a4146cb4a2f80309d25ac62d5dbcc697196688d2c224c93e71d00b23d9
+  data.tar.gz: a10648261f1625b72bd30562cdc2bab15b4f53dad0b305c8662eecbfec9cbe719b11b4d47687e4b27104d101caf49d49921d3eb0464e1b41990b854550204494

data/.rspec

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

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+## [Unreleased]
+
+## [0.2.0] - 2026-04-07
+
+### Fixed
+- Removed debug `puts` statement left in `jsonb_update!`
+- Fixed `jsonb_update!` and `jsonb_update_columns` mutating the caller's input hash
+- Fixed `self.name.constantize` in querying class methods (broke on anonymous models)
+- Fixed `NoOrderKey` error initializer accepting an unused `attribute:` keyword argument
+- Fixed `ReadOnlyAttribute` raise syntax (`ReadOnlyAttribute(...)` → `ReadOnlyAttribute.new(...)`)
+
+### Added
+- **Key existence queries**: `jsonb_where_exists`, `jsonb_where_exists_any`, `jsonb_where_exists_all` using PostgreSQL `?`, `?|`, `?&` operators
+- **Atomic key deletion**: `jsonb_delete_key` / `jsonb_delete_key!` / `jsonb_delete_key_columns` via PostgreSQL `#-`
+- **Atomic array append**: `jsonb_array_append` — initializes missing key to `[]` automatically
+- **Atomic array remove**: `jsonb_array_remove` — removes all occurrences of a value
+- **Atomic numeric increment**: `jsonb_increment` — initializes missing key to `0` automatically
+- **Batch update**: `jsonb_batch_update` — wraps multiple `jsonb_update!` calls in a transaction
+- **GIN index helper**: `jsonb_gin_index_sql` — returns the SQL to create an optimal GIN index
+
+### Improved
+- Multi-key paths use `#>`/`#>>` path operators instead of chained `->` (more idiomatic, better index usage)
+- Numeric comparisons use `->>` text extraction before `::float` cast
+- `jsonb_order` now emits explicit `NULLS LAST` (asc) / `NULLS FIRST` (desc)
+- Trimmed `quoting.rb` to only the methods actually used; fixed `default_timezone` reference
+- Added test isolation via `database_cleaner-active_record`
+
+## [0.1.0] - 2024-06-20
+
+- Initial release

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in rails_psql_jsonb.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,81 @@
+PATH
+  remote: .
+  specs:
+    rails_psql_jsonb (0.2.0)
+      activerecord (>= 6.1)
+      activesupport (>= 6.1)
+      pg (>= 1.5.6)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (8.1.3)
+      activesupport (= 8.1.3)
+    activerecord (8.1.3)
+      activemodel (= 8.1.3)
+      activesupport (= 8.1.3)
+      timeout (>= 0.4.0)
+    activesupport (8.1.3)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    bigdecimal (4.1.1)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    database_cleaner-active_record (2.2.2)
+      activerecord (>= 5.a)
+      database_cleaner-core (~> 2.0)
+    database_cleaner-core (2.0.1)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    json (2.19.3)
+    logger (1.7.0)
+    minitest (6.0.3)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    pg (1.6.3-arm64-darwin)
+    prism (1.9.0)
+    rake (13.3.1)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    securerandom (0.4.1)
+    timeout (0.6.1)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.1.1)
+
+PLATFORMS
+  arm64-darwin-23
+  arm64-darwin-24
+
+DEPENDENCIES
+  database_cleaner-active_record (~> 2.1)
+  rails_psql_jsonb!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.4.13

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 bubiche
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,154 @@
+# RailsPsqlJsonb
+
+Helpers for querying and atomically updating PostgreSQL JSONB columns in Rails ActiveRecord.
+
+Inspired by https://github.com/madeintandem/jsonb_accessor and https://github.com/antoinemacia/atomic_json
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "rails_psql_jsonb"
+```
+
+Include in your model:
+
+```ruby
+class Friend < ApplicationRecord
+  include RailsPsqlJsonb
+end
+```
+
+## Usage
+
+### Querying
+
+**Contains / equality / numeric comparison**
+
+```ruby
+# @> contains
+Friend.jsonb_where(column_name: "props", operator: "contains", value: { age: 90 })
+
+# Numeric operators: gt, lt, gte, lte, eq  (also accept >, <, >=, <=, =)
+Friend.jsonb_where(column_name: "props", json_keys: ["age"], operator: "gt", value: 20)
+
+# Nested key path
+Friend.jsonb_where(column_name: "props", json_keys: ["address", "city"], operator: "eq", value: "Berlin")
+
+# Exclusion
+Friend.jsonb_where_not(column_name: "props", operator: "contains", value: { active: true })
+```
+
+**Key existence**
+
+```ruby
+# Records where the key exists
+Friend.jsonb_where_exists(column_name: "props", key: "age")
+
+# Records where the key is absent
+Friend.jsonb_where_exists(column_name: "props", key: "age", exclude: true)
+
+# Records having any of the given keys
+Friend.jsonb_where_exists_any(column_name: "props", keys: ["age", "score"])
+
+# Records having all of the given keys
+Friend.jsonb_where_exists_all(column_name: "props", keys: ["age", "name"])
+
+# Scope check to a nested object
+Friend.jsonb_where_exists(column_name: "props", key: "city", json_keys: ["address"])
+```
+
+**Ordering**
+
+```ruby
+Friend.all.jsonb_order(column_name: "props", json_keys: ["age"], direction: "desc")
+# NULLs sort first for desc, last for asc
+```
+
+### Updating
+
+All update methods are atomic at the database level using `jsonb_set`.
+
+**Set / merge keys**
+
+```ruby
+# Merges new keys without overwriting unrelated keys
+friend.jsonb_update!({ "props" => { "age" => 31 } })
+friend.jsonb_update!({ "props" => { "age" => 31, "score" => 100 } })
+
+# Without touching updated_at
+friend.jsonb_update_columns({ "props" => { "age" => 31 } })
+
+# Without running validations
+friend.jsonb_update({ "props" => { "age" => 31 } })
+```
+
+**Delete a key**
+
+```ruby
+friend.jsonb_delete_key("props", "age")                    # removes props['age']
+friend.jsonb_delete_key("props", "address", "city")        # removes props['address']['city']
+friend.jsonb_delete_key_columns("props", "age")            # no updated_at touch
+```
+
+**Array operations**
+
+```ruby
+# Append — initializes to [value] if the key doesn't exist
+friend.jsonb_array_append("props", ["tags"], "ruby")
+
+# Remove all occurrences — returns [] if the last element is removed
+friend.jsonb_array_remove("props", ["tags"], "ruby")
+```
+
+**Numeric increment / decrement**
+
+```ruby
+friend.jsonb_increment("props", ["score"])        # +1 (default)
+friend.jsonb_increment("props", ["score"], 5)     # +5
+friend.jsonb_increment("props", ["score"], -1)    # -1 (decrement)
+# Missing key is initialized to 0 before applying the delta
+```
+
+**Batch update**
+
+```ruby
+# Wraps multiple jsonb_update! calls in a single transaction
+Friend.jsonb_batch_update([
+  [friend_a, { "props" => { "score" => 10 } }],
+  [friend_b, { "props" => { "score" => 20 } }],
+])
+```
+
+### GIN index recommendation
+
+For best query performance, create a GIN index on your JSONB column. Use `jsonb_gin_index_sql` to get the correct SQL for your migration:
+
+```ruby
+# In a migration:
+execute Friend.jsonb_gin_index_sql(column_name: "props")
+# => CREATE INDEX ON "friends" USING GIN ("props" jsonb_path_ops);
+
+# jsonb_path_ops  — smaller index, faster for @> (contains) queries (default)
+# jsonb_ops       — also supports ?, ?|, ?& key-existence operators
+execute Friend.jsonb_gin_index_sql(column_name: "props", using: :jsonb_ops)
+```
+
+## Development
+
+To run tests you must have [PostgreSQL](https://www.postgresql.org/) installed and create the test database:
+
+```sh
+PGPASSWORD=postgres createdb -U postgres -h localhost rails_psql_jsonb_test
+```
+
+Tests assume PostgreSQL is running on `localhost:5432` with username `postgres` and password `postgres`.
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt.
+
+To release a new version, update `version.rb`, then run `bundle exec rake release` to create a git tag, push commits and the tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/rails_psql_jsonb/atomic_update.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+# Inspired by https://github.com/antoinemacia/atomic_json
+
+require_relative "query_helpers"
+
+module RailsPsqlJsonb
+  module AtomicUpdate
+    extend ActiveSupport::Concern
+
+    def jsonb_update(input)
+      update_query = build_update_query(input.deep_dup, touch: true)
+      run_callbacks(:save) do
+        self.class.connection.exec_update(update_query)
+        reload.validate
+      end
+    end
+
+    def jsonb_update!(input)
+      update_query = build_update_query(input.deep_dup, touch: true)
+      run_callbacks(:save) do
+        self.class.connection.exec_update(update_query)
+        reload.validate!
+      end
+    end
+
+    def jsonb_update_columns(input)
+      update_query = build_update_query(input.deep_dup, touch: false)
+      self.class.connection.exec_update(update_query)
+    end
+
+    # Atomically removes a key (or nested key path) from a JSONB column.
+    # Uses PostgreSQL's #- operator which is safe when the path doesn't exist.
+    #
+    # Examples:
+    #   record.jsonb_delete_key("props", "age")             # removes props['age']
+    #   record.jsonb_delete_key("props", "nested", "inner") # removes props['nested']['inner']
+    def jsonb_delete_key(column_name, *key_path)
+      validate_key_path!(key_path)
+      col = validate_record_and_column!(column_name)
+      exec_delete_key(col, key_path, touch: true)
+      reload
+    end
+
+    def jsonb_delete_key!(column_name, *key_path)
+      jsonb_delete_key(column_name, *key_path)
+      validate!
+      self
+    end
+
+    def jsonb_delete_key_columns(column_name, *key_path)
+      validate_key_path!(key_path)
+      col = validate_record_and_column!(column_name)
+      exec_delete_key(col, key_path, touch: false)
+      reload
+    end
+
+    # Atomically appends a value to a JSONB array at the given key path.
+    # Initializes to [value] if the key doesn't exist yet.
+    #
+    # Example:
+    #   record.jsonb_array_append("props", ["tags"], "ruby")
+    def jsonb_array_append(column_name, key_path, value)
+      col      = validate_record_and_column!(column_name)
+      key_path = Array(key_path)
+      validate_key_path!(key_path)
+
+      pg_path    = "{#{key_path.map(&:to_s).join(",")}}"
+      quoted_col = RailsPsqlJsonb::QueryHelpers.quote_column_name(col)
+      quoted_tbl = RailsPsqlJsonb::QueryHelpers.quote_table_name(self.class.table_name)
+      quoted_val = RailsPsqlJsonb::QueryHelpers.quote(value.to_json)
+
+      sql = <<~SQL
+        UPDATE #{quoted_tbl}
+        SET #{quoted_col} = jsonb_set(
+          #{quoted_col}::jsonb,
+          '#{pg_path}',
+          COALESCE(#{quoted_col} #> '#{pg_path}', '[]'::jsonb) || jsonb_build_array(#{quoted_val}::jsonb)
+        )#{optional_touch_sql}
+        WHERE id = #{RailsPsqlJsonb::QueryHelpers.quote(id)};
+      SQL
+      self.class.connection.exec_update(sql)
+      reload
+    end
+
+    # Atomically removes all occurrences of value from a JSONB array at the given key path.
+    # Returns [] if all elements are removed or the key doesn't exist.
+    #
+    # Example:
+    #   record.jsonb_array_remove("props", ["tags"], "ruby")
+    def jsonb_array_remove(column_name, key_path, value)
+      col      = validate_record_and_column!(column_name)
+      key_path = Array(key_path)
+      validate_key_path!(key_path)
+
+      pg_path    = "{#{key_path.map(&:to_s).join(",")}}"
+      quoted_col = RailsPsqlJsonb::QueryHelpers.quote_column_name(col)
+      quoted_tbl = RailsPsqlJsonb::QueryHelpers.quote_table_name(self.class.table_name)
+      quoted_val = RailsPsqlJsonb::QueryHelpers.quote(value.to_json)
+
+      sql = <<~SQL
+        UPDATE #{quoted_tbl}
+        SET #{quoted_col} = jsonb_set(
+          #{quoted_col}::jsonb,
+          '#{pg_path}',
+          COALESCE(
+            (SELECT jsonb_agg(e)
+             FROM jsonb_array_elements(#{quoted_col} #> '#{pg_path}') AS e
+             WHERE e <> #{quoted_val}::jsonb),
+            '[]'::jsonb
+          )
+        )#{optional_touch_sql}
+        WHERE id = #{RailsPsqlJsonb::QueryHelpers.quote(id)};
+      SQL
+      self.class.connection.exec_update(sql)
+      reload
+    end
+
+    # Atomically increments (or decrements with negative delta) a numeric JSONB value.
+    # Initializes missing keys to 0 before applying the delta.
+    #
+    # Example:
+    #   record.jsonb_increment("props", ["score"], 5)
+    #   record.jsonb_increment("props", ["score"], -1)  # decrement
+    def jsonb_increment(column_name, key_path, delta = 1)
+      raise TypeError, "delta must be Numeric, got #{delta.class}" unless delta.is_a?(Numeric)
+      col      = validate_record_and_column!(column_name)
+      key_path = Array(key_path)
+      validate_key_path!(key_path)
+
+      pg_path    = "{#{key_path.map(&:to_s).join(",")}}"
+      quoted_col = RailsPsqlJsonb::QueryHelpers.quote_column_name(col)
+      quoted_tbl = RailsPsqlJsonb::QueryHelpers.quote_table_name(self.class.table_name)
+
+      sql = <<~SQL
+        UPDATE #{quoted_tbl}
+        SET #{quoted_col} = jsonb_set(
+          #{quoted_col}::jsonb,
+          '#{pg_path}',
+          to_jsonb(COALESCE((#{quoted_col} #>> '#{pg_path}')::numeric, 0) + #{RailsPsqlJsonb::QueryHelpers.quote(delta)})
+        )#{optional_touch_sql}
+        WHERE id = #{RailsPsqlJsonb::QueryHelpers.quote(id)};
+      SQL
+      self.class.connection.exec_update(sql)
+      reload
+    end
+
+    private
+
+    def validate_key_path!(key_path)
+      raise ArgumentError, "key_path must not be empty" if key_path.empty?
+    end
+
+    # Returns ", updated_at = '...'" when the model has an updated_at column, else "".
+    # Pass touch: false to suppress the timestamp even when the column exists.
+    def optional_touch_sql(touch: true)
+      return "" unless touch && has_attribute?(:updated_at)
+      ", #{timestamp_update_string}"
+    end
+
+    # Validates that the record is persisted and the column is a JSONB column.
+    # Returns the resolved (alias-expanded) column name.
+    def validate_record_and_column!(column_name)
+      raise RailsPsqlJsonb::Errors::ActiveRecordError, "cannot update a new record" if new_record?
+      raise RailsPsqlJsonb::Errors::ActiveRecordError, "cannot update a destroyed record" if destroyed?
+      col = RailsPsqlJsonb::QueryHelpers.db_column_name(self.class, column_name.to_s)
+      RailsPsqlJsonb::QueryHelpers.validate_column_name!(self.class, col)
+      col
+    end
+
+    def exec_delete_key(col, key_path, touch:)
+      quoted_col = RailsPsqlJsonb::QueryHelpers.quote_column_name(col)
+      quoted_tbl = RailsPsqlJsonb::QueryHelpers.quote_table_name(self.class.table_name)
+      path_array = key_path.map { |k| RailsPsqlJsonb::QueryHelpers.quote(k.to_s) }.join(", ")
+      sql = "UPDATE #{quoted_tbl} SET #{quoted_col} = #{quoted_col} #- ARRAY[#{path_array}]#{optional_touch_sql(touch: touch)} WHERE id = #{RailsPsqlJsonb::QueryHelpers.quote(id)};"
+      self.class.connection.exec_update(sql)
+    end
+
+    def build_update_query(input, touch: false)
+      RailsPsqlJsonb::QueryHelpers.validate_atomic_update!(self, input)
+
+      <<~SQL
+        UPDATE #{RailsPsqlJsonb::QueryHelpers.quote_table_name(self.class.table_name)}
+        SET #{build_set_subquery(input, touch)}
+        WHERE id = #{RailsPsqlJsonb::QueryHelpers.quote(self.id)};
+      SQL
+    end
+
+    def build_set_subquery(attributes, touch)
+      updates = json_updates_agg(attributes)
+      updates << timestamp_update_string if touch && has_attribute?(:updated_at)
+      updates.join(',')
+    end
+
+    def json_updates_agg(attributes)
+      attributes.map do |column, payload|
+        "#{RailsPsqlJsonb::QueryHelpers.quote_column_name(column)} = #{json_deep_merge(column, payload)}"
+      end
+    end
+
+    def timestamp_update_string
+      "#{RailsPsqlJsonb::QueryHelpers.quote_column_name(:updated_at)} = #{RailsPsqlJsonb::QueryHelpers.quote(Time.now)}"
+    end
+
+    def json_deep_merge(target, payload)
+      loop do
+        keys, value = traverse_payload(Hash[*payload.shift])
+        target = jsonb_set_query_string(target, keys, value)
+        break target if payload.empty?
+      end
+    end
+
+    # Returns [key_path, leaf_value] by walking nested single-key hashes.
+    def traverse_payload(key_value_pair, keys = [])
+      loop do
+        key, val = key_value_pair.flatten
+        keys << key.to_s
+        break [keys, val] unless single_value_hash?(val)
+        key_value_pair = val
+      end
+    end
+
+    def jsonb_set_query_string(target, keys, value)
+      <<~EOF
+        jsonb_set(
+          #{target}::jsonb,
+          #{RailsPsqlJsonb::QueryHelpers.quote_jsonb_keys(keys)},
+          #{multi_value_hash?(value) ? RailsPsqlJsonb::QueryHelpers.concatenation(target, keys, value) : RailsPsqlJsonb::QueryHelpers.quote_jsonb_value(value)}
+        )::jsonb
+      EOF
+    end
+
+    def multi_value_hash?(value)
+      value.is_a?(Hash) && value.keys.count > 1
+    end
+
+    def single_value_hash?(value)
+      value.is_a?(Hash) && value.keys.count == 1
+    end
+  end
+end

data/lib/rails_psql_jsonb/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RailsPsqlJsonb
+  module Errors
+    class InvalidColumnName < StandardError
+      def initialize(table_name:, column_name:)
+        super("Table #{table_name} does not have jsonb column name #{column_name}")
+      end
+    end
+
+    class InvalidOperator < StandardError
+      def initialize(value:)
+        super("Invalid operator #{value}")
+      end
+    end
+
+    class InvalidOrder < StandardError
+      def initialize(value:)
+        super("only `asc` or `desc` can be used for ordering, got: #{value}")
+      end
+    end
+
+    class ReadOnlyAttribute < StandardError
+      def initialize(attribute:)
+        super("#{attribute} is marked as readonly")
+      end
+    end
+
+    class NoOrderKey < StandardError
+      def initialize
+        super("order json_keys must be a non-empty array")
+      end
+    end
+
+    class ActiveRecordError < StandardError
+    end
+  end
+end

data/lib/rails_psql_jsonb/query_helpers.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "quoting"
+require "json"
+
+module RailsPsqlJsonb
+  module QueryHelpers
+    OPERATORS_MAP = {
+      :gt => ">",
+      "gt" => ">",
+      ">" => ">",
+      :> => ">",
+      :lt => "<",
+      "lt" => "<",
+      "<" => "<",
+      :< => "<",
+      :gte => ">=",
+      "gte" => ">=",
+      :>= => ">=",
+      ">=" => ">=",
+      :lte => "<=",
+      "lte" => "<=",
+      :<= => "<=",
+      "<=" => "<=",
+      :eq => "=",
+      "eq" => "=",
+      :"=" => "=",
+      "=" => "=",
+      :contains => "@>",
+      "contains" => "@>",
+      :"@>" => "@>",
+      "@>" => "@>",
+      :exists => "?",
+      "exists" => "?",
+      :"?" => "?",
+      "?" => "?",
+      :exists_any => "?|",
+      "exists_any" => "?|",
+      :"?|" => "?|",
+      "?|" => "?|",
+      :exists_all => "?&",
+      "exists_all" => "?&",
+      :"?&" => "?&",
+      "?&" => "?&"
+    }.freeze
+
+    def self.numeric_operator?(query_operator)
+      [">", "<", ">=", "<="].include?(query_operator)
+    end
+
+    def self.existence_operator?(query_operator)
+      ["?", "?|", "?&"].include?(query_operator)
+    end
+
+    def self.validate_operator!(operator)
+      raise RailsPsqlJsonb::Errors::InvalidOperator.new(value: operator) if !OPERATORS_MAP.key?(operator)
+    end
+
+    def self.validate_column_name!(ar_model, column_name)
+      raise RailsPsqlJsonb::Errors::InvalidColumnName.new(table_name: ar_model.table_name, column_name:) if !ar_model.column_names.include?(column_name.to_s) || ar_model.type_for_attribute(column_name).type != :jsonb
+    end
+
+    def self.validate_ordering!(value)
+      raise RailsPsqlJsonb::Errors::InvalidOrder.new(value: value) if ![:asc, :desc, "asc", "desc"].include?(value)
+    end
+
+    def self.validate_json_keys_for_ordering!(json_keys)
+      raise RailsPsqlJsonb::Errors::NoOrderKey unless json_keys.is_a?(Array) && !json_keys.empty?
+    end
+
+    def self.validate_atomic_update!(record, input)
+      raise RailsPsqlJsonb::Errors::ActiveRecordError, "cannot update a new record" if record.new_record?
+      raise RailsPsqlJsonb::Errors::ActiveRecordError, "cannot update a destroyed record" if record.destroyed?
+
+      raise TypeError, "Atomic update input must be a hash" unless input.is_a?(Hash)
+
+      input.each do |key, payload|
+        raise RailsPsqlJsonb::Errors::ReadOnlyAttribute.new(attribute: key) if record.class.readonly_attributes.include?(key.to_s)
+
+        validate_column_name!(record.class, db_column_name(record.class, key))
+
+        raise ArgumentError, "payload for column #{key} must not be empty" if payload.is_a?(Hash) && payload.empty?
+      end
+    end
+
+    def self.db_column_name(ar_model, column_name)
+      ar_model.attribute_alias?(column_name) ? ar_model.attribute_alias(column_name) : column_name
+    end
+
+    def self.quote(value)
+      RailsPsqlJsonb::Quoting.quote(value)
+    end
+
+    def self.quote_column_name(value)
+      RailsPsqlJsonb::Quoting.quote_column_name(value)
+    end
+
+    def self.quote_table_name(value)
+      RailsPsqlJsonb::Quoting.quote_table_name(value)
+    end
+
+    def self.quote_jsonb_value(value)
+      %('#{value.to_json}')
+    end
+
+    def self.quote_jsonb_keys(keys)
+      "'{#{keys.map(&:to_s).join(',')}}'"
+    end
+
+    def self.concatenation(target, keys, value)
+      "#{target}->#{keys.map { |x| quote(x) }.join('->')} || #{quote_jsonb_value(value)}"
+    end
+  end
+end

data/lib/rails_psql_jsonb/querying.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require_relative "query_helpers"
+require "json"
+
+module RailsPsqlJsonb
+  module Querying
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def jsonb_where(column_name:, operator:, value:, force_value_type: nil, json_keys: [], exclude: false)
+        _resolved, quoted_column = resolve_jsonb_column(column_name)
+        RailsPsqlJsonb::QueryHelpers.validate_operator!(operator)
+
+        query_operator = RailsPsqlJsonb::QueryHelpers::OPERATORS_MAP[operator]
+
+        if RailsPsqlJsonb::QueryHelpers.existence_operator?(query_operator)
+          query_clause = build_existence_clause(quoted_column, query_operator, value, json_keys)
+          return exclude ? where.not(query_clause) : where(query_clause)
+        end
+
+        is_numeric = RailsPsqlJsonb::QueryHelpers.numeric_operator?(query_operator)
+        # Use text-extraction operators (->> / #>>) for numeric comparisons when json_keys
+        # are present: extracts as text then casts to float, which is the idiomatic PG approach.
+        use_text_extraction = is_numeric && force_value_type.nil? && !json_keys.empty?
+
+        lhs_raw = build_lhs_expression(quoted_column, json_keys, text_extraction: use_text_extraction)
+
+        query_clause = if use_text_extraction
+          "(#{lhs_raw})::float #{query_operator} #{RailsPsqlJsonb::QueryHelpers.quote(value)}"
+        else
+          query_rhs = RailsPsqlJsonb::QueryHelpers.quote(is_numeric ? value : value.to_json)
+          cast_type = force_value_type || (is_numeric ? "float" : "jsonb")
+          "(#{lhs_raw})::#{cast_type} #{query_operator} (#{query_rhs})::#{cast_type}"
+        end
+
+        exclude ? where.not(query_clause) : where(query_clause)
+      end
+
+      def jsonb_where_not(column_name:, operator:, value:, force_value_type: nil, json_keys: [])
+        jsonb_where(column_name:, operator:, value:, force_value_type:, json_keys:, exclude: true)
+      end
+
+      def jsonb_order(column_name:, json_keys:, direction:)
+        _resolved, quoted_column = resolve_jsonb_column(column_name)
+        RailsPsqlJsonb::QueryHelpers.validate_json_keys_for_ordering!(json_keys)
+        RailsPsqlJsonb::QueryHelpers.validate_ordering!(direction)
+
+        lhs = build_lhs_expression(quoted_column, json_keys)
+        nulls_clause = direction.to_s.downcase == "asc" ? "NULLS LAST" : "NULLS FIRST"
+        order(Arel.sql("(#{lhs}) #{direction} #{nulls_clause}"))
+      end
+
+      def jsonb_where_exists(column_name:, key:, json_keys: [], exclude: false)
+        jsonb_where(column_name:, operator: :exists, value: key, json_keys:, exclude:)
+      end
+
+      def jsonb_where_exists_any(column_name:, keys:, json_keys: [], exclude: false)
+        jsonb_where(column_name:, operator: :exists_any, value: keys, json_keys:, exclude:)
+      end
+
+      def jsonb_where_exists_all(column_name:, keys:, json_keys: [], exclude: false)
+        jsonb_where(column_name:, operator: :exists_all, value: keys, json_keys:, exclude:)
+      end
+
+      # Returns the SQL to create a GIN index on a JSONB column for use in a migration:
+      #   execute MyModel.jsonb_gin_index_sql(column_name: "props")
+      #
+      # using: :jsonb_path_ops — smaller index, faster for @> (contains) queries
+      # using: :jsonb_ops      — default GIN, also supports ?, ?|, ?& key-existence operators
+      def jsonb_gin_index_sql(column_name:, using: :jsonb_path_ops)
+        table = connection.quote_table_name(table_name)
+        col   = connection.quote_column_name(column_name.to_s)
+        "CREATE INDEX ON #{table} USING GIN (#{col} #{using});"
+      end
+
+      def jsonb_batch_update(records_and_payloads)
+        transaction do
+          records_and_payloads.each do |record, input|
+            record.jsonb_update!(input)
+          end
+        end
+      end
+
+      private
+
+      def resolve_jsonb_column(column_name)
+        resolved = RailsPsqlJsonb::QueryHelpers.db_column_name(self, column_name)
+        RailsPsqlJsonb::QueryHelpers.validate_column_name!(self, resolved)
+        quoted = "#{RailsPsqlJsonb::QueryHelpers.quote_table_name(table_name)}.#{RailsPsqlJsonb::QueryHelpers.quote_column_name(resolved)}"
+        [resolved, quoted]
+      end
+
+      # Builds the LHS SQL expression for a JSONB path.
+      # For multi-key paths uses #> / #>> (path operators) instead of chained ->.
+      # text_extraction: true uses ->> / #>> (returns text, used before numeric cast).
+      def build_lhs_expression(quoted_column, json_keys, text_extraction: false)
+        return quoted_column if json_keys.empty?
+        if json_keys.length == 1
+          op = text_extraction ? "->>" : "->"
+          "#{quoted_column} #{op} #{RailsPsqlJsonb::QueryHelpers.quote(json_keys.first.to_s)}"
+        else
+          path = json_keys.map(&:to_s).join(",")
+          op = text_extraction ? "#>>" : "#>"
+          "#{quoted_column} #{op} '{#{path}}'"
+        end
+      end
+
+      def build_existence_clause(quoted_column, operator, value, json_keys)
+        case operator
+        when "?"
+          unless value.is_a?(String) || value.is_a?(Symbol)
+            raise TypeError, "value for ? (exists) operator must be a String or Symbol, got #{value.class}"
+          end
+        when "?|", "?&"
+          raise TypeError, "value for #{operator} operator must be an Array, got #{value.class}" unless value.is_a?(Array)
+        end
+
+        lhs = build_lhs_expression(quoted_column, json_keys)
+
+        case operator
+        when "?"
+          "#{lhs} ? #{RailsPsqlJsonb::QueryHelpers.quote(value.to_s)}"
+        when "?|", "?&"
+          keys = Array(value).map { |k| RailsPsqlJsonb::QueryHelpers.quote(k.to_s) }.join(", ")
+          "#{lhs} #{operator} ARRAY[#{keys}]"
+        end
+      end
+    end
+  end
+end

data/lib/rails_psql_jsonb/quoting.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+# Minimal copy of ActiveRecord's PostgreSQL quoting module.
+# Clone of: https://github.com/rails/rails/blob/5bec50bc70380bb1e70e8fb0a1654130042b1f16/activerecord/lib/active_record/connection_adapters/postgresql/quoting.rb
+#
+# Used as a module so we don't need ActiveRecord::Base.connection.quote, which
+# requires an active database connection even though quoting itself doesn't need one.
+#
+# A fix is available in ActiveRecord 7.2:
+# https://github.com/rails/rails/commit/0016280f4fde55d96738887093dc333aae0d107b
+# TODO: remove this module when minimum supported ActiveRecord version is >= 7.2.
+
+module RailsPsqlJsonb
+  module Quoting
+
+    class IntegerOutOf64BitRange < StandardError
+      def initialize(msg)
+        super(msg)
+      end
+    end
+
+    def self.quote_column_name(name)
+      "\"#{name}\""
+    end
+
+    def self.quote_table_name(name)
+      "\"#{name}\""
+    end
+
+    def self.check_int_in_range(value)
+      if value.to_int > 9223372036854775807 || value.to_int < -9223372036854775808
+        exception = <<~ERROR
+          Provided value outside of the range of a signed 64bit integer.
+
+          PostgreSQL will treat the column type in question as a numeric.
+          This may result in a slow sequential scan due to a comparison
+          being performed between an integer or bigint value and a numeric value.
+
+          To allow for this potentially unwanted behavior, set
+          ActiveRecord.raise_int_wider_than_64bit to false.
+        ERROR
+        raise IntegerOutOf64BitRange.new exception
+      end
+    end
+
+    def self.quote(value)
+      if ActiveRecord.raise_int_wider_than_64bit && value.is_a?(Integer)
+        check_int_in_range(value)
+      end
+
+      case value
+      when Numeric
+        if value.finite?
+          value.to_s
+        else
+          "'#{value}'"
+        end
+      when Range
+        quote(encode_range(value))
+      when String, Symbol, ActiveSupport::Multibyte::Chars
+        "'#{quote_string(value.to_s)}'"
+      when true       then "TRUE"
+      when false      then "FALSE"
+      when nil        then "NULL"
+      when BigDecimal then value.to_s("F")
+      when Date, Time then "'#{quoted_date(value)}'"
+      when Class      then "'#{value}'"
+      else raise TypeError, "can't quote #{value.class.name}"
+      end
+    end
+
+    def self.quote_string(s)
+      s.gsub("\\", '\&\&').gsub("'", "''")
+    end
+
+    def self.quoted_date(value)
+      if value.acts_like?(:time)
+        if ActiveRecord.default_timezone == :utc
+          value = value.getutc if !value.utc?
+        else
+          value = value.getlocal
+        end
+      end
+
+      result = value.to_fs(:db)
+      if value.respond_to?(:usec) && value.usec > 0
+        result << "." << sprintf("%06d", value.usec)
+      else
+        result
+      end
+    end
+
+    def self.encode_range(range)
+      "[#{type_cast_range_value(range.begin)},#{type_cast_range_value(range.end)}#{range.exclude_end? ? ')' : ']'}"
+    end
+
+    def self.type_cast_range_value(value)
+      return "" if infinity?(value)
+      case value
+      when Rational then value.to_f
+      when Symbol, ActiveSupport::Multibyte::Chars then value.to_s
+      when true  then true
+      when false then false
+      when BigDecimal then value.to_s("F")
+      when nil, Numeric, String then value
+      when Date, Time then quoted_date(value)
+      else raise TypeError, "can't cast #{value.class.name}"
+      end
+    end
+
+    def self.infinity?(value)
+      value.respond_to?(:infinite?) && value.infinite?
+    end
+  end
+end

data/lib/rails_psql_jsonb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsPsqlJsonb
+  VERSION = "0.2.0"
+end

data/lib/rails_psql_jsonb.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+require "active_record"
+require "active_record/connection_adapters/postgresql_adapter"
+
+require_relative "rails_psql_jsonb/version"
+require_relative "rails_psql_jsonb/errors"
+require_relative "rails_psql_jsonb/quoting"
+require_relative "rails_psql_jsonb/query_helpers"
+require_relative "rails_psql_jsonb/querying"
+require_relative "rails_psql_jsonb/atomic_update"
+
+module RailsPsqlJsonb
+  extend ActiveSupport::Concern
+  include RailsPsqlJsonb::Querying
+  include RailsPsqlJsonb::AtomicUpdate
+end

metadata

@@ -0,0 +1,145 @@
+--- !ruby/object:Gem::Specification
+name: rails_psql_jsonb
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- bubiche
+bindir: exe
+cert_chain: []
+date: 2026-04-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: pg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.5.6
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner-active_record
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: Provides jsonb_where, jsonb_order, and atomic update methods (jsonb_update!,
+  jsonb_delete_key, jsonb_array_append, jsonb_increment, and more) for PostgreSQL
+  JSONB columns in Rails ActiveRecord. Generates safe, type-cast SQL with no lost-update
+  race conditions under concurrency.
+email:
+- bubiche95@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/rails_psql_jsonb.rb
+- lib/rails_psql_jsonb/atomic_update.rb
+- lib/rails_psql_jsonb/errors.rb
+- lib/rails_psql_jsonb/query_helpers.rb
+- lib/rails_psql_jsonb/querying.rb
+- lib/rails_psql_jsonb/quoting.rb
+- lib/rails_psql_jsonb/version.rb
+homepage: https://github.com/bubiche/rails_psql_jsonb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bubiche/rails_psql_jsonb
+  source_code_uri: https://github.com/bubiche/rails_psql_jsonb
+  changelog_uri: https://github.com/bubiche/rails_psql_jsonb/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: ActiveRecord helpers for querying and atomically updating PostgreSQL JSONB
+  columns.
+test_files: []