skaidb 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4524df0a2c1434d82de3ae0e2202e408ce54a9ea2a0b2f892247e6623b739e3c
-  data.tar.gz: 0c1431641d973133fce8fb4e5fb965c7fbf3730a239250f1b3773cbcf1c5da51
+  metadata.gz: 7a9f39f07d8b6d8abb6edf43d48b4c70da568b4a66f62044fb6f36d7b7b0e1ae
+  data.tar.gz: bb205511e213fe77efcfbaff5c17b82c453fcc2135cee1c362e154b9ad169e6f
 SHA512:
-  metadata.gz: f4f4b9390ed85e9504f325b14b8ae1a9f8f4b54edfd9622e2bc514b0d47b208e763f46887016388ffc6db20625e14ea6a9dda26e5d53daa6fa86f5addbd6b992
-  data.tar.gz: 8afeaab18359327ad49ff27d07227068e6243b1c2ae4df6da6ed0ee44d87233cebb12d00601c0f930fdbe715f0fbe467ba2034bb70f92e8880fa44dbc7ebe3dd
+  metadata.gz: 9ce5348688c5bd6cd480006b2fa567ed7af74cc0ffe557f387d55705effd49dcbd754b8c52b32a30ae3361234226e4a82828bff7dc0d3d43f9a03e086849c53b
+  data.tar.gz: e7d6fd76c93392bbea0e2583b5741b418188c4d045d0226d7e8d0dcf2828fbe4cd03e34a32da58598d0173d81875cf8b1fe5b405c64e0ac658c108be67adf1da

data/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.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 +174,8 @@ 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.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.2.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.2.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)
@@ -321,7 +323,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 +417,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`, and for `Skaidb::Uuid.new` of a string that
+  is not a UUID.
 
 ## Transactions
 
@@ -421,7 +446,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.2.0
 ```
 
 The server records the row asynchronously, so a `SELECT` immediately after
@@ -434,8 +459,9 @@ 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 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

@@ -73,6 +73,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 +83,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 +108,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,120 @@ 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`.
+
+**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 +149,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/lib/skaidb.rb

@@ -34,7 +34,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.1.0"
+  VERSION = "1.2.0"
 
   # Base class for every error raised by this driver.
   class Error < StandardError; end
@@ -677,11 +677,28 @@ module Skaidb
   class Connection
     # @return [Boolean] whether the connection has been closed
     attr_reader :closed
-
+    # @return [String, nil] the member this connection reached, as the
+    #   "host:port" it dialed (nil until it connects)
+    attr_reader :endpoint
+    # Internal, for Pool: the pool told of this connection's round trips,
+    # transport failures and writes, and asked for the dial order when it
+    # re-dials (nil outside a pool); the member the pool counts it against;
+    # the affinity key it was checked out under; whether it is checked out.
+    attr_accessor :observer, :pool_member, :pool_affinity, :pool_out
+
+    # +endpoints+ and +observer+ are internal, for Pool: an explicit dial
+    # order of [host, port] pairs (no shuffle) and the pool that owns the
+    # connection.
     def initialize(host:, port:, user:, password:, consistency:, timeout:,
                    database: nil, tls: false, tls_ca: nil, tls_insecure: false,
                    tls_server_name: "skaidb", seeds: nil, tls_client_cert: nil,
-                   tls_client_key: nil, auth_mechanism: :scram)
+                   tls_client_key: nil, auth_mechanism: :scram, endpoints: nil,
+                   observer: nil)
+      @observer = observer
+      @endpoint = nil
+      @pool_member = nil
+      @pool_affinity = nil
+      @pool_out = false
       @consistency = Consistency.resolve(consistency)
       @auth_mechanism = AuthMechanism.resolve(auth_mechanism)
       if tls_client_cert.to_s.empty? != tls_client_key.to_s.empty?
@@ -704,7 +721,7 @@ module Skaidb
                      timeout: timeout, database: database, tls: tls, tls_ca: tls_ca,
                      tls_insecure: tls_insecure, tls_server_name: tls_server_name,
                      seeds: seeds, tls_client_cert: tls_client_cert,
-                     tls_client_key: tls_client_key }
+                     tls_client_key: tls_client_key, endpoints: endpoints }
       dial!
     end
 
@@ -726,11 +743,19 @@ module Skaidb
       # Seeds: try each until one connects AND authenticates — a node that
       # accepts TCP while unhealthy must not swallow the attempt. skaidb is
       # leaderless, so any node serves; the order is shuffled so many
-      # clients spread instead of stampeding the first entry.
-      endpoints = (seeds && !seeds.empty? ? seeds : ["#{host}:#{port}"]).map do |sd|
-        h, _, p = sd.to_s.rpartition(":")
-        h.empty? ? [sd.to_s, port] : [h, p.to_i]
-      end.shuffle
+      # clients spread instead of stampeding the first entry. A pooled
+      # connection dials in the pool's order instead: the member the pool
+      # picked first, and on a re-dial the usable members with the one it
+      # lost last.
+      endpoints = if @observer && @endpoint
+                    @observer.dial_order(@endpoint)
+                  elsif @dial_args[:endpoints]
+                    @dial_args[:endpoints]
+                  else
+                    (seeds && !seeds.empty? ? seeds : ["#{host}:#{port}"]).map do |sd|
+                      Skaidb.parse_endpoint(sd, port)
+                    end.shuffle
+                  end
       last = nil
       endpoints.each do |(h, prt)|
         begin
@@ -745,10 +770,12 @@ module Skaidb
           else
             handshake(user.to_s, password.to_s)
           end
+          @endpoint = "#{h}:#{prt}"
           last = nil
           break
         rescue StandardError => e
           last = e
+          @observer.note_failure("#{h}:#{prt}") if @observer && Skaidb.member_fault?(e)
           begin
             @sock&.close
           rescue StandardError
@@ -848,7 +875,9 @@ module Skaidb
             raise QueryError, "statement expects #{nparams} parameters, got #{order.length}"
           end
 
-          return exec_prepared(id, order, level)
+          res = exec_prepared(id, order, level)
+          note_statement(sql)
+          return res
         end
       end
       text = begin
@@ -890,12 +919,10 @@ module Skaidb
           req << [b.bytesize].pack("V") << b
         end
       end
-      reader = nil
-      @mutex.synchronize do
-        write_frame(req)
-        reader = Reader.new(read_frame)
-      end
-      parse_response(reader).cmd_tuples
+      reader = request(req)
+      n = parse_response(reader).cmd_tuples
+      note_statement(sql)
+      n
     end
 
     # Stream a result set: yields one row Hash at a time while holding a
@@ -948,9 +975,17 @@ module Skaidb
       live = false
       summary = nil
       @mutex.synchronize do
-        write_frame(req)
-        r = Reader.new(read_frame)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        begin
+          write_frame(req)
+          r = Reader.new(read_frame)
+        rescue ConnectionError
+          observe_failure
+          raise
+        end
+        @observer&.note_round_trip(self, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
         tag = r.u8
+        note_statement(sql) unless tag == 3
         case tag
         when 3
           msg = r.text
@@ -1023,11 +1058,7 @@ module Skaidb
 
       sql_bytes = sql.dup.force_encoding("UTF-8").b
       req = [2].pack("C") + [sql_bytes.bytesize].pack("V") + sql_bytes
-      reader = nil
-      @mutex.synchronize do
-        write_frame(req)
-        reader = Reader.new(read_frame)
-      end
+      reader = request(req)
       tag = reader.u8
       case tag
       when 4
@@ -1055,11 +1086,7 @@ module Skaidb
         v = Skaidb.encode_value(p)
         req << [v.bytesize].pack("V") << v
       end
-      reader = nil
-      @mutex.synchronize do
-        write_frame(req)
-        reader = Reader.new(read_frame)
-      end
+      reader = request(req)
       parse_response(reader)
     end
 
@@ -1113,6 +1140,9 @@ module Skaidb
       rescue StandardError
         # ignore — socket already gone
       end
+      # Closed while checked out instead of returned: the pool stops
+      # counting it against its member.
+      @observer.note_closed(self) if @observer && @pool_out
       nil
     end
 
@@ -1275,12 +1305,38 @@ module Skaidb
 
       sql_bytes = sql.dup.force_encoding("UTF-8").b
       req = [1, consistency].pack("CC") + [sql_bytes.bytesize].pack("V") + sql_bytes
-      reader = nil
-      @mutex.synchronize do
-        write_frame(req)
-        reader = Reader.new(read_frame)
+      reader = request(req)
+      res = parse_response(reader)
+      note_statement(sql)
+      res
+    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.
+    def request(req)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      frame = begin
+        @mutex.synchronize do
+          write_frame(req)
+          read_frame
+        end
+      rescue ConnectionError
+        observe_failure
+        raise
       end
-      parse_response(reader)
+      @observer&.note_round_trip(self, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+      Reader.new(frame)
+    end
+
+    def observe_failure
+      @observer.note_failure(@endpoint) if @observer && @endpoint
+    end
+
+    # A statement succeeded: a pool with read-your-writes on remembers which
+    # member took a write.
+    def note_statement(sql)
+      @observer&.note_statement(self, sql)
     end
 
     def parse_response(r)
@@ -1338,23 +1394,8 @@ module Skaidb
   #   is optional and, when given, must equal the certificate's Common Name)
   # @yield [conn] optional block; the connection is closed when it returns
   # @return [Connection] (or the block's value when a block is given)
-  def self.connect(host: "localhost", port: 7000, user: nil,
-                   password: "", consistency: :quorum, timeout: 10.0,
-                   database: nil, tls: false, tls_ca: nil, tls_insecure: false,
-                   tls_server_name: "skaidb", seeds: nil, tls_client_cert: nil,
-                   tls_client_key: nil, auth_mechanism: :scram)
-    tls = true if tls_ca || tls_insecure || tls_client_cert
-    # A SCRAM login with no user is "anonymous"; a certificate login with no
-    # user sends an empty one and lets the certificate's CN decide.
-    user = "anonymous" if user.nil? && AuthMechanism.resolve(auth_mechanism) == AuthMechanism::SCRAM
-    conn = Connection.new(host: host, port: port, user: user,
-                          password: password, consistency: consistency,
-                          timeout: timeout, database: database, tls: tls,
-                          tls_ca: tls_ca, tls_insecure: tls_insecure,
-                          tls_server_name: tls_server_name, seeds: seeds,
-                          tls_client_cert: tls_client_cert,
-                          tls_client_key: tls_client_key,
-                          auth_mechanism: auth_mechanism)
+  def self.connect(**options)
+    conn = Connection.new(**connection_options(**options))
     return conn unless block_given?
 
     begin
@@ -1363,67 +1404,257 @@ module Skaidb
       conn.close
     end
   end
-  # A thread-safe pool of connections.
+
+  # Internal: Skaidb.connect's keywords with their defaults applied, as
+  # Connection.new takes them (Pool dials every connection with these).
+  def self.connection_options(host: "localhost", port: 7000, user: nil,
+                              password: "", consistency: :quorum, timeout: 10.0,
+                              database: nil, tls: false, tls_ca: nil, tls_insecure: false,
+                              tls_server_name: "skaidb", seeds: nil, tls_client_cert: nil,
+                              tls_client_key: nil, auth_mechanism: :scram)
+    tls = true if tls_ca || tls_insecure || tls_client_cert
+    # A SCRAM login with no user is "anonymous"; a certificate login with no
+    # user sends an empty one and lets the certificate's CN decide.
+    user = "anonymous" if user.nil? && AuthMechanism.resolve(auth_mechanism) == AuthMechanism::SCRAM
+    { host: host, port: port, user: user, password: password, consistency: consistency,
+      timeout: timeout, database: database, tls: tls, tls_ca: tls_ca,
+      tls_insecure: tls_insecure, tls_server_name: tls_server_name, seeds: seeds,
+      tls_client_cert: tls_client_cert, tls_client_key: tls_client_key,
+      auth_mechanism: auth_mechanism }
+  end
+
+  # Internal: "host:port", or a bare host on +default_port+, as [host, port].
+  def self.parse_endpoint(text, default_port)
+    h, _, p = text.to_s.rpartition(":")
+    h.empty? ? [text.to_s, default_port] : [h, p.to_i]
+  end
+
+  # Leading keywords of statements that never write: everything else counts
+  # as a write for read-your-writes affinity (a read taken for a write only
+  # keeps the caller on its member a little longer).
+  READ_KEYWORDS = %w[select show explain describe desc values with use].freeze
+  # Whitespace, comments and opening parentheses before the first keyword.
+  STATEMENT_LEAD = %r{\A(?:\s+|\(|--[^\n]*\n?|/\*.*?(?:\*/|\z))*}m.freeze
+  private_constant :READ_KEYWORDS, :STATEMENT_LEAD
+
+  # Internal: whether +sql+ counts as a write for read-your-writes — its
+  # first keyword, after whitespace, comments and opening parentheses, is
+  # none of SELECT, SHOW, EXPLAIN, DESCRIBE, DESC, VALUES, WITH, USE.
+  def self.write_statement?(sql)
+    rest = sql.to_s.b.sub(STATEMENT_LEAD, "")
+    !READ_KEYWORDS.include?(rest[/\A[A-Za-z_]*/].downcase)
+  end
+
+  # Internal: whether a failed dial says something about the member's
+  # health. A refused login is the caller's problem, not the member's —
+  # except a capacity refusal, which is the member being full.
+  def self.member_fault?(error)
+    return true unless error.is_a?(Error) # socket, TLS, timeout
+
+    msg = error.message
+    return msg.include?("too many connections:") if msg.start_with?("authentication denied")
+
+    !msg.start_with?("server signature mismatch")
+  end
+
+  # A thread-safe pool of connections, balanced across the cluster's members.
   #
   # +maxsize+ bounds the connections kept IDLE, not the number checked out: a
   # burst creates extras and the surplus is closed on return. Every keyword
-  # accepted by Skaidb.connect passes through, so pooled connections inherit
-  # seed failover, TLS and the session database.
+  # accepted by Skaidb.connect passes through: +host+/+port+/+seeds+ name the
+  # starting members, and the rest (TLS, the session database, ...) apply to
+  # every connection.
   #
-  #   pool = Skaidb::Pool.new(seeds: ["h1:7000", "h2:7000"], database: "app", maxsize: 8)
+  # Load balancing (PROTOCOL.md §6.1, the same in every skaidb driver; see
+  # docs/pooling.md):
+  #
+  # - +load_balancing+ — +:random+ (default: each new connection dials the
+  #   members in random order), +:round_robin+ (checkouts rotate over the
+  #   members) or +:least_latency+ (of two members picked at random, the one
+  #   with the lower latency average x checked-out connections).
+  # - +idle_order+ — +:lifo+ (default: the most recently returned idle
+  #   connection first) or +:fifo+ (the longest idle first, so every idle
+  #   connection keeps getting used).
+  # - +discover+ — read the members from SHOW ENDPOINTS (server >= 0.327)
+  #   when a member is first reached and every +refresh_interval+ seconds
+  #   after (every 5 s while one is not ready): joiners are added, leavers
+  #   dropped, and members reported +resyncing+ or +unreachable+ get no new
+  #   connections until they are +ready+ again.
+  # - Health ejection: a member with +eject_errors+ consecutive transport
+  #   failures, or whose latency average is above +eject_latency_factor+
+  #   times the other members' median and more than +eject_latency_floor+
+  #   seconds above it, gets no connections for +eject_backoff+ seconds
+  #   (doubling per repeat, up to +eject_backoff_max+); then a background
+  #   thread probes it and re-admits it. The last usable member is never
+  #   ejected.
+  # - +read_your_writes+ — seconds after a write during which checkouts with
+  #   the same +affinity:+ key go to the member that took it (the coordinator
+  #   that acknowledged a write reads it back even at ONE). 0 (default) = off.
+  # - +logger+ — a Logger (or anything with +warn+) told of ejections and
+  #   re-admissions.
+  #
+  #   pool = Skaidb::Pool.new(seeds: ["h1:7000", "h2:7000"], database: "app", maxsize: 8,
+  #                           load_balancing: :least_latency, discover: true)
   #   pool.with { |conn| conn.exec("SELECT 1") }
   #   pool.close
   class Pool
-    def initialize(maxsize: 10, **connect_kwargs)
+    POLICIES = %i[random round_robin least_latency].freeze
+    IDLE_ORDERS = %i[lifo fifo].freeze
+    # Latency EWMA: each round trip moves a member's average 5% toward it,
+    # and no sample counts for more than 10x the larger of the current
+    # average and the ejection floor — one slow query does not eject a
+    # healthy member, a member that stays slow is ejected within a few dozen
+    # statements.
+    EWMA_WEIGHT = 0.05
+    EWMA_CLAMP = 10.0
+    # Round trips a member (and at least one other) needs before its average
+    # can eject it.
+    EWMA_MIN_SAMPLES = 10
+    # least_latency: a member whose last round trip is older than this scores
+    # 0, so a lightly loaded pool keeps re-measuring every member instead of
+    # settling forever on whichever answered fastest once.
+    STALE_SAMPLE = 2.0
+    # Discovery refresh while a listed member is not ready: a member is often
+    # +unreachable+ or +resyncing+ only for seconds (a peer's circuit breaker
+    # right after it restarts), and waiting a whole refresh interval to let
+    # it back in leaves the load on the others.
+    REFRESH_NOT_READY = 5.0
+    # How often the background thread checks for members due a re-probe.
+    MAINTAIN_TICK = 0.25
+    # Read-your-writes keys kept before the expired ones are swept.
+    AFFINITY_SWEEP = 4096
+    private_constant :EWMA_WEIGHT, :EWMA_CLAMP, :EWMA_MIN_SAMPLES, :STALE_SAMPLE,
+                     :REFRESH_NOT_READY, :MAINTAIN_TICK, :AFFINITY_SWEEP
+
+    # One member as the pool sees it.
+    class Member
+      attr_reader :endpoint, :host, :port, :seed
+      attr_accessor :canonical, :listed, :ewma, :samples, :last_sample, :errors,
+                    :ejected_until, :ejections, :readmitted_at, :in_use, :probing
+
+      def initialize(host, port, seed)
+        @host = host
+        @port = port
+        @endpoint = "#{host}:#{port}" # what the pool dials, and its key
+        @seed = seed                  # configured: discovery never drops it
+        @canonical = nil              # its own SHOW ENDPOINTS name
+        @listed = :ready              # :ready, :resyncing, :unreachable, :unlisted
+        @ewma = nil                   # seconds
+        @samples = 0
+        @last_sample = 0.0
+        @errors = 0                   # consecutive transport failures
+        @ejected_until = nil          # nil = admitted
+        @ejections = 0
+        @readmitted_at = 0.0
+        @in_use = 0
+        @probing = false
+      end
+    end
+    private_constant :Member
+
+    def initialize(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_kwargs)
       raise ArgumentError, "maxsize must be >= 1" if maxsize < 1
+      raise ArgumentError, "eject_errors must be >= 1" if eject_errors < 1
 
+      @policy = choice(load_balancing, POLICIES, "load_balancing")
+      @fifo = choice(idle_order, IDLE_ORDERS, "idle_order") == :fifo
       @maxsize = maxsize
-      @kwargs = connect_kwargs
+      @discover = discover ? true : false
+      @refresh_interval = refresh_interval.to_f
+      @ryw = read_your_writes.to_f
+      @eject_errors = eject_errors
+      @eject_factor = eject_latency_factor.to_f
+      @eject_floor = eject_latency_floor.to_f
+      @backoff = eject_backoff.to_f
+      @backoff_max = eject_backoff_max.to_f
+      @logger = logger
+      @conn_opts = Skaidb.connection_options(**connect_kwargs)
+      @port = @conn_opts[:port]
+      seeds = @conn_opts[:seeds]
+      @members = {}
+      (seeds && !seeds.empty? ? seeds : ["#{@conn_opts[:host]}:#{@port}"]).each do |s|
+        host, port = Skaidb.parse_endpoint(s, @port)
+        @members["#{host}:#{port}"] ||= Member.new(host, port, true)
+      end
       @idle = []
       @mutex = Mutex.new
+      @wake = ConditionVariable.new
+      @rr = -1
+      @affinity = {}
+      @discovery_off = false
+      @next_refresh = 0.0
+      @maintainer = nil
       @closed = false
     end
 
-    # Check out a usable connection, reusing an idle one when possible.
-    def checkout
+    # -- checkout / checkin --
+
+    # Check out a usable connection: an idle one to the member the policy
+    # picks, or a new one dialed to it (falling back to the other members).
+    # +affinity+ scopes read-your-writes (nil = pool-wide).
+    def checkout(affinity: nil)
       loop do
-        conn = @mutex.synchronize do
+        conn = order = nil
+        stale = []
+        @mutex.synchronize do
           raise Error, "pool is closed" if @closed
 
-          @idle.pop
+          target = pick(affinity)
+          conn, stale = take_idle(target)
+          order = order_for(target) if conn.nil?
         end
-        return Skaidb.connect(**@kwargs) if conn.nil?
-        # A connection the server closed while it sat idle still looks fine
-        # locally, so check before handing it out.
-        return conn if conn.usable?
-
-        begin
-          conn.close
-        rescue StandardError
-          nil
+        stale.each { |c| close_quietly(c) }
+        if conn.nil?
+          conn = Connection.new(**@conn_opts, endpoints: order, observer: self)
+          conn.pool_member = conn.endpoint
+          discover_through(conn)
+          unless conn.usable?
+            close_quietly(conn)
+            next
+          end
+        elsif !conn.usable?
+          # A connection the server closed while it sat idle still looks
+          # fine locally, so check before handing it out.
+          close_quietly(conn)
+          next
         end
+        @mutex.synchronize do
+          m = @members[conn.pool_member]
+          m.in_use += 1 if m
+          conn.pool_affinity = affinity
+          conn.pool_out = true
+        end
+        return conn
       end
     end
 
-    # Return a connection, closing it if broken or the pool is full.
+    # Return a connection, closing it if it is broken, its member is ejected
+    # or gone, or the pool is full.
     def checkin(conn)
       keep = @mutex.synchronize do
-        !@closed && conn.usable? && @idle.length < @maxsize
-      end
-      if keep
-        @mutex.synchronize { @idle.push(conn) }
-        return
-      end
-      begin
-        conn.close
-      rescue StandardError
-        nil
+        if conn.pool_out
+          conn.pool_out = false
+          counted = @members[conn.pool_member]
+          counted.in_use -= 1 if counted && counted.in_use.positive?
+        end
+        m = @members[conn.pool_member]
+        if !@closed && conn.usable? && m && usable?(m) && @idle.length < @maxsize
+          @idle.push(conn)
+          true
+        else
+          false
+        end
       end
+      close_quietly(conn) unless keep
     end
 
     # Run the block with a checked-out connection, returning it afterwards.
-    def with
-      conn = checkout
+    # +affinity+ scopes read-your-writes (nil = pool-wide).
+    def with(affinity: nil)
+      conn = checkout(affinity: affinity)
       begin
         yield conn
       ensure
@@ -1431,20 +1662,400 @@ module Skaidb
       end
     end
 
-    # Close the pool and every idle connection.
+    # The members as the pool sees them, for monitoring: one Hash each with
+    # +:endpoint+ (what the pool dials), +:canonical+ (the member's own name,
+    # once discovered), +:state+ (+:ready+, +:ejected+, +:resyncing+,
+    # +:unreachable+, +:unlisted+), +:latency_ms+ (the round-trip average,
+    # nil until measured), +:in_use+, +:idle+ and +:seed+.
+    def members
+      @mutex.synchronize do
+        idle = Hash.new(0)
+        @idle.each { |c| idle[c.pool_member] += 1 }
+        @members.values.sort_by { |m| [m.host, m.port] }.map do |m|
+          { endpoint: m.endpoint, canonical: m.canonical,
+            state: m.ejected_until ? :ejected : m.listed,
+            latency_ms: m.ewma && m.ewma * 1000.0, in_use: m.in_use,
+            idle: idle[m.endpoint], seed: m.seed }
+        end
+      end
+    end
+
+    # Close the pool and every idle connection, and stop the background
+    # thread. Checked-out connections are closed when they are returned.
     def close
       drained = @mutex.synchronize do
         @closed = true
+        @wake.broadcast
         d = @idle
         @idle = []
         d
       end
-      drained.each do |c|
-        begin
-          c.close
-        rescue StandardError
-          nil
+      drained.each { |c| close_quietly(c) }
+    end
+
+    # -- what connections report (internal: called by Connection, any thread) --
+
+    # Internal: the order a pooled connection re-dials in — the usable
+    # members first, +exclude+ (the member it lost) last.
+    def dial_order(exclude)
+      @mutex.synchronize { order_for(nil, exclude) }
+    end
+
+    # Internal: a round trip on +conn+ took +elapsed+ seconds.
+    def note_round_trip(conn, elapsed)
+      @mutex.synchronize do
+        ep = conn.endpoint
+        if ep != conn.pool_member
+          # The connection re-dialed to another member mid-checkout.
+          if conn.pool_out
+            old = @members[conn.pool_member]
+            old.in_use -= 1 if old && old.in_use.positive?
+            moved = @members[ep]
+            moved.in_use += 1 if moved
+          end
+          conn.pool_member = ep
+        end
+        m = @members[ep]
+        next if m.nil?
+
+        m.errors = 0
+        if m.ewma.nil?
+          m.ewma = elapsed
+        else
+          cap = EWMA_CLAMP * [m.ewma, @eject_floor].max
+          m.ewma += EWMA_WEIGHT * ([elapsed, cap].min - m.ewma)
         end
+        m.samples += 1
+        m.last_sample = now
+        next unless m.samples >= EWMA_MIN_SAMPLES && @eject_factor.positive? && m.ejected_until.nil?
+
+        others = @members.each_value.select do |o|
+          !o.equal?(m) && usable?(o) && o.ewma && o.samples >= EWMA_MIN_SAMPLES
+        end.map(&:ewma).sort
+        next if others.empty?
+
+        median = others[(others.length - 1) / 2]
+        if m.ewma > @eject_factor * median && m.ewma - median > @eject_floor
+          eject(m, format("latency %.1f ms vs median %.1f ms", m.ewma * 1000, median * 1000))
+        end
+      end
+    end
+
+    # Internal: a dial or a request to +endpoint+ failed in transport.
+    def note_failure(endpoint)
+      @mutex.synchronize do
+        m = @members[endpoint]
+        next if m.nil?
+
+        m.errors += 1
+        eject(m, "#{m.errors} consecutive connection failures") if m.errors >= @eject_errors && m.ejected_until.nil?
+      end
+    end
+
+    # Internal: +sql+ succeeded on +conn+; a write pins the connection's
+    # affinity key to its member for +read_your_writes+ seconds.
+    def note_statement(conn, sql)
+      return if @ryw <= 0 || !conn.pool_out || !Skaidb.write_statement?(sql)
+
+      t = now
+      @mutex.synchronize do
+        @affinity.select! { |_, (_, untl)| untl > t } if @affinity.length >= AFFINITY_SWEEP
+        @affinity[conn.pool_affinity] = [conn.endpoint, t + @ryw]
+      end
+    end
+
+    # Internal: +conn+ was closed while checked out instead of returned.
+    def note_closed(conn)
+      @mutex.synchronize do
+        next unless conn.pool_out
+
+        conn.pool_out = false
+        m = @members[conn.pool_member]
+        m.in_use -= 1 if m && m.in_use.positive?
+      end
+    end
+
+    private
+
+    def choice(value, allowed, name)
+      v = value.to_s.downcase.to_sym if value.is_a?(String) || value.is_a?(Symbol)
+      return v if allowed.include?(v)
+
+      names = allowed.map(&:inspect)
+      raise ArgumentError, "unknown #{name} #{value.inspect} (use #{names[0..-2].join(', ')} or #{names[-1]})"
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def close_quietly(conn)
+      conn.close
+    rescue StandardError
+      nil
+    end
+
+    def log(message)
+      @logger&.warn("skaidb pool: #{message}")
+    end
+
+    # -- choosing a member (callers hold @mutex) --
+
+    def usable?(m)
+      m.ejected_until.nil? && m.listed == :ready
+    end
+
+    # The member this checkout should go to, or nil for "any" (the random
+    # policy, or no usable member at all).
+    def pick(affinity)
+      if @ryw.positive? && (hit = @affinity[affinity])
+        ep, untl = hit
+        m = @members[ep]
+        if now >= untl || m.nil?
+          @affinity.delete(affinity)
+        elsif usable?(m)
+          return m
+        end
+      end
+      usable = @members.values.select { |m| usable?(m) }
+      return nil if usable.empty? || @policy == :random
+
+      if @policy == :round_robin
+        usable.sort_by! { |m| [m.host, m.port] }
+        @rr = (@rr + 1) % usable.length
+        return usable[@rr]
+      end
+      return usable[0] if usable.length == 1
+
+      a, b = usable.sample(2)
+      score(a) <= score(b) ? a : b
+    end
+
+    # A member never measured, or not lately, scores 0: it is tried and
+    # measured.
+    def score(m)
+      return 0.0 if m.ewma.nil? || now - m.last_sample > STALE_SAMPLE
+
+      m.ewma * (m.in_use + 1)
+    end
+
+    # Remove and return an idle connection (to +target+, or to any usable
+    # member), plus the idle connections found to belong to members that are
+    # no longer usable (to close outside the lock).
+    def take_idle(target)
+      stale = []
+      found = nil
+      indexes = @fifo ? (0...@idle.length) : (@idle.length - 1).downto(0)
+      indexes.each do |i|
+        m = @members[@idle[i].pool_member]
+        if m.nil? || !usable?(m)
+          stale << i
+        elsif target.nil? || m.equal?(target)
+          found = i
+          break
+        end
+      end
+      picked = found && @idle[found]
+      stale_conns = stale.map { |i| @idle[i] }
+      (found ? stale + [found] : stale).sort.reverse_each { |i| @idle.delete_at(i) }
+      [picked, stale_conns]
+    end
+
+    # [host, port] pairs to dial, best first: +first+, the other usable
+    # members in random order, then the rest (resyncing/unreachable before
+    # ejected, soonest re-admission first) — a dial never has nowhere to go
+    # while any member is configured. +exclude+ goes last.
+    def order_for(first, exclude = nil)
+      all = @members.values
+      usable = all.select { |m| !m.equal?(first) && usable?(m) }.shuffle
+      rest = all.select { |m| !m.equal?(first) && !usable?(m) }
+      rest = rest.sort_by { |m| m.ejected_until ? [1, m.ejected_until] : [0, 0.0] }
+      order = (first ? [first] : []) + usable + rest
+      lost = exclude && order.length > 1 && order.find { |m| m.endpoint == exclude }
+      order = order.reject { |m| m.equal?(lost) } + [lost] if lost
+      order.map { |m| [m.host, m.port] }
+    end
+
+    # -- ejection and re-admission --
+
+    # Take +m+ out of rotation (caller holds @mutex) — unless it is the last
+    # usable member: a slow or flaky member beats none.
+    def eject(m, why)
+      return unless @members.each_value.any? { |o| !o.equal?(m) && usable?(o) }
+
+      t = now
+      m.ejections = 0 if t - m.readmitted_at > @backoff_max # healthy for a while: start over
+      m.ejections += 1
+      m.ejected_until = t + backoff_for(m)
+      log("ejecting #{m.endpoint} (#{why})")
+      ensure_maintainer
+    end
+
+    def backoff_for(m)
+      [@backoff * (2**[m.ejections - 1, 0].max), @backoff_max].min
+    end
+
+    # Start the background thread (caller holds @mutex): it re-probes ejected
+    # members and refreshes discovery, and ends when the pool closes. Ruby
+    # never waits for it at exit.
+    def ensure_maintainer
+      return if @maintainer || @closed
+
+      @maintainer = Thread.new { maintain }
+      @maintainer.name = "skaidb-pool"
+    end
+
+    def maintain
+      loop do
+        due = []
+        refresh = false
+        @mutex.synchronize do
+          @wake.wait(@mutex, MAINTAIN_TICK) unless @closed
+          return if @closed
+
+          t = now
+          due = @members.each_value.select { |m| m.ejected_until && t >= m.ejected_until && !m.probing }
+          due.each { |m| m.probing = true }
+          refresh = @discover && !@discovery_off && t >= @next_refresh
+        end
+        due.each { |m| probe(m) }
+        refresh_members if refresh
+      end
+    end
+
+    # Dial +m+ alone and run one statement: success re-admits it (the probe
+    # connection joins the idle set), failure ejects it again for twice as
+    # long.
+    def probe(m)
+      conn = nil
+      ok = begin
+        conn = Connection.new(**@conn_opts, endpoints: [[m.host, m.port]])
+        conn.exec("SHOW DATABASES")
+        true
+      rescue StandardError
+        false
+      end
+      keep = false
+      @mutex.synchronize do
+        m.probing = false
+        if ok && !@closed
+          m.ejected_until = nil
+          m.errors = 0
+          m.ewma = nil
+          m.samples = 0
+          m.readmitted_at = now
+          log("re-admitted #{m.endpoint}")
+          if @idle.length < @maxsize
+            conn.observer = self
+            conn.pool_member = m.endpoint
+            @idle.push(conn)
+            keep = true
+          end
+        else
+          m.ejections += 1
+          m.ejected_until = now + backoff_for(m)
+        end
+      end
+      close_quietly(conn) if conn && !keep
+    end
+
+    # -- discovery --
+
+    # Run discovery on a freshly dialed connection when the member it reached
+    # has not named itself yet (once per member, so seeds given as host names
+    # are matched to the endpoints the server reports).
+    def discover_through(conn)
+      return if !@discover || @discovery_off
+
+      ask = @mutex.synchronize do
+        m = @members[conn.pool_member]
+        next false if m.nil? || m.canonical
+
+        ensure_maintainer
+        true
+      end
+      list_through(conn) if ask
+    end
+
+    def refresh_members
+      conn = begin
+        checkout
+      rescue StandardError
+        @mutex.synchronize { @next_refresh = now + @refresh_interval }
+        return
+      end
+      begin
+        list_through(conn)
+      ensure
+        checkin(conn)
+      end
+    end
+
+    def list_through(conn)
+      rows = begin
+        conn.exec("SHOW ENDPOINTS").rows
+      rescue QueryError
+        # A server that predates the statement: keep the seeds.
+        @mutex.synchronize { @discovery_off = true }
+        return
+      rescue Error
+        return
+      end
+      if rows.empty?
+        # A standalone server: nothing to discover, ever.
+        @mutex.synchronize { @discovery_off = true }
+        return
+      end
+      @mutex.synchronize do
+        apply_listing(conn.pool_member, rows)
+        interval = @refresh_interval
+        if @members.each_value.any? { |m| m.listed == :resyncing || m.listed == :unreachable }
+          interval = [interval, REFRESH_NOT_READY].min
+        end
+        @next_refresh = now + interval
+      end
+    end
+
+    # Fold a non-empty SHOW ENDPOINTS answer (caller holds @mutex).
+    def apply_listing(dialed, rows)
+      listed = {}
+      rows.each do |endpoint, state, local|
+        listed[endpoint] = state
+        next unless local
+
+        me = @members[dialed]
+        me.canonical = endpoint if me
+      end
+      # A member reported under the name of one already known (a seed given
+      # as a host name) is that member, not a new one.
+      by_name = {}
+      @members.each_value do |m|
+        by_name[m.canonical] = m if m.canonical && (!by_name.key?(m.canonical) || m.seed)
+      end
+      @members.delete_if { |_, m| m.canonical && !by_name[m.canonical].equal?(m) } # a duplicate of a seed
+      seen = {}.compare_by_identity
+      listed.each do |endpoint, state|
+        m = by_name[endpoint]
+        if m.nil?
+          host, port = Skaidb.parse_endpoint(endpoint, @port)
+          m = (@members["#{host}:#{port}"] ||= Member.new(host, port, false))
+          m.canonical = endpoint
+        end
+        state = %w[ready resyncing unreachable].include?(state) ? state.to_sym : :ready
+        if state == :ready && m.listed != :ready
+          # Back in rotation: measured afresh, like a re-admission.
+          m.ewma = nil
+          m.samples = 0
+          m.errors = 0
+        end
+        m.listed = state
+        seen[m] = true
+      end
+      @members.delete_if do |_, m|
+        next false if seen[m] || (m.seed && m.canonical.nil?) # listed, or a seed not identified yet
+
+        m.listed = :unlisted if m.seed # configured, but no longer a member
+        !m.seed
       end
     end
   end

metadata

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