pgi 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e861fe364065922d9e21beb03770004e3645a31b2cd9fe827b0a517aa35739e
-  data.tar.gz: 45e6948a019f2194f4d1f2cc49ab81d575c55d16014baf3585f00a85b957374e
+  metadata.gz: e57eefff746743d0e70c5c256fa2fed74f2335c07b9657c67e0f517a5a37b927
+  data.tar.gz: '0073639115a44fe351077c3577b7e355da0165e580683c17620fc50b824303fe'
 SHA512:
-  metadata.gz: 22c23e207efec5a443f93c316dad62e556ad63bffe3d18b618d26dc211d56676a51789f94ccdeb9acb791433b3c94b76d6145e455358435ed8dff193090d7519
-  data.tar.gz: 2a6f49983336cedaf4997d625923964611336f309c686f8b548d484324dcf110c1a71da20e8e0c7618a8c1909d043be341437dea3cef3293ec71a8e0b0ffb1c4
+  metadata.gz: 7b981f438da0b1f82946471622922d1eee510cb135b67f3db5fa108e24fdb2b7936648c55385841f13d67bfc1a479c48c78e6298701a4d962abc2f69e2fbb614
+  data.tar.gz: 38a762ec93398e240563e2dfc46d3b7ae8d8e3d1c08938c23c25e90ad2286789e4b1b4b553c7f0185d1146ea6c8acb7cf80ab8370678d36e43a9f753f4964c92

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # CHANGELOG
 
+## Unreleased
+
+- **Sort on a projection** — `#order` and `#page`/`#keyset` accept a declared
+  `projections:` name as the sort column and order (and seek) on its
+  expression, so a list can page on a computed value.
+
+- **`DB.configure` requires `pg_conn_uri`** — leaving it unset used to pass
+  `configure` and raise at the first pool checkout, naming `Connection.new`'s
+  keywords instead of the knob you set; it now raises `ArgumentError` there and
+  then. Pass `pg_conn_uri: ""` to ask libpq for its defaults on purpose.
+
+- **`DB.configure` no longer shares state between databases** (bug fix) — the
+  options lived on the class and the pool read them at checkout time, so a second
+  `configure` silently took over the first DB's pool. Each call now keeps its
+  own options.
+
+- **`Connection.new` requires a connection** — building one with neither
+  `conn:` nor `conn_uri:` now raises `ArgumentError` instead of connecting to
+  whatever libpq's environment defaults point at. Pass `conn_uri: ""` to ask
+  for those defaults on purpose.
+
+- **A colliding projection name raises** (behaviour change) — a `projections:`
+  entry named after a base column landed as a second result field and silently
+  overwrote the base value; the read now raises, as an unaliased joined column
+  from `#select` already did.
+
+- **Dependency updates**
+  - connection_pool: the dependency widens from `~> 2.4` to `>= 2.4, < 4`.
+
 ## 1.1.0 (2026-08-28)
 
 The query release: joins, search, projected columns — and server notices that

data/README.md

@@ -58,8 +58,10 @@ Repository.page(nil, 20, :name, :asc)   # first page of 20, sorted by name
 
 The pieces:
 
-* `#select(column1, ...)` — limit the result set to the specified columns
-  (also appends **joined** columns, see [Projecting joined columns](#projecting-joined-columns))
+* `Dataset#select(column1, ...)` — start a query limited to the specified
+  columns of the base table
+* `Query#select(column1, ...)` — append a **joined** table's column onto the
+  base table's columns, see [Projecting joined columns](#projecting-joined-columns)
 * `#where(...)` — can only be called once per query, so combine all conditions
   in a single call. Two forms:
   * `#where("name = ? AND age > ?", ['joe', 21])` — a string clause with placeholders (`?` or `$1`)
@@ -252,8 +254,17 @@ Notes:
   filtering **on** a projection promotes evaluation to the whole scope; that
   EXPLAIN is the caller's to own. If a projection ever measures hot, the
   escalation is a trigger-maintained column, not a cleverer query.
-- A projection name colliding with a base column will overwrite it in the row
-  hash — pick names that cannot collide (`mates_count`, not `count`).
+- **Sort on a projection** — `#order` and `#page`/`#keyset` take a declared
+  projection's name as the sort column and order on its expression; the
+  read need not project it. The cursor row resolves the same expression.
+
+  ```ruby
+  Repository.page(nil, 20, :mates_count, :desc)
+  ```
+- **A colliding name raises** — a projection named after a base column would
+  overwrite it in the row hash, so the read raises when the rows come back
+  (same guard as an unaliased joined column). Pick names that cannot collide
+  (`mates_count`, not `count`).
 
 ### Search
 

data/VERSION

@@ -1 +1 @@
-1.1.0
+1.2.0

data/lib/pgi/connection.rb

@@ -10,9 +10,12 @@ module PGI
 
     # Create instance
     #
-    # @param pool [ConnectionPool]
     # @param logger [Logger]
+    # @param conn_uri [String] connection URI; "" asks libpq for its own defaults
+    # @param conn [PG::Connection] an already built connection, used as is
     def initialize(logger:, conn_uri: nil, conn: nil)
+      raise ArgumentError, "conn or conn_uri required" unless conn || conn_uri
+
       @logger = logger
 
       @conn = conn || PG::Connection.new(conn_uri).tap do |new_conn|
@@ -24,7 +27,7 @@ module PGI
 
         new_conn.type_map_for_results = PG::BasicTypeMapForResults.new(new_conn, registry: regi)
         new_conn.type_map_for_queries = PG::BasicTypeMapForQueries.new(new_conn, registry: regi)
-      end || raise("no connection provided")
+      end
 
       # Server notices (a DROP CASCADE's chatter, a RAISE NOTICE) route to
       # the configured logger instead of libpq's stderr default: a library

data/lib/pgi/dataset/query.rb

@@ -37,7 +37,8 @@ module PGI
       # Opt into declared projections for THIS read: the named computed
       # columns join the select list as (expr) AS name. Names must be
       # declared on the dataset (the trust boundary stays at extension
-      # time); unknown names raise.
+      # time); unknown names raise. A name that collides with a base column
+      # raises when the rows come back, rather than clobbering it.
       #
       # @param names [Array<Symbol>] declared projection names
       # @return [Query] the Query instance (for method chaining)
@@ -201,7 +202,8 @@ module PGI
       # Adds a ORDER BY clause to the query - suports multiple calls to the method
       #
       # @param column [Symbol, Hash] the column - a single-pair Hash qualifies
-      #   it with a joined table: { users: :name }
+      #   it with a joined table: { users: :name }; a declared projection's
+      #   name sorts on its expression
       # @param direction [Symbol] the direction the sort should take - can be either `:desc` or `:asc`
       # @param collate [String, nil] collation for text ordering, e.g. "da-x-icu"
       #   (policy - which locale maps to which collation - belongs to the caller)
@@ -234,7 +236,7 @@ module PGI
       # Do not combine with a conflicting #order call — pages are only correct when
       # the leading sort columns match the cursor predicate.
       #
-      # @param sort_by [Symbol] the sort column
+      # @param sort_by [Symbol] the sort column, or a declared projection's name
       # @param cursor_id [*, nil] id of the last row from the previous page, or nil for the first page
       # @param sort_dir [Symbol] :asc or :desc
       # @param collate [String, nil] collation for the sort column. Must be the
@@ -367,31 +369,32 @@ module PGI
 
       private
 
-      # Run the query and guard against a projected-column name collision
-      # before the rows are handed back (see #select).
+      # Run the query and guard against a duplicate result field name before
+      # the rows are handed back (see #assert_result_unambiguous!).
       #
       # @return [PG::Result]
       def result
         res = @database.exec_stmt(Utils.stmt_name(@table, sql), sql, params)
-        assert_projection_unambiguous!(res)
+        assert_result_unambiguous!(res)
         res
       end
 
-      # Raise if #select projected two columns onto the same result field name
-      # (a joined column clashing with a base column, or two joined columns) -
-      # the row hash would silently keep only the last, losing data. Only
-      # relevant when #select added columns; a plain base.* read cannot clash.
+      # Raise when two columns land on the same result field name - the row
+      # hash would silently keep only the last, losing data.
+      #
+      # A plain base.* read cannot clash, so only an appended column can:
+      # #select's joined column or an opted-in projections: entry.
       #
       # @param result [PG::Result]
       # @raise [RuntimeError] listing the duplicated field name(s)
-      def assert_projection_unambiguous!(result)
-        return if @select.empty?
+      def assert_result_unambiguous!(result)
+        return if @select.empty? && @projected.empty?
 
         dups = result.fields.tally.select { |_, n| n > 1 }.keys
         return if dups.empty?
 
-        raise "Ambiguous projected column(s): #{dups.join(", ")} - alias with " \
-              "select(table => { column: :alias }) to disambiguate"
+        raise "Ambiguous result column(s): #{dups.join(", ")} - alias a joined column " \
+              "with select(table => { column: :alias }), or rename the colliding projections: entry"
       end
 
       # Render a #select column: a bare column (base table), a { table => column }
@@ -438,16 +441,24 @@ module PGI
         term.to_s.gsub(/[\\%_]/) { |c| "\\#{c}" }
       end
 
+      # A declared projection's trusted expression, parenthesised; nil for any other name.
+      def projected_term(name)
+        return if name.is_a?(Hash)
+
+        expr = @projections[name.to_sym] || @projections[name.to_s]
+        expr && "(#{expr})"
+      end
+
       def assert_known_table!(table)
         return if table.to_sym == @table.to_sym || @join_tables.include?(table.to_sym)
 
         raise "Unknown table #{table.inspect} - qualify only the base table or joined tables"
       end
 
-      # A column reference with an optional COLLATE. Collation names are
-      # identifiers (e.g. "da-x-icu"), validated and quoted - never params.
+      # A sort term with an optional COLLATE: a declared projection's
+      # expression, else a column. Collation names are validated and quoted.
       def collated_column(column, collate)
-        col = qualified_column(column)
+        col = projected_term(column) || qualified_column(column)
         return col unless collate
 
         raise "Invalid collation: #{collate.inspect}" unless collate.to_s.match?(COLLATION_NAME)

data/lib/pgi/dataset.rb

@@ -194,9 +194,8 @@ module PGI
     # @param attributes [Hash] column => value
     # @return [Array(Array, Array, Array)] sanitized columns, placeholders, values
     def sql_params(attributes)
-      # Projections are READ-ONLY facts computed by the dataset - they ride
-      # every read and RETURNING, so a model round-trip (find -> to_h ->
-      # update) naturally carries them; writes must shed them silently.
+      # Projections are READ-ONLY facts computed by the dataset - a model built
+      # from a projected read carries them, so writes must shed them silently.
       projections = @options.fetch(:projections, {})
       attrs = attributes.reject { |k, _| projections.key?(k.to_sym) }.sort.to_h
       [Utils.sanitize_columns(attrs.keys), (1..attrs.size).map { |i| "$#{i}" }, attrs.values]

data/lib/pgi/db.rb

@@ -20,19 +20,24 @@ module PGI
       @retry_wait  = retry_wait
     end
 
+    # Build a DB from a block of options. The options are a local, so the pool
+    # block closes over this call's values - a second DB never takes over this one.
     def self.configure
-      @options = Struct.new(
+      options = Struct.new(
         :pool_size, :pool_timeout, :pg_conn_uri, :logger, :max_retries, :retry_wait
       ).new
 
-      yield @options
+      yield options
 
-      pool = ConnectionPool.new(size: @options.pool_size, timeout: @options.pool_timeout) do
-        Connection.new(conn_uri: @options.pg_conn_uri, logger: @options.logger)
+      # Fail where the knob was set, not at the first checkout; "" asks libpq for its defaults.
+      raise ArgumentError, "pg_conn_uri required" if options.pg_conn_uri.nil?
+
+      pool = ConnectionPool.new(size: options.pool_size, timeout: options.pool_timeout) do
+        Connection.new(conn_uri: options.pg_conn_uri, logger: options.logger)
       end
 
-      retry_options = { max_retries: @options.max_retries, retry_wait: @options.retry_wait }.compact
-      new(pool, @options.logger, **retry_options)
+      retry_options = { max_retries: options.max_retries, retry_wait: options.retry_wait }.compact
+      new(pool, options.logger, **retry_options)
     end
 
     # wrapper around ConnectionPool#with with auto-healing capabilities

data/pgi.gemspec

@@ -18,7 +18,7 @@ Gem::Specification.new do |gem|
   gem.require_paths = ["lib"]
   gem.files         = Dir["lib/**/*", "CHANGELOG.md", "LICENSE", "README.md", "VERSION", "pgi.gemspec"]
 
-  gem.add_dependency "connection_pool", "~> 2.4"
+  gem.add_dependency "connection_pool", ">= 2.4", "< 4"
   gem.add_dependency "pg", "~> 1.5"
 
   gem.metadata["rubygems_mfa_required"] = "true"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgi
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Coherify
@@ -13,16 +13,22 @@ dependencies:
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement