skaidb 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a9f39f07d8b6d8abb6edf43d48b4c70da568b4a66f62044fb6f36d7b7b0e1ae
-  data.tar.gz: bb205511e213fe77efcfbaff5c17b82c453fcc2135cee1c362e154b9ad169e6f
+  metadata.gz: a452610f682221a59cfbbc48e42c9a37f1c0e880d2191037f1c9c7151a3034fa
+  data.tar.gz: 1a73f7f552091bfaed9b4072dfd684b57daac637ff12d163a34bf1c278bef784
 SHA512:
-  metadata.gz: 9ce5348688c5bd6cd480006b2fa567ed7af74cc0ffe557f387d55705effd49dcbd754b8c52b32a30ae3361234226e4a82828bff7dc0d3d43f9a03e086849c53b
-  data.tar.gz: e7d6fd76c93392bbea0e2583b5741b418188c4d045d0226d7e8d0dcf2828fbe4cd03e34a32da58598d0173d81875cf8b1fe5b405c64e0ac658c108be67adf1da
+  metadata.gz: ce44a1e28e0add382aa9fde578eb09350e1b5306d22c3cf5d272faa5d606c8ec05be08b77967d014a33ceddba5fefd0ed449503c24d4997680c37af156ad2e5f
+  data.tar.gz: 3d34175d862982988e593fb42c631bdbb9cd6f23682908ec40fc53a7d25fe3868105201dd50988108508783bfb8bf076065737864d71c6cc5337c8b6c371e6c3

data/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to the skaidb Ruby driver. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [1.3.0] - 2026-10-29
+
+### Added
+- **Parameterised streaming**: `conn.stream(sql, params)` binds `$1`, `$2`,
+  … exactly as `exec_params(sql, params)` does — typed, with the same values
+  (Arrays, Hashes, `Time`, `BigDecimal`, `Skaidb::Uuid`, …) and the same
+  placeholder checks — over `OP_QUERY_STREAM_PARAMS` (server ≥ 0.330), so a
+  range-bounded export no longer needs its values written into the SQL. It
+  takes `consistency:`, a block or the Enumerator form like any stream.
+  Without parameters (`nil` or `[]`) the request is the original
+  `OP_QUERY_STREAM`, byte for byte, so it works against every server; a
+  parameterised stream against an older server raises `QueryError`
+  (`server does not support parameterised streaming (skaidb >= 0.330): …`)
+  and leaves the connection usable. `params` that are not an Array raise
+  `ArgumentError`.
+- The vendored conformance suite's `stream_params` case (a streamed
+  statement with bound parameters) runs through `stream(sql, params)`.
+
 ## [1.2.0] - 2026-10-25
 
 ### Added
@@ -174,6 +192,7 @@ batches, a 2 500-row stream, error handling, and the `drivers` table showing
   because it is a bundled gem since Ruby 3.4.
 - The example moved to `examples/basic.rb`.
 
+[1.3.0]: https://github.com/porcupin26/skaidb-ruby/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/porcupin26/skaidb-ruby/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/porcupin26/skaidb-ruby/compare/v1.0.3...v1.1.0
 [1.0.3]: https://github.com/porcupin26/skaidb-ruby/compare/v1.0.2...v1.0.3

data/README.md

@@ -55,13 +55,13 @@ Xcode command-line tools on macOS). `gem install skaidb` and vendoring reuse
 the `bigdecimal` already installed.
 
 Or vendor the single file: copy
-[`lib/skaidb.rb`](https://github.com/porcupin26/skaidb-ruby/blob/v1.2.0/lib/skaidb.rb)
+[`lib/skaidb.rb`](https://github.com/porcupin26/skaidb-ruby/blob/v1.3.0/lib/skaidb.rb)
 into your project and `require_relative` it. It has no dependencies beyond
 Ruby's standard library.
 
 Every release is also attached as a `.gem` to its
 [GitHub release](https://github.com/porcupin26/skaidb-ruby/releases) for
-installs without registry access: `gem install ./skaidb-1.2.0.gem`.
+installs without registry access: `gem install ./skaidb-1.3.0.gem`.
 
 ## Quick start
 
@@ -280,8 +280,9 @@ A result holds all its rows in memory; for results that do not fit, stream.
 
 ## Streaming large results
 
-`conn.stream(sql, consistency: nil)` runs the statement over the streaming
-opcode and yields one row Hash at a time, holding **one chunk** in memory:
+`conn.stream(sql, params = [], consistency: nil)` runs the statement over the
+streaming opcode and yields one row Hash at a time, holding **one chunk** in
+memory:
 
 ```ruby
 conn.stream("SELECT id, pad FROM big ORDER BY id") do |row|
@@ -289,12 +290,23 @@ conn.stream("SELECT id, pad FROM big ORDER BY id") do |row|
 end
 
 first = conn.stream("SELECT id FROM big ORDER BY id").first(10)   # Enumerator form
+
+conn.stream("SELECT id, ts, body FROM events WHERE ts >= $1 AND ts < $2", [from, to]) do |row|
+  export(row)                    # bound parameters, typed
+end
 ```
 
-`stream` takes SQL text only (no parameters). With a block it returns a
-`Result` whose `kind` is `:stream` and whose `fields` are the column names
-(the rows went to the block); a non-row statement returns its `:mutation` /
-`:ddl` Result without yielding.
+`params` bind `$1`, `$2`, … exactly as `exec_params` binds them — typed, with
+the same values accepted — and need a server ≥ 0.330: an older one raises
+`QueryError` (`server does not support parameterised streaming (skaidb >=
+0.330): …`), and there is no client-side text fallback. A stream without
+parameters sends the original streaming opcode, which every server
+understands. The server pages a plain `SELECT` (bare columns from one table,
+unordered or in storage-key order), and no scan budget applies to a streamed
+page (server ≥ 0.330). With a block `stream` returns a `Result` whose `kind`
+is `:stream` and whose `fields` are the column names (the rows went to the
+block); a non-row statement returns its `:mutation` / `:ddl` Result without
+yielding.
 
 **The abandon/drain rule.** The connection is busy for the whole stream:
 a statement from another thread waits for it. Leaving the block early —
@@ -418,8 +430,8 @@ StandardError
 - A transport failure (`ConnectionError`) marks the connection broken; the
   next statement re-dials, or a pool replaces it.
 - `ArgumentError` for `Pool.new(maxsize: 0)` or an unknown
-  `load_balancing`/`idle_order`, and for `Skaidb::Uuid.new` of a string that
-  is not a UUID.
+  `load_balancing`/`idle_order`, for `Skaidb::Uuid.new` of a string that
+  is not a UUID, and for `stream` parameters that are not an Array.
 
 ## Transactions
 
@@ -446,7 +458,7 @@ frame after every handshake. It shows up as `client_name = 'ruby'` /
 
 ```sql
 SELECT client_name, client_version FROM drivers;
--- ruby | 1.2.0
+-- ruby | 1.3.0
 ```
 
 The server records the row asynchronously, so a `SELECT` immediately after
@@ -461,7 +473,8 @@ know the opcode answers with an error the driver ignores.
   falls back: prepared statements → client-side text binding, `Hello` →
   ignored, pool discovery (`SHOW ENDPOINTS`, server ≥ 0.327) → the
   configured seeds. `stream` and `exec_batch` need a server with those
-  opcodes and raise `QueryError` otherwise.
+  opcodes, and `stream` with parameters a server ≥ 0.330; they raise
+  `QueryError` otherwise.
 - The wire protocol (framing, SCRAM handshake, value encoding, opcodes) is
   specified at <https://skaidb.org/docs/PROTOCOL.html>. The driver speaks the
   binary protocol on port 7000; the server's REST/JSON gateway (port 7080)

data/docs/api.md

@@ -55,8 +55,16 @@ Raises `Skaidb::Error` before dialing for an unknown `auth_mechanism`, a
 - `prepare_server(sql) → [id, nparams] | nil` — prepare a statement with `?`
   placeholders on the server; `nil` when the server refuses. Cached per
   connection (240 entries); the cache is cleared on re-dial.
-- `stream(sql, consistency: nil) { |row| … } → Result` — see
-  [streaming.md](streaming.md). For a row stream the returned Result has
+- `stream(sql, params = [], consistency: nil) { |row| … } → Result` — see
+  [streaming.md](streaming.md). `params` (an Array) bind `$1`, `$2`, …
+  exactly as `exec_params` binds them, typed, over `OP_QUERY_STREAM_PARAMS`
+  (server ≥ 0.330; an older one raises `QueryError` `server does not support
+  parameterised streaming (skaidb >= 0.330): …`, with no text fallback);
+  without parameters (`nil` or `[]`) the request is the original
+  `OP_QUERY_STREAM`, which every server understands. A placeholder/parameter
+  mismatch or a value that cannot be bound raises `QueryError` before
+  anything is sent, and `params` that are not an Array raise
+  `ArgumentError`. For a row stream the returned Result has
   `kind == :stream`, the column names in `fields` and no `rows` (they went to
   the block); a statement without rows returns its `:mutation` / `:ddl`
   Result without yielding. Without a block returns an Enumerator.

data/docs/pooling.md

@@ -122,6 +122,12 @@ latest writer — pass a key when you balance. A statement is a write unless
 its first keyword (after whitespace, comments and opening parentheses) is
 `SELECT`, `SHOW`, `EXPLAIN`, `DESCRIBE`, `DESC`, `VALUES`, `WITH` or `USE`.
 
+Derive the key without touching the pool: if it comes from something that
+itself queries the database through the same pool (a web framework's
+"current user" loader), a helper that checks out a connection and computes
+the key inside it re-enters itself. Read the raw id from the session or
+token instead.
+
 **Watching it.** `pool.members` returns one Hash per member, sorted by
 endpoint:
 

data/docs/streaming.md

@@ -4,7 +4,12 @@
 a result that should not be held in memory at once, `stream` runs the
 statement over the protocol's streaming opcode: the server answers with a
 header (the column names), then row chunks, then an end marker, and the
-driver yields rows as each chunk arrives, holding one chunk at a time.
+driver yields rows as each chunk arrives, holding one chunk at a time. The
+server executes a plain `SELECT` (bare columns from one table, unordered or
+in storage-key order) page by page, and no scan budget applies to a
+streamed page (server ≥ 0.330; `EXPLAIN` says whether a statement pages, and
+the rules are under "Streamed queries" in the server's
+[SQL syntax reference](https://skaidb.org/docs/query_syntax.html)).
 
 ```ruby
 conn.stream("SELECT id, payload FROM events ORDER BY id") do |row|
@@ -12,7 +17,9 @@ conn.stream("SELECT id, payload FROM events ORDER BY id") do |row|
 end
 ```
 
-- `stream(sql, consistency: nil)` takes SQL text only — no parameters.
+- `stream(sql, params = [], consistency: nil)`: `params` bind `$1`, `$2`, …
+  exactly as `exec_params` binds them ([Parameters](#parameters), below);
+  `consistency:` overrides the connection's level for this statement.
 - With a block it returns a `Skaidb::Result` after the last row: `kind` is
   `:stream`, `fields` holds the column names (known even when no row
   arrived), and `rows` is empty because the rows went to the block.
@@ -24,6 +31,34 @@ end
 - A server without the streaming opcode raises `Skaidb::QueryError`
   (`server does not support streaming: …`).
 
+## Parameters
+
+`params` bind the statement's `$1`, `$2`, … placeholders exactly as
+`exec_params` binds them: typed, with every value [types.md](types.md) lists
+(Arrays, Hashes, `Time`, `BigDecimal`, `Skaidb::Uuid`, …), the same `$N` as
+often as you like, and the same checks before anything is sent (a
+placeholder without a parameter, a parameter no placeholder uses, a bare
+`?`).
+
+```ruby
+conn.stream("SELECT id, ts, body FROM events WHERE ts >= $1 AND ts < $2", [from, to]) do |row|
+  export(row)
+end
+
+conn.stream("SELECT id, v FROM t WHERE tenant = $1", [tenant], consistency: :one).each_slice(1000) do |batch|
+  load(batch)
+end
+```
+
+They travel in `OP_QUERY_STREAM_PARAMS`, which needs a server ≥ 0.330. An
+older server refuses it, and `stream` raises `Skaidb::QueryError`
+(`server does not support parameterised streaming (skaidb >= 0.330): …`);
+the connection stays usable. Unlike `exec_params` there is no client-side
+text fallback. A stream without parameters (`nil` or `[]`) sends the
+original `OP_QUERY_STREAM` with the SQL untouched, so it works against every
+server. `params` must be an Array — anything else raises `ArgumentError`;
+the consistency is only ever the `consistency:` keyword.
+
 ## Errors mid-stream
 
 The server can fail a statement after it has started sending rows (a node

data/docs/types.md

@@ -1,8 +1,9 @@
 # Types
 
 Results decode from skaidb's typed wire values; parameters encode back to
-them when a statement is prepared, which is the normal path whenever you pass
-values to `exec_params` or `exec_batch`.
+them — when a statement is prepared, which is the normal path whenever you
+pass values to `exec_params` or `exec_batch`, and always for the values you
+pass to `stream`.
 
 | skaidb type | Result value | Accepted as a parameter |
 |---|---|---|

data/lib/skaidb.rb

@@ -25,7 +25,8 @@
 # Placeholders use the pg-style +$1+, +$2+, ... . They are sent as TYPED values
 # through a server-side prepared statement where the server accepts one, and
 # interpolated into the SQL client-side, with correct quoting, where it does not
-# (old servers, and statement kinds that cannot be prepared).
+# (old servers, and statement kinds that cannot be prepared). +stream+ sends
+# its parameters typed in the stream request itself and never interpolates.
 require "socket"
 require "openssl"
 require "securerandom"
@@ -34,7 +35,7 @@ require "bigdecimal"
 module Skaidb
   # The package version — the single source of truth. The gemspec reads it,
   # and it is what the driver reports to the server in the Hello frame.
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 
   # Base class for every error raised by this driver.
   class Error < StandardError; end
@@ -930,6 +931,17 @@ module Skaidb
     # large scans.
     #
     #   conn.stream("SELECT ...") { |row| puts row["id"] }
+    #   conn.stream("SELECT id, ts FROM events WHERE ts >= $1 AND ts < $2", [from, to]) { |row| ... }
+    #
+    # +params+ bind +$1+, +$2+, ... exactly as +exec_params+ binds them —
+    # typed, the same values accepted (Arrays, Hashes, Times, ...), the same
+    # placeholder checks — and travel in OP_QUERY_STREAM_PARAMS, which needs
+    # a server >= 0.330: an older one answers QueryError "server does not
+    # support parameterised streaming (skaidb >= 0.330): ..." and the
+    # connection stays usable. Unlike +exec_params+ there is no client-side
+    # text fallback. Without parameters (+nil+ or +[]+) the request is the
+    # original OP_QUERY_STREAM with the SQL untouched, so a parameterless
+    # stream works against every server.
     #
     # The protocol forbids any other request on the connection until the
     # stream ends, so the whole exchange runs under the connection mutex
@@ -962,16 +974,21 @@ module Skaidb
     # no row arrived) while +rows+ stays empty — the rows went to the block;
     # a statement that produces no rows returns its ordinary +:mutation+ or
     # +:ddl+ Result without yielding.
-    #
-    # Takes no parameters — the streaming opcode carries SQL text.
-    def stream(sql, consistency: nil)
-      return enum_for(:stream, sql, consistency: consistency) unless block_given?
+    def stream(sql, params = [], consistency: nil)
+      return enum_for(:stream, sql, params, consistency: consistency) unless block_given?
       raise ConnectionError, "connection is closed" if @closed
-      ensure_live!
 
       level = consistency.nil? ? @consistency : Consistency.resolve(consistency)
-      sql_bytes = sql.dup.force_encoding("UTF-8").b
-      req = [5, level].pack("CC") + [sql_bytes.bytesize].pack("V") + sql_bytes
+      params ||= []
+      unless params.is_a?(Array)
+        raise ArgumentError, "stream params must be an Array, got #{params.class} " \
+                             "(the consistency is a keyword: stream(sql, consistency: :one))"
+      end
+      # Built before anything touches the socket, so a parameter that cannot
+      # be bound is refused without a round trip (or a re-dial).
+      req = stream_request(sql, params, level)
+      ensure_live!
+
       live = false
       summary = nil
       @mutex.synchronize do
@@ -989,7 +1006,11 @@ module Skaidb
         case tag
         when 3
           msg = r.text
-          raise QueryError, msg.include?("unknown opcode") ? "server does not support streaming: #{msg}" : msg
+          if msg.include?("unknown opcode")
+            what = params.empty? ? "streaming" : "parameterised streaming (skaidb >= 0.330)"
+            raise QueryError, "server does not support #{what}: #{msg}"
+          end
+          raise QueryError, msg
         when 1
           return Result.new(fields: [], rows: [], cmd_tuples: r.u64, kind: :mutation) # not row-producing
         when 2
@@ -1311,6 +1332,30 @@ module Skaidb
       res
     end
 
+    # The request +stream+ sends. Without parameters: OP_QUERY_STREAM with
+    # the SQL as given, byte for byte what every server understands. With
+    # them: OP_QUERY_STREAM_PARAMS (server >= 0.330), $N rewritten to the
+    # positional ? and the values typed in ? order — the parameter vector
+    # OP_EXECUTE carries (u16 count, then u32 length + value each).
+    def stream_request(sql, params, level)
+      if params.empty?
+        sql_bytes = sql.dup.force_encoding("UTF-8").b
+        return [5, level].pack("CC") + [sql_bytes.bytesize].pack("V") + sql_bytes
+      end
+
+      qsql, order = Skaidb.to_qmark(sql.to_s, params)
+      # The count is a u16 on the wire, and pack would wrap a larger one.
+      raise QueryError, "a statement takes at most 65535 parameters, got #{order.length}" if order.length > 0xFFFF
+
+      sql_bytes = qsql.dup.force_encoding("UTF-8").b
+      req = +([9, level].pack("CC") + [sql_bytes.bytesize].pack("V") + sql_bytes + [order.length].pack("v"))
+      order.each do |p|
+        b = Skaidb.encode_value(p)
+        req << [b.bytesize].pack("V") << b
+      end
+      req
+    end
+
     # One request and its response under the connection mutex. In a pool the
     # round trip (send to the first response frame) feeds the member's
     # latency average, and a transport failure counts against the member.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: skaidb
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - skaidb contributors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal