skaidb 1.0.3

data/docs/getting-started.md

@@ -0,0 +1,127 @@
+# Getting started
+
+## Install
+
+The gem is published on RubyGems.org as
+[`skaidb`](https://rubygems.org/gems/skaidb); whichever way it is installed
+the library is loaded with `require "skaidb"`.
+
+```sh
+gem install skaidb
+```
+
+With Bundler:
+
+```ruby
+# Gemfile
+gem "skaidb", "~> 1.0"
+```
+
+Or vendor the single file `lib/skaidb.rb` into your project and
+`require_relative` it — it needs nothing beyond Ruby's standard library
+(`socket`, `openssl`, `securerandom`, `bigdecimal`).
+
+Ruby 2.7 or newer; CI covers 3.1 through 3.4.
+
+## Connect
+
+```ruby
+require "skaidb"
+
+conn = Skaidb.connect(host: "localhost", port: 7000,
+                      user: "skaidb", password: "secret",
+                      database: "app")
+```
+
+`connect` opens the TCP connection, runs the four-frame SCRAM-SHA-256
+handshake (verifying the server's signature when a password is given), sends
+the driver's `Hello`, and runs `USE "app"` when `database:` is set. Pass a
+block to have the connection closed when it returns:
+
+```ruby
+Skaidb.connect(host: "localhost", user: "skaidb", password: "secret") do |conn|
+  # ...
+end
+```
+
+For a server with authentication disabled, omit `user:` and `password:`.
+
+For a cluster, pass every node as `seeds:` — they are tried in random order
+until one accepts the connection and the handshake:
+
+```ruby
+conn = Skaidb.connect(seeds: ["db1", "db2:7000", "db3"], user: "app", password: "secret")
+```
+
+## Run statements
+
+```ruby
+conn.exec("CREATE TABLE users (PRIMARY KEY (id))")
+
+conn.exec_params("INSERT INTO users (id, name, age, tags) VALUES ($1, $2, $3, $4)",
+                 [1, "Ada", 36, ["math", "eng"]])
+
+res = conn.exec_params("SELECT id, name, tags FROM users WHERE age > $1 ORDER BY id", [30])
+res.each { |row| puts "#{row['id']} #{row['name']} #{row['tags'].inspect}" }
+res.ntuples      # 1
+res.fields       # ["id", "name", "tags"]
+res.rows         # [[1, "Ada", ["math", "eng"]]]
+
+conn.exec_params("UPDATE users SET age = $1 WHERE id = $2", [37, 1]).cmd_tuples   # 1
+```
+
+Placeholders are `$1`, `$2`, … and values are sent **typed** through a
+server-side prepared statement: Strings need no escaping, and Arrays and
+Hashes bind natively. See [types.md](types.md) for the full mapping.
+
+## Bulk insert
+
+```ruby
+rows = (1..10_000).map { |i| [i, "row #{i}"] }
+conn.exec_batch("INSERT INTO t (id, v) VALUES ($1, $2)", rows)   # one round-trip
+```
+
+## Large results
+
+```ruby
+conn.stream("SELECT id, payload FROM events ORDER BY id") do |row|
+  process(row)
+end
+```
+
+Rows arrive chunk by chunk; the driver holds one chunk at a time. See
+[streaming.md](streaming.md), in particular what happens when you leave the
+block early.
+
+## Errors
+
+```ruby
+begin
+  conn.exec("SELECT nope FROM missing")
+rescue Skaidb::QueryError => e       # the server rejected the statement; connection still fine
+  warn e.message                     # table "missing" does not exist
+rescue Skaidb::ConnectionError => e  # transport/handshake trouble; next statement re-dials
+  warn e.message
+end
+```
+
+Both inherit from `Skaidb::Error`.
+
+## Close
+
+```ruby
+conn.close
+```
+
+Or use the block form of `connect`, or a [pool](pooling.md).
+
+## Next
+
+- [API reference](api.md)
+- [Types](types.md)
+- [TLS](tls.md)
+- [Streaming](streaming.md)
+- [Pooling](pooling.md)
+- Runnable scripts in [`examples/`](../examples/)
+- Server documentation: <https://skaidb.org/docs/> — the wire protocol this
+  driver speaks: <https://skaidb.org/docs/PROTOCOL.html>

data/docs/pooling.md

@@ -0,0 +1,47 @@
+# Connection pool
+
+`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.
+
+```ruby
+pool = Skaidb::Pool.new(seeds: ["db1", "db2", "db3"], user: "app", password: "secret",
+                        database: "app", maxsize: 8)
+
+pool.with do |conn|                          # checked out; returned when the block ends
+  conn.exec_params("SELECT … WHERE id = $1", [id])
+end
+
+conn = pool.checkout                         # the explicit form
+begin
+  conn.exec("…")
+ensure
+  pool.checkin(conn)
+end
+
+pool.close                                   # closes every idle connection
+```
+
+## 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
+  is closed instead of kept.
+- `checkout` and `checkin` both validate with `usable?`: a connection broken
+  by a transport error, or left mid-stream by an abandoned Enumerator, is
+  closed and dropped rather than handed on. `usable?` is local knowledge
+  only — a connection the server closed while it sat idle still looks fine
+  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.
+
+See also `examples/pool.rb`.

data/docs/streaming.md

@@ -0,0 +1,69 @@
+# Streaming large results
+
+`exec` and `exec_params` buffer the whole result in a `Skaidb::Result`. For
+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.
+
+```ruby
+conn.stream("SELECT id, payload FROM events ORDER BY id") do |row|
+  export(row)                 # row is a Hash keyed by column name
+end
+```
+
+- `stream(sql, consistency: nil)` takes SQL text only — no parameters.
+- With a block it returns `nil` after the last row.
+- Without a block it returns an Enumerator: `conn.stream(sql).first(10)`,
+  `.each_slice(1000)`, `.lazy.map { … }`, and the rest of Enumerable work.
+- A non-row statement (an `INSERT`, DDL, `USE`) answers with its ordinary
+  result over the same opcode; `stream` returns `nil` without yielding.
+- A server without the streaming opcode raises `Skaidb::QueryError`
+  (`server does not support streaming: …`).
+
+## Errors mid-stream
+
+The server can fail a statement after it has started sending rows (a node
+dying mid-scan, a scan budget tripping). The rows already yielded are valid;
+the block stops and `stream` raises `Skaidb::QueryError` with the server's
+message. The connection stays usable.
+
+## The abandon/drain rule
+
+The protocol forbids any other request on the connection until the stream
+ends, so the whole exchange runs under the connection's lock: a statement
+from another thread **waits** for the stream to finish rather than
+interleaving with it.
+
+Leaving the block early — `break`, `return`, `raise`, or any Enumerable
+method that stops before the end (`first`, `take`, `find`) — unwinds through
+an `ensure` that **drains** the frames the server is still sending, so the
+socket is back at a request boundary and the next statement is clean:
+
+```ruby
+first = conn.stream("SELECT id FROM big ORDER BY id").first(3)
+conn.usable?      # true
+conn.exec("SELECT 1")
+```
+
+Draining is not free and there is no cancel opcode: breaking out of a
+million-row scan still transfers the rest of it before the connection is
+usable again. If you only want a few rows, say so in SQL (`LIMIT`).
+
+Two things defeat the drain:
+
+- **External iteration** — `e = conn.stream(sql); e.next` — runs the stream
+  inside the Enumerator's Fiber. A Fiber abandoned part-way is collected
+  without running any `ensure`, so nothing drains and the connection stays
+  marked mid-stream: `usable?` is `false` for good and a pool will not hand
+  it out again. Iterate with a block or `each`.
+- **A frame that makes no sense mid-stream**, or a dead socket. The driver
+  no longer knows where the reply ends, so it marks the connection broken
+  instead of guessing; `usable?` turns `false`, and the next statement
+  re-dials.
+
+There is no read deadline: a peer that is alive but silent blocks the drain,
+holding the lock. `close` does not take the lock, so another thread can break
+such a read by closing the connection.
+
+See also `examples/stream.rb`.

data/docs/tls.md

@@ -0,0 +1,59 @@
+# TLS
+
+The binary protocol runs over plain TCP by default. A server configured with
+`client_tls = required` refuses plaintext outright, so such a cluster is
+only reachable with TLS switched on in the driver.
+
+## Enabling it
+
+Any one of these three keywords turns TLS on:
+
+```ruby
+Skaidb.connect(host: "db1", tls: true)                      # verify against the system trust store
+Skaidb.connect(host: "db1", tls_ca: "/etc/skaidb/ca.crt")   # verify against this CA file only
+Skaidb.connect(host: "db1", tls_insecure: true)             # encrypt, verify nothing
+```
+
+- `tls: true` uses OpenSSL's default certificate paths — right when the
+  server's certificate chains to a public or system-installed CA.
+- `tls_ca:` trusts exactly the certificates in that PEM file. This is the
+  usual shape for a cluster with its own CA: hand the driver the CA
+  certificate, nothing else.
+- `tls_insecure: true` sets `VERIFY_NONE`. The connection is encrypted but
+  the peer is not authenticated, so a man in the middle can present any
+  certificate. Development and throw-away environments only.
+
+`Skaidb::Pool` passes all of these through to every connection it opens.
+
+## The server name
+
+The driver sends `tls_server_name` as SNI and, unless `tls_insecure`, checks
+it against the certificate's subject alternative names with
+`post_connection_check`. The default is `"skaidb"`, the DNS SAN skaidb's own
+generated certificates carry — which is usually **not** the address you
+dial. If your certificate names the host instead, say so:
+
+```ruby
+Skaidb.connect(host: "db1.internal", tls_ca: "ca.crt", tls_server_name: "db1.internal")
+```
+
+A mismatch fails the connect with `Skaidb::ConnectionError` wrapping
+OpenSSL's message.
+
+## What runs inside the session
+
+The TCP connection is upgraded to TLS *before* the SCRAM handshake, so the
+user name, nonces and proof all travel encrypted; with `seeds:`, each
+endpoint is upgraded and authenticated in turn until one succeeds. The
+driver does not present a client certificate; authentication is SCRAM.
+
+## Failures
+
+- Wrong CA, expired certificate, name mismatch: `Skaidb::ConnectionError`
+  with the OpenSSL message, from `connect` (or from the statement that
+  triggered a re-dial).
+- Plain TCP against a `client_tls = required` server: the handshake cannot
+  complete, so `connect` raises `Skaidb::ConnectionError`
+  (`no reachable endpoint in …`) naming the underlying failure.
+
+See also `examples/tls.rb`.

data/docs/types.md

@@ -0,0 +1,72 @@
+# 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`.
+
+| skaidb type | Result value | Accepted as a parameter |
+|---|---|---|
+| Null | `nil` | `nil` |
+| Bool | `true` / `false` | `true` / `false` |
+| Int (64-bit) | `Integer` | `Integer` in the signed 64-bit range |
+| Float (64-bit) | `Float` | `Float`, finite (NaN and ±Infinity are refused) |
+| Decimal | `BigDecimal`, exact | `BigDecimal`, finite, mantissa within a signed 128-bit integer |
+| String | `String` (UTF-8) | `String` with any text encoding (sent as UTF-8 bytes); `Symbol` |
+| Bytes | `String` with `Encoding::BINARY` | `String` whose encoding is `Encoding::BINARY` (`ASCII-8BIT`) |
+| Uuid | `String`, canonical lowercase `8-4-4-4-12` | `Skaidb::Uuid` |
+| Timestamp | `Time` in UTC, millisecond precision (may predate 1970) | `Time` (any zone) |
+| Array | `Array` of mapped values | `Array` (elements follow this table) |
+| Document | `Hash` with String keys, in the order the server sends them | `Hash` (keys are converted with `to_s`) |
+
+## Notes
+
+- **Bytes vs String** is decided by the Ruby String's encoding: `"…".b`,
+  `String.new`, `File.binread` and `[…].pack` produce binary Strings and bind
+  as Bytes; literals and `File.read` produce text and bind as String. A text
+  String is sent as its UTF-8 bytes (it is `force_encoding`'d, not
+  transcoded — keep text in UTF-8).
+- **Uuid** results are Strings so they compare and print naturally. To bind
+  a value *as* a UUID wrap it: `Skaidb::Uuid.new("6ba7b810-9dad-11d1-80b4-00c04fd430c8")`
+  (dashes optional, any case), `Skaidb::Uuid.random`, or
+  `Skaidb::Uuid.from_bytes(raw)`. `uuid == "6ba7b810-…"` is true when the
+  canonical forms match, so a bound value compares equal to what comes back.
+  A plain String parameter binds as String, not Uuid.
+- **Decimal** is `mantissa × 10^-scale` on the wire. `BigDecimal("123.45")`
+  is sent as mantissa `12345`, scale `2`; trailing zeros are dropped and a
+  positive exponent (`BigDecimal("1e5")`) is folded into the mantissa. A
+  mantissa beyond ±2^127 raises `QueryError`.
+- **Document** results keep the key order the server sends; the driver adds
+  keys to the `Hash` as they arrive. That order is not the one the document
+  was bound in: the server stores a document in canonical form, with keys
+  sorted at every nesting level, so `{"zeta" => 1, "alpha" => 2}` comes back
+  as `{"alpha" => 2, "zeta" => 1}`. Do not rely on key order.
+- **Timestamp**: a `Time` keeps its instant whatever its zone (local,
+  `+05:30`, UTC) and is truncated to the millisecond towards negative
+  infinity, so `decode(encode(t)) == t` for any millisecond-precision `Time`.
+  Results are always UTC.
+- **Int**: an `Integer` outside `-2^63 … 2^63-1` raises `QueryError` before
+  anything is sent. There is no marker to force Float for an integral value;
+  bind `3.0`, not `3`, when you mean a Float.
+- **Document** keys become Strings (`{ city: "London" }` is stored with key
+  `"city"`); nested Arrays and Hashes are encoded recursively.
+- Any other class — `Date`, `DateTime`, `Rational`, `Set`, `Range`, your own
+  objects — raises `QueryError("cannot bind value of type …")`. Convert
+  first (`date.to_time`, `rational.to_f`, `set.to_a`).
+
+## The client-side fallback
+
+When the server refuses to prepare a statement (DDL, `USE`, and every
+statement on a server without the prepare opcode), `exec_params` renders the
+parameters into the SQL text instead:
+
+| Ruby value | Literal |
+|---|---|
+| `nil` | `NULL` |
+| `true` / `false` | `TRUE` / `FALSE` |
+| `Integer`, `Float` (finite) | as printed |
+| `BigDecimal` | plain decimal notation (`123.45`) |
+| `String` (text), `Symbol` | single-quoted, `'` doubled |
+| `String` (binary) | the hex digits, single-quoted |
+| `Skaidb::Uuid` | the canonical form, single-quoted |
+| `Time` | Unix milliseconds |
+| `Array`, `Hash` | refused: `QueryError`, with the server's reason for not preparing the statement appended |