skaidb 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4524df0a2c1434d82de3ae0e2202e408ce54a9ea2a0b2f892247e6623b739e3c
-  data.tar.gz: 0c1431641d973133fce8fb4e5fb965c7fbf3730a239250f1b3773cbcf1c5da51
+  metadata.gz: a452610f682221a59cfbbc48e42c9a37f1c0e880d2191037f1c9c7151a3034fa
+  data.tar.gz: 1a73f7f552091bfaed9b4072dfd684b57daac637ff12d163a34bf1c278bef784
 SHA512:
-  metadata.gz: f4f4b9390ed85e9504f325b14b8ae1a9f8f4b54edfd9622e2bc514b0d47b208e763f46887016388ffc6db20625e14ea6a9dda26e5d53daa6fa86f5addbd6b992
-  data.tar.gz: 8afeaab18359327ad49ff27d07227068e6243b1c2ae4df6da6ed0ee44d87233cebb12d00601c0f930fdbe715f0fbe467ba2034bb70f92e8880fa44dbc7ebe3dd
+  metadata.gz: ce44a1e28e0add382aa9fde578eb09350e1b5306d22c3cf5d272faa5d606c8ec05be08b77967d014a33ceddba5fefd0ed449503c24d4997680c37af156ad2e5f
+  data.tar.gz: 3d34175d862982988e593fb42c631bdbb9cd6f23682908ec40fc53a7d25fe3868105201dd50988108508783bfb8bf076065737864d71c6cc5337c8b6c371e6c3

data/CHANGELOG.md

@@ -4,6 +4,50 @@ 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
+- **Pool load balancing across members** (the rules every skaidb driver
+  shares, PROTOCOL.md §6.1): `load_balancing: :round_robin` /
+  `:least_latency` (power of two choices on the round-trip average ×
+  checked-out connections, re-measuring a member not used in the last 2 s;
+  `:random` stays the default), `idle_order: :fifo`, health ejection
+  (consecutive transport failures, or a latency average far above the other
+  members') with a background probe that re-admits the member,
+  `discover: true` (members from `SHOW ENDPOINTS`, server ≥ 0.327: joiners
+  added, leavers dropped, resyncing/unreachable members skipped and
+  re-checked every 5 s), and `read_your_writes: <seconds>` with
+  `checkout(affinity: key)` / `with(affinity: key)` — reads follow the member
+  that took the key's last write. `pool.members` reports each member's
+  state, latency and connections; `logger:` is told of ejections and
+  re-admissions. Options take Symbols or Strings.
+- `Connection#endpoint`: the `"host:port"` of the member a connection reached.
+
+### Changed
+- A pooled connection that re-dials does so in the pool's order (usable
+  members first, the one it lost last) instead of shuffling the seeds.
+- `Skaidb::Pool.new` checks its `Skaidb.connect` keywords when it is created
+  instead of at the first checkout, and a connection checked in to a pool
+  that did not create it is closed instead of kept.
+
 ## [1.1.0] - 2026-09-26
 
 ### Added
@@ -148,6 +192,9 @@ 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
 [1.0.2]: https://github.com/porcupin26/skaidb-ruby/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/porcupin26/skaidb-ruby/compare/v1.0.0...v1.0.1

data/README.md

@@ -13,7 +13,8 @@ and the result behaves like `PG::Result`. **Pure standard library** (`socket`,
 Ruby 2.7 through 3.4. It speaks skaidb's binary protocol directly:
 SCRAM-SHA-256 authentication, server-side prepared statements with typed
 parameters, one-round-trip batches, streamed result sets, multi-seed failover,
-transparent reconnect, TLS and connection pooling.
+transparent reconnect, TLS and a connection pool that balances across the
+cluster's members.
 
 - Repository: <https://github.com/porcupin26/skaidb-ruby>
 - RubyGems: <https://rubygems.org/gems/skaidb>
@@ -54,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.1.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.1.0.gem`.
+installs without registry access: `gem install ./skaidb-1.3.0.gem`.
 
 ## Quick start
 
@@ -98,7 +99,8 @@ end
   prepared statements, `exec_batch`
 - [Results](#results)
 - [Streaming large results](#streaming-large-results)
-- [Connection pool](#connection-pool)
+- [Connection pool](#connection-pool) — balancing across members,
+  health ejection, discovery, read-your-writes
 - [Streams (`CREATE STREAM`)](#streams-create-stream) — `subscribe`
 - [Type mapping](#type-mapping)
 - [Errors](#errors)
@@ -278,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|
@@ -287,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 —
@@ -321,7 +335,29 @@ pool.close                                    # closes idle connections
 blocks — when no idle connection is available a new one is dialed, and a
 returned connection beyond `maxsize` is closed. Connections are validated with
 `usable?` on checkout and check-in, so one broken by a transport error or an
-undrained stream is closed and replaced. Details: [docs/pooling.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/pooling.md).
+undrained stream is closed and replaced.
+
+The pool spreads its connections across the members by the rules every skaidb
+driver shares
+([PROTOCOL.md §6.1](https://skaidb.org/docs/PROTOCOL.html#61-balancing-a-pool-across-members)):
+
+```ruby
+pool = Skaidb::Pool.new(seeds: ["db1", "db2", "db3"], database: "app",
+                        load_balancing: :least_latency, # or :round_robin; :random is the default
+                        discover: true,                 # members from SHOW ENDPOINTS, resyncing ones skipped
+                        read_your_writes: 2.0)          # seconds; see affinity below
+
+pool.with(affinity: user_id) { |conn| conn.exec_params("INSERT INTO notes (id, owner) VALUES ($1, $2)", [nid, user_id]) }
+pool.with(affinity: user_id) { |conn| conn.exec_params("SELECT * FROM notes WHERE id = $1", [nid]) } # same member
+
+pool.members # => [{ endpoint: "db1:7000", canonical: "10.0.0.1:7000", state: :ready,
+             #      latency_ms: 0.8, in_use: 2, idle: 3, seed: true }, …]
+```
+
+A member with consecutive transport failures, or a round-trip average far
+above the others', is ejected and re-admitted by a background probe (the last
+usable member never is); `idle_order: :fifo` keeps every idle connection in
+use. Details: [docs/pooling.md](https://github.com/porcupin26/skaidb-ruby/blob/main/docs/pooling.md).
 
 ## Streams (`CREATE STREAM`)
 
@@ -393,8 +429,9 @@ StandardError
   connection stays usable.
 - A transport failure (`ConnectionError`) marks the connection broken; the
   next statement re-dials, or a pool replaces it.
-- `ArgumentError` for `Pool.new(maxsize: 0)` and for `Skaidb::Uuid.new` of a
-  string that is not a UUID.
+- `ArgumentError` for `Pool.new(maxsize: 0)` or an unknown
+  `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
 
@@ -421,7 +458,7 @@ frame after every handshake. It shows up as `client_name = 'ruby'` /
 
 ```sql
 SELECT client_name, client_version FROM drivers;
--- ruby | 1.1.0
+-- ruby | 1.3.0
 ```
 
 The server records the row asynchronously, so a `SELECT` immediately after
@@ -434,8 +471,10 @@ know the opcode answers with an error the driver ignores.
   `bigdecimal` is declared because it is a bundled gem since Ruby 3.4.
 - Works with any skaidb server. Where a server predates an opcode the driver
   falls back: prepared statements → client-side text binding, `Hello` →
-  ignored. `stream` and `exec_batch` need a server with those opcodes and
-  raise `QueryError` otherwise.
+  ignored, pool discovery (`SHOW ENDPOINTS`, server ≥ 0.327) → the
+  configured seeds. `stream` and `exec_batch` need a server with those
+  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.
@@ -73,6 +81,8 @@ Raises `Skaidb::Error` before dialing for an unknown `auth_mechanism`, a
 - `usable?` — `false` once closed, once a transport error broke the socket,
   or while a stream is in flight (including one abandoned through external
   iteration). No round-trip.
+- `endpoint` — the member the connection reached, as the `"host:port"` it
+  dialed (it changes when a re-dial lands on another member).
 - `closed`, `finished?` — `true` after `close`.
 - `close` — closes the socket; idempotent. Does not take the connection's
   lock, so another thread can use it to break a blocked read.
@@ -81,10 +91,11 @@ Raises `Skaidb::Error` before dialing for an unknown `auth_mechanism`, a
 
 A transport failure raises `Skaidb::ConnectionError` and marks the
 connection broken. The next `exec`/`exec_params`/`exec_batch`/`stream`
-re-dials across the original seeds, re-authenticates, re-sends `Hello`,
-re-runs `USE`, and starts with an empty prepared-statement cache. If the
-re-dial fails, that statement raises `ConnectionError` and the one after it
-tries again.
+re-dials across the original seeds (a pooled connection: in the pool's
+order, usable members first and the one it lost last), re-authenticates,
+re-sends `Hello`, re-runs `USE`, and starts with an empty prepared-statement
+cache. If the re-dial fails, that statement raises `ConnectionError` and the
+one after it tries again.
 
 ## `Skaidb::Result`
 
@@ -105,10 +116,33 @@ Shaped like `PG::Result`; `Enumerable` over row Hashes.
 
 ## `Skaidb::Pool`
 
-`Skaidb::Pool.new(maxsize: 10, **connect_options)` — see
-[pooling.md](pooling.md). `with { |conn| }`, `checkout`, `checkin(conn)`,
-`close`. Raises `ArgumentError` for `maxsize < 1` and `Skaidb::Error` on
-checkout from a closed pool.
+```ruby
+Skaidb::Pool.new(maxsize: 10, load_balancing: :random, idle_order: :lifo, discover: false,
+                 refresh_interval: 60.0, read_your_writes: 0.0, eject_errors: 3,
+                 eject_latency_factor: 3.0, eject_latency_floor: 0.05, eject_backoff: 5.0,
+                 eject_backoff_max: 60.0, logger: nil, **connect_options)
+```
+
+A thread-safe pool balanced across the cluster's members — see
+[pooling.md](pooling.md) for every option.
+
+- `with(affinity: nil) { |conn| … }` — check out, yield, check in; returns
+  the block's value.
+- `checkout(affinity: nil) → Connection` — an idle connection to the member
+  the policy picks, or a new one. Never blocks. `affinity` (any Hash key;
+  `nil` = pool-wide) scopes `read_your_writes`.
+- `checkin(conn)` — return it; closed instead when broken, when its member
+  is ejected or gone, or when `maxsize` are already idle.
+- `members → Array<Hash>` — per member: `:endpoint`, `:canonical`, `:state`
+  (`:ready`, `:ejected`, `:resyncing`, `:unreachable`, `:unlisted`),
+  `:latency_ms` (`nil` until measured), `:in_use`, `:idle`, `:seed`.
+- `close` — closes the idle connections and stops the background thread.
+
+`load_balancing` (`:random`, `:round_robin`, `:least_latency`) and
+`idle_order` (`:lifo`, `:fifo`) take a Symbol or a String. Raises
+`ArgumentError` for `maxsize < 1`, `eject_errors < 1` or an unknown
+`load_balancing`/`idle_order`, and `Skaidb::Error` on checkout from a closed
+pool.
 
 ## `Skaidb::Uuid`
 

data/docs/pooling.md

@@ -2,7 +2,9 @@
 
 `Skaidb::Pool` keeps a bounded set of idle connections and hands one to each
 caller, so a threaded server or job runner can use one connection per
-thread without dialing and authenticating on every request.
+thread without dialing and authenticating on every request. It spreads its
+connections across the cluster's members by the rules every skaidb driver
+shares.
 
 ```ruby
 pool = Skaidb::Pool.new(seeds: ["db1", "db2", "db3"], user: "app", password: "secret",
@@ -22,11 +24,126 @@ end
 pool.close                                   # closes every idle connection
 ```
 
+## API
+
+```ruby
+Skaidb::Pool.new(
+  maxsize: 10,
+  load_balancing: :random,      # :random | :round_robin | :least_latency
+  idle_order: :lifo,            # :lifo | :fifo
+  discover: false,              # read the members from SHOW ENDPOINTS
+  refresh_interval: 60.0,       # seconds between discovery refreshes
+  read_your_writes: 0.0,        # seconds; 0 = off
+  eject_errors: 3,              # consecutive transport failures
+  eject_latency_factor: 3.0,    # x the other members' median; 0 = off
+  eject_latency_floor: 0.05,    # seconds above the median, at least
+  eject_backoff: 5.0,           # first ejection, doubling per repeat
+  eject_backoff_max: 60.0,
+  logger: nil,                  # anything with #warn: ejections, re-admissions
+  **connect_options             # every Skaidb.connect keyword
+)
+
+pool.with(affinity: nil) { |conn| … }   # the block's value
+pool.checkout(affinity: nil)  -> Skaidb::Connection
+pool.checkin(conn)
+pool.members                  -> Array of Hashes (see "Watching it")
+pool.close
+```
+
+`load_balancing` and `idle_order` take a Symbol or a String. `host`/`port`/
+`seeds` name the starting members; the other `Skaidb.connect` keywords
+(`database`, TLS, `consistency`, `timeout`) apply to every connection, so
+pooled connections run `USE` and authenticate exactly like single ones. A
+pooled connection that re-dials after a transport error does so in the
+pool's order: usable members first, the one it lost last.
+`Connection#endpoint` names the member a connection reached.
+
+## Balancing across members
+
+With the default `load_balancing: :random` each new connection dials the
+members in random order and stays on the member it reached — fine for many
+clients, but one process can end up with most of its connections on one
+member. Pick a policy to spread a single process's load:
+
+```ruby
+pool = Skaidb::Pool.new(
+  seeds: ["db1", "db2", "db3"], database: "app", user: "app", password: pw,
+  load_balancing: :least_latency, # or :round_robin
+  discover: true,                 # learn the members from the cluster
+  read_your_writes: 2.0,          # seconds; see below
+  idle_order: :fifo
+)
+```
+
+| Option | Default | What it does |
+|---|---|---|
+| `load_balancing` | `:random` | `:round_robin`: checkouts rotate over the usable members in endpoint order. `:least_latency`: of two members picked at random, the one with the lower round-trip average × (checked-out connections + 1), so near and idle members win; a member not measured yet, or not in the last 2 s, scores 0 and is tried, so a lightly loaded pool keeps re-measuring every member. |
+| `idle_order` | `:lifo` | `:lifo` hands out the most recently returned connection first, so a quiet pool keeps few sockets warm. `:fifo` hands out the longest-idle one first, so every idle connection keeps being used and a server-side idle timeout never finds one. |
+| `discover` | `false` | Reads the members with `SHOW ENDPOINTS` (server ≥ 0.327; no privilege needed) when a member is first reached and every `refresh_interval` (60 s) after — every 5 s while a member is `resyncing` or `unreachable`. New members are added, members that left are dropped (seeds are kept, marked `unlisted`), and members the server reports `resyncing` or `unreachable` get no new connections until they are `ready` again, when they start with a fresh latency average. An older or standalone server leaves the seeds as they are, and the pool stops asking. |
+| `eject_errors` | `3` | Consecutive transport failures (a failed dial, an I/O error mid-request, a capacity refusal) that eject a member. Statement errors and refused logins do not count. |
+| `eject_latency_factor`, `eject_latency_floor` | `3.0`, `0.05` | A member whose round-trip average is above factor × the other usable members' median **and** more than floor seconds above it is ejected (once it and another member have 10 samples each). A factor of `0` disables it. |
+| `eject_backoff`, `eject_backoff_max` | `5.0`, `60.0` | How long an ejection lasts, doubling for each repeat up to the max; a member that stays healthy for `eject_backoff_max` after a re-admission starts over at the base. When the time is up a background thread dials the member and runs one statement: success re-admits it (with a fresh latency average), failure ejects it again. The last usable member is never ejected — a slow or flaky member beats none. |
+| `read_your_writes` | `0.0` | Seconds after a write during which checkouts with the same `affinity` go to the member that took the write. |
+| `logger` | `nil` | A `Logger` (or anything with `warn`) told of each ejection and re-admission. |
+
+An ejected member gets no new connections and its idle ones are closed; a
+connection to it that is returned to the pool is closed instead of kept.
+With a target member (round-robin, least-latency, an affinity) the pool
+hands out an idle connection to that member or dials it; a failed dial falls
+through to the other usable members, then to the unusable ones, so a
+checkout never has nowhere to go while any member is configured.
+
+**Latency.** Per member the pool keeps an exponentially weighted average of
+round trips (request sent to the first response frame): each sample moves it
+5 % of the way, and no sample counts for more than 10 × the larger of the
+current average and `eject_latency_floor`. One slow statement barely moves
+it; a member that stays slow is noticed within a few dozen statements.
+
+**Read-your-writes.** The member that coordinated a write reads it back at
+any consistency, `ONE` included; another member may not have applied it yet.
+With `read_your_writes` set, pass an affinity key — a user or session id —
+when you check out:
+
+```ruby
+pool.with(affinity: user_id) do |conn|
+  conn.exec_params("INSERT INTO notes (id, owner, body) VALUES ($1, $2, $3)", [nid, user_id, body])
+end
+# … the next request for the same user, within the window:
+pool.with(affinity: user_id) do |conn|        # same member
+  conn.exec_params("SELECT body FROM notes WHERE id = $1", [nid])
+end
+```
+
+The window starts when a write succeeds on a connection checked out under
+the key, and checkouts under it go to that member until the window ends
+(unless the member is ejected or not `ready`). Checkouts without a key
+share one pool-wide key, so with constant writes everything follows the
+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:
+
+```ruby
+[{ endpoint: "db1:7000", canonical: "10.0.0.1:7000", state: :ready,
+   latency_ms: 0.8, in_use: 2, idle: 3, seed: true }, …]
+```
+
+`endpoint` is what the pool dials, `canonical` the name the member reports
+for itself (once discovered), `state` one of `:ready`, `:ejected`,
+`:resyncing`, `:unreachable`, `:unlisted`, and `latency_ms` is `nil` until
+the member has been measured. The rules are the same in every skaidb driver
+([PROTOCOL.md §6.1](https://skaidb.org/docs/PROTOCOL.html#61-balancing-a-pool-across-members)).
+
 ## Behaviour
 
-- Every `Skaidb.connect` keyword passes through (`seeds`, `database`, TLS,
-  `consistency`, `timeout`), so pooled connections fail over across seeds
-  and run `USE` exactly like single ones.
 - `maxsize` (default 10) bounds the connections kept **idle**, not the number
   checked out. `checkout` never blocks: with no idle connection available it
   dials a new one, and a connection returned while `maxsize` are already idle
@@ -38,10 +155,15 @@ pool.close                                   # closes every idle connection
   and will fail its first statement with `Skaidb::ConnectionError`; that
   failure marks it broken, so `checkin` discards it and the next checkout
   gets a fresh one. Retry the statement in that case if it is safe to.
-- `close` marks the pool closed and closes the idle connections; connections
-  checked out at the time are closed when they are returned. `checkout` on a
-  closed pool raises `Skaidb::Error`. `maxsize < 1` raises `ArgumentError`.
-- The pool is thread-safe. A single connection should still be used by one
-  thread at a time; the pool is what gives each thread its own.
+- `close` marks the pool closed, closes the idle connections and stops the
+  background thread; connections checked out at the time are closed when
+  they are returned. `checkout` on a closed pool raises `Skaidb::Error`.
+  `maxsize < 1`, `eject_errors < 1` and an unknown `load_balancing` or
+  `idle_order` raise `ArgumentError`.
+- The pool is thread-safe: the idle list and the member table are guarded
+  by one mutex. The background thread (probes and discovery refreshes) is
+  started on first need; Ruby never waits for it at exit. A single
+  connection should still be used by one thread at a time; the pool is what
+  gives each thread its own.
 
 See also `examples/pool.rb`.

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 |
 |---|---|---|