pg_hash_func 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47be51c825e894ee45f7988db38544022028bb084cc82448f14409547e5eef38
-  data.tar.gz: 48541492aa6ac7815e05580c9b76fd522b75b033d43edc76e73ccb32ef55baad
+  metadata.gz: 0303bfab8aabd0277360e7634888b7e5d537c89bf1dfd9ed69974d6932db62d5
+  data.tar.gz: 273b85ecaf3dc8763840c4a3960b6fc671f14d448e6feab14c7a3c6e1d88aec7
 SHA512:
-  metadata.gz: 5255d4ab2d65c8ce8a5e9be8be446f40932b0ae2861d4c9794a513f8746f94381adcc3e968a06191ef3c66dc85295618ce5be70887b2658935cec12e56689c4c
-  data.tar.gz: 7e80636f9c6a53328f3d46b0e096aba3efa44618d97b72b70b702c6f05ce721a25a7acb1f5ce953b8d3688b49b0ccb70b80a72cf3cb82733c12ff94cbdd8812e
+  metadata.gz: 8813ec5ac0235621d59b768be7c5ee1512d5900c8ccf370e5393abded30786c9cefca1d1becb2b3780c8c9a6506c0048502eda3cebe554ec6fe60440f250337a
+  data.tar.gz: 103a1377449085d683716668174c9d7b323b203bdbca4990e99c87f49a905b9927617affe7aa1381893e956394dd01bcf2d0573727a59bfa2136f194a5e56782

data/.rubocop.yml

@@ -1,6 +1,6 @@
 # .rubocop.yml
 
-require:
+plugins:
   - rubocop-performance
   - rubocop-rake
   - rubocop-rspec
@@ -41,10 +41,20 @@ Metrics/BlockLength:
     - "spec/**/*_spec.rb"
 
 RSpec/ExampleLength:
-  Max: 10
+  Max: 25
+  Exclude:
+    - "spec/**/*_spec.rb"
 
 RSpec/MultipleExpectations:
   Max: 5
 
+RSpec/MultipleMemoizedHelpers:
+  Max: 15
+  Exclude:
+    - "spec/**/*_spec.rb"
+
 Style/StringLiterals:
   EnforcedStyle: double_quotes
+
+Metrics/ModuleLength:
+  Max: 200

data/Gemfile

@@ -10,9 +10,10 @@ group :development, :test do
   gem "benchmark-ips"
   gem "bundler"
   gem "pg"
-  gem "rake", "~> 13.0"
-  gem "rspec", "~> 3.0"
-  gem "rubocop", "~> 1.60" # Use a recent version
+  gem "pry"
+  gem "rake"
+  gem "rspec"
+  gem "rubocop"
   gem "rubocop-performance"
   gem "rubocop-rake"
   gem "rubocop-rspec"

data/Gemfile.lock

@@ -1,23 +1,28 @@
 PATH
   remote: .
   specs:
-    pg_hash_func (0.1.0)
+    pg_hash_func (0.1.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
     benchmark-ips (2.14.0)
-    diff-lcs (1.6.1)
-    json (2.11.3)
-    language_server-protocol (3.17.0.4)
+    coderay (1.1.3)
+    diff-lcs (1.6.2)
+    json (2.12.0)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    method_source (1.1.0)
     parallel (1.27.0)
     parser (3.3.8.0)
       ast (~> 2.4.1)
       racc
     pg (1.5.9)
     prism (1.4.0)
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.2.1)
@@ -28,14 +33,14 @@ GEM
       rspec-mocks (~> 3.13.0)
     rspec-core (3.13.3)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.3)
+    rspec-expectations (3.13.4)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.2)
+    rspec-mocks (3.13.4)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.2)
-    rubocop (1.75.3)
+    rspec-support (3.13.3)
+    rubocop (1.75.6)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -73,9 +78,10 @@ DEPENDENCIES
   bundler
   pg
   pg_hash_func!
-  rake (~> 13.0)
-  rspec (~> 3.0)
-  rubocop (~> 1.60)
+  pry
+  rake
+  rspec
+  rubocop
   rubocop-performance
   rubocop-rake
   rubocop-rspec

data/README.md

@@ -3,7 +3,9 @@
 [![CI](https://github.com/shayonj/pg_hash_func/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/shayonj/pg_hash_func/actions/workflows/ci.yml)
 [![Gem Version](https://badge.fury.io/rb/pg_hash_func.svg)](https://badge.fury.io/rb/pg_hash_func)
 
-Determine the target partition index for an integer key according to PostgreSQL's default hash strategy, without querying the database.
+This gem allows your application to calculate the target partition for integer keys in PostgreSQL **hash-partitioned** tables _without_ querying the database. Typically, when querying a parent partitioned table, PostgreSQL consults catalog tables to route the query, incurring network latency and lookup costs. By replicating PostgreSQL's native hashing logic, this gem allows your application to bypass the parent table and directly derive the partition name/index, leading to significant performance gains in read-heavy, latency-sensitive workloads.
+
+This gem replicates the hashing logic PostgreSQL's `hashint8extended` (for `bigint`) and `hashint4extended` (for `integer` and `smallint`) in [src/backend/access/hash/hashfunc.c](https://github.com/postgres/postgres/blob/master/src/backend/access/hash/hashfunc.c)
 
 **Supported Types:**
 

data/benchmarks/file.rb

@@ -1,14 +1,14 @@
 # frozen_string_literal: true
 
-require 'benchmark/ips'
-require 'pg'
-require_relative '../lib/pg_hash_func'
+require "benchmark/ips"
+require "pg"
+require_relative "../lib/pg_hash_func"
 DB_CONFIG = {
-  dbname: ENV['PGDATABASE'] || 'postgres',
-  user: ENV['PGUSER'] || 'postgres',
-  password: ENV['PGPASSWORD'],
-  host: ENV['PGHOST'] || 'localhost',
-  port: ENV['PGPORT'] || 5432
+  dbname: ENV["PGDATABASE"] || "postgres",
+  user: ENV["PGUSER"] || "postgres",
+  password: ENV.fetch("PGPASSWORD", nil),
+  host: ENV["PGHOST"] || "localhost",
+  port: ENV["PGPORT"] || 5432
 }.compact
 
 # Constants from the gem
@@ -16,37 +16,49 @@ SEED = PgHashFunc::Hasher::HASH_PARTITION_SEED
 MAGIC = PgHashFunc::Hasher::PARTITION_MAGIC_CONSTANT
 UINT64_MODULUS = PgHashFunc::Hasher::UINT64_MASK + 1 # 2^64
 
-TEST_DATA = [
+TEST_DATA_BIGINT = [
   [1, 16],
   [-1, 16],
   [540_364, 16],
-  [2**31 - 1, 32],
+  [(2**31) - 1, 32],
   [-(2**31), 32],
-  [2**63 - 1, 64],
+  [(2**63) - 1, 64],
   [-(2**63), 64],
   [123_456_789_012_345, 1024],
   [9_223_372_036_854_775_807, 2048]
 ].freeze
 
-SQL_QUERY = <<~SQL
+TEST_DATA_INT4 = [
+  [1, 16],
+  [-1, 16],
+  [123_456, 16],
+  [(2**31) - 1, 32],
+  [-(2**31), 32]
+].freeze
+
+SQL_QUERY_BIGINT = <<~SQL
   SELECT ( ( ((hashint8extended($1::bigint, $2::bigint)::numeric + $3::numeric) % $5::numeric) % $4::numeric ) + $4::numeric ) % $4::numeric;
 SQL
 
+SQL_QUERY_INT4 = <<~SQL
+  SELECT (( ( (hashint4extended($1::integer, $2::bigint)::numeric % $4::numeric ) % $3::numeric ) + $3::numeric ) % $3::numeric);
+SQL
+
 begin
   conn = PG.connect(DB_CONFIG)
-  puts 'Connected to PostgreSQL.'
+  puts "Connected to PostgreSQL."
 rescue PG::ConnectionBad => e
-  puts 'Failed to connect to PostgreSQL. Ensure DB is running and configured correctly.'
+  puts "Failed to connect to PostgreSQL. Ensure DB is running and configured correctly."
   puts "Error: #{e.message}"
   exit(1)
 end
 
-puts 'Warming up...'
+puts "Warming up..."
 
 Benchmark.ips do |x|
-  x.report('Ruby Calculation') do
-    TEST_DATA.each do |key, num_partitions|
-      PgHashFunc.calculate_partition_index(
+  x.report("Ruby Calculation (bigint)") do
+    TEST_DATA_BIGINT.each do |key, num_partitions|
+      PgHashFunc.calculate_partition_index_bigint(
         value: key,
         num_partitions: num_partitions,
         seed: SEED,
@@ -55,9 +67,26 @@ Benchmark.ips do |x|
     end
   end
 
-  x.report('SQL Query') do
-    TEST_DATA.each do |key, num_partitions|
-      result = conn.exec_params(SQL_QUERY, [key, SEED, MAGIC, num_partitions, UINT64_MODULUS])
+  x.report("SQL Query (bigint)") do
+    TEST_DATA_BIGINT.each do |key, num_partitions|
+      result = conn.exec_params(SQL_QUERY_BIGINT, [key, SEED, MAGIC, num_partitions, UINT64_MODULUS])
+      result.getvalue(0, 0).to_i
+    end
+  end
+
+  x.report("Ruby Calculation (int4)") do
+    TEST_DATA_INT4.each do |key, num_partitions|
+      PgHashFunc.calculate_partition_index_int4(
+        value: key,
+        num_partitions: num_partitions,
+        seed: SEED
+      )
+    end
+  end
+
+  x.report("SQL Query (int4)") do
+    TEST_DATA_INT4.each do |key, num_partitions|
+      result = conn.exec_params(SQL_QUERY_INT4, [key, SEED, num_partitions, UINT64_MODULUS])
       result.getvalue(0, 0).to_i
     end
   end
@@ -66,20 +95,20 @@ Benchmark.ips do |x|
 end
 
 conn.close if conn && !conn.finished?
-puts 'Disconnected from PostgreSQL.'
+puts "Disconnected from PostgreSQL."
 
 # Connected to PostgreSQL.
 # Warming up...
 # ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +PRISM [arm64-darwin24]
 # Warming up --------------------------------------
-#     Ruby Calculation     6.755k i/100ms
-#            SQL Query   320.000 i/100ms
+#     Ruby Calculation (bigint)     6.755k i/100ms
+#            SQL Query (bigint)   320.000 i/100ms
 # Calculating -------------------------------------
-#     Ruby Calculation     67.103k (± 3.4%) i/s   (14.90 μs/i) -    337.750k in   5.040734s
-#            SQL Query      3.192k (± 2.6%) i/s  (313.26 μs/i) -     16.000k in   5.016067s
+#     Ruby Calculation (bigint)     67.103k (± 3.4%) i/s   (14.90 μs/i) -    337.750k in   5.040734s
+#            SQL Query (bigint)      3.192k (± 2.6%) i/s  (313.26 μs/i) -     16.000k in   5.016067s
 
 # Comparison:
-#     Ruby Calculation:    67102.7 i/s
-#            SQL Query:     3192.2 i/s - 21.02x  slower
+#     Ruby Calculation (bigint):    67102.7 i/s
+#            SQL Query (bigint):     3192.2 i/s - 21.02x  slower
 
 # Disconnected from PostgreSQL.

data/lib/pg_hash_func/hasher.rb

@@ -120,19 +120,42 @@ module PgHashFunc
 
       hash_val = hashint8extended(value: value, seed: seed)
 
-      result = (hash_val + magic_constant) & UINT64_MASK
-      idx = result % num_partitions
+      # First, interpret the 64-bit hash as signed, matching PostgreSQL's
+      # behavior where the C function's uint64 return value is received in SQL
+      # as a signed int8.
+      signed_hash = hash_val >= 0x8000_0000_0000_0000 ? hash_val - (1 << 64) : hash_val
+
+      # Now add the magic constant in signed 64-bit arithmetic (two's-
+      # complement wrap-around). We keep the wrap-around by masking back to
+      # 64-bits as PostgreSQL does with uint64 arithmetic before the cast.
+      unsigned_sum = (signed_hash + magic_constant) & UINT64_MASK
+
+      # Cast that wrapped result back to signed 64-bit for the final modulo.
+      signed_sum = unsigned_sum >= 0x8000_0000_0000_0000 ? unsigned_sum - (1 << 64) : unsigned_sum
+
+      # Follow the expression that postgres uses internally:
+      rem = signed_sum.remainder(num_partitions)
+      idx = (rem + num_partitions) % num_partitions
       idx.to_i
     end
 
     # Calculates the target partition index for a given int4 value.
-    def self.calculate_partition_index_int4(value:, seed:, magic_constant:, num_partitions:)
+    def self.calculate_partition_index_int4(value:, seed:, num_partitions:)
       raise ArgumentError, "Number of partitions must be positive" unless num_partitions.positive?
 
       hash_val = hashint4extended(value: value, seed: seed)
 
-      result = (hash_val + magic_constant) & UINT64_MASK
-      idx = result % num_partitions
+      signed_hash = hash_val >= 0x8000_0000_0000_0000 ? hash_val - (1 << 64) : hash_val
+
+      # PostgreSQL does *not* add the partition magic constant for int2/int4
+      # hash partitioning (see get_hash_partition_greatest_modulus_int4 in the
+      # backend). Only bigint types add the magic. Therefore we skip it here.
+      unsigned_sum = signed_hash & UINT64_MASK
+
+      signed_sum = unsigned_sum >= 0x8000_0000_0000_0000 ? unsigned_sum - (1 << 64) : unsigned_sum
+
+      rem = signed_sum.remainder(num_partitions)
+      idx = (rem + num_partitions) % num_partitions
       idx.to_i
     end
   end

data/lib/pg_hash_func/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PgHashFunc
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/pg_hash_func.rb

@@ -36,17 +36,16 @@ module PgHashFunc
 
   # Calculates the target partition index for a given integer (int4) or smallint (int2) value based on
   # PostgreSQL's default hash partitioning strategy.
-  # Mimics (hashint4extended(value, seed) + magic) % num_partitions using uint64 arithmetic.
-  # Note: PostgreSQL uses the same hash function (`hashint4extended` equivalent) for both int2 and int4.
+  # Mimics hashint4extended(value, seed) % num_partitions using uint64 arithmetic.
+  # Note 1: PostgreSQL uses the same hash function (`hashint4extended` equivalent) for both int2 and int4.
+  # Note 2: Unlike bigint hash partitioning, PostgreSQL does NOT add the magic constant for int4/int2
+  # hash partitioning.
   #
   # @param value [Integer] The partitioning key value (treated as int4/int2).
   # @param num_partitions [Integer] The number of partitions for this level.
   # @param seed [Integer] The 64-bit seed. Defaults to PostgreSQL's standard HASH_PARTITION_SEED.
-  # @param magic_constant [Integer] The magic constant. Defaults to PostgreSQL's standard PARTITION_MAGIC_CONSTANT.
   # @return [Integer] The calculated partition index (0-based).
-  def self.calculate_partition_index_int4(value:, num_partitions:, seed: Hasher::HASH_PARTITION_SEED,
-                                          magic_constant: Hasher::PARTITION_MAGIC_CONSTANT)
-    Hasher.calculate_partition_index_int4(value: value, seed: seed, magic_constant: magic_constant,
-                                          num_partitions: num_partitions)
+  def self.calculate_partition_index_int4(value:, num_partitions:, seed: Hasher::HASH_PARTITION_SEED)
+    Hasher.calculate_partition_index_int4(value: value, seed: seed, num_partitions: num_partitions)
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pg_hash_func
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Shayon Mukherjee
 bindir: exe
 cert_chain: []
-date: 2025-04-26 00:00:00.000000000 Z
+date: 2025-05-17 00:00:00.000000000 Z
 dependencies: []
 description: |
   Replicates PostgreSQL's default hash partitioning calculations.