feat(qwp)!: stop flushing pooled senders on close, add a commit window and a lease-scoped reset

README.md

@@ -32,7 +32,7 @@ try (QuestDB db = QuestDB.connect("ws::addr=localhost:9000;")) {
                 .doubleColumn("price", 2615.54)
                 .doubleColumn("amount", 0.00044)
                 .atNow();
-        // close() flushes pending rows and returns the Sender to the pool.
+        // close() returns the Sender to the pool; rows ship once an auto-flush threshold trips (age, rows or bytes), or when the idle slot is settled.
     }
 }
 ```
@@ -98,8 +98,15 @@ snippets below borrow from its pools.
 
 ### Ingest Data
 
-Borrow a `Sender`, write rows, and close it. `close()` flushes pending rows and returns the sender to the pool — the
-underlying connection is only torn down when the `QuestDB` handle itself is closed.
+Borrow a `Sender`, write rows, and close it. Close releases, flush ships, drain waits: `close()` returns the sender to
+the pool and ships the slot's pending rows once the oldest is older than `auto_flush_interval` (100 ms by default) or
+another auto-flush threshold trips, otherwise it only releases; rows left in the slot go out when an auto-flush
+threshold trips on a later append or `close()`, or when the pool's housekeeper settles the idle slot, typically within
+one `auto_flush_interval`. A lease that holds the slot without appending or closing, for example one that waits for input
+inside the `try` block, holds those rows back until it does: borrow once the data is in hand. Borrowing per
+message is the intended pattern and batches like a sender held for the whole run. Call `flush()` to ship now and
+`drain()` to wait for the server. The underlying connection is only torn down when the `QuestDB` handle itself is
+closed.
 
 ```java
 import io.questdb.client.Sender;
@@ -110,15 +117,29 @@ try (Sender sender = db.borrowSender()) {
             .doubleColumn("price", 42_500.50)
             .longColumn("size", 100)
             .atNow();
-    // No explicit flush() needed: close() flushes for you.
+    // close() returns the sender; the pool ships the row by threshold or on its next settle.
 }
 ```
 
 ### Sending Batches of Rows
 
 The sender buffers rows and sends them in batches. For high throughput, write many rows on one borrowed sender and
-flush per batch rather than per row: each flush has a fixed cost, so batching raises throughput. `close()` flushes the
-final partial batch.
+flush per batch rather than per row: each flush has a fixed cost, so batching raises throughput. The final partial batch ships on the
+pool's next settle; call `flush()` before `close()` if you need it on the wire now.
+
+If you borrow per message and want each message in the store-and-forward ring the moment `close()` returns, set
+`flush_on_close=on` together with a commit window (`commit_rows`, `commit_interval_ms`): every close ships one frame
+flagged defer-commit, the server appends it, and the pool commits once per window instead of once per close. A rejected
+frame then rolls back the whole open group, so every lease since the last commit loses its rows.
+
+A server rejection covers a whole frame. With the default `flush_on_close=off` one frame carries the rows of every
+lease that closed since the last ship, so one rejected row discards the other leases' rows in that frame as well,
+after their `close()` calls returned. The default error handler logs the rejection with the frame's sequence span, and
+the error is thrown by the next call on that slot, possibly to a lease that wrote none of the rejected rows. A
+retriable rejection (write error, internal error) replays the frame; a terminal one (schema mismatch, parse error,
+security error) retires the slot, and with `sf_dir` its unacked frames stay in the slot directory for recovery. A
+lease whose rows must not share a frame calls `flush()` before `close()`, or the handle sets `flush_on_close=on`.
+`reset()` on a borrowed sender discards only the rows appended through that lease.
 
 ```java
 try (Sender sender = db.borrowSender()) {
@@ -134,7 +155,7 @@ try (Sender sender = db.borrowSender()) {
             sender.flush();
         }
     }
-    // Remaining rows are flushed by close().
+    // Remaining rows ship on the pool's next settle; flush() ships them now.
 }
 ```
 
@@ -652,13 +673,16 @@ schema::key1=value1;key2=value2;
 | Key                      | Default | Description                                                                    |
 | ------------------------ | ------- | ------------------------------------------------------------------------------ |
 | `lazy_connect`           | `off`   | Tolerant startup: async ingest + lazy reads so `build()` succeeds server-down  |
-| `sender_pool_min`        | `1`     | Minimum ingest connections kept warm (`0` lets the pool drain when idle)       |
+| `sender_pool_min`        | `1`     | Minimum ingest connections kept warm (`0` lets the pool drain when idle). The free list is LIFO, so under steady load the pool shrinks to its working set and reopens connections on a burst; set it equal to `sender_pool_max` to keep every connection warm |
 | `sender_pool_max`        | `4`     | Maximum ingest connections                                                     |
 | `query_pool_min`         | `1`     | Minimum query connections kept warm (`0` under `lazy_connect`)                 |
 | `query_pool_max`         | `4`     | Maximum query connections                                                      |
 | `acquire_timeout_ms`     | `5000`  | How long `borrowSender()`/`borrowQuery()` waits for a free slot                |
 | `idle_timeout_ms`        | `60000` | How long a pooled connection may stay idle before it is reaped                 |
 | `max_lifetime_ms`        | `1800000` | Maximum lifetime of a pooled connection before it is recycled                |
+| `flush_on_close`         | `off`   | `on` makes a pooled `close()` flush before releasing (one frame and one commit per close, the behaviour before 1.3.12). Note: "flush" means published to the store-and-forward ring, not acknowledged. Close-time errors are wrapped; the delegate's error is the cause; only `LineSenderServerException` keeps its type, so code that catches another `LineSenderException` subclass around a pooled `close()` must look at `getCause()`; with `on` and no commit window each lease ships its own frame, so a server rejection cannot discard other leases' rows; with `off` leases share frames and a rejection covers all of them; with a commit window a rejection rolls back the whole open group, every lease since the last commit |
+| `commit_rows`            | _(unset)_ | Commit window: with `flush_on_close=on`, closes ship frames flagged defer-commit and the server commits once per window of this many rows. Acks arrive at the commit; `drain()` after `flush()` |
+| `commit_interval_ms`     | _(unset)_ | Commit window age in milliseconds; setting either window key enables the window, the other defaults to 1000 rows / 100 ms. An idle slot's open group is committed at the settle cadence, so the interval only bounds groups on busy slots |
 
 ### Query routing keys
 

core/src/main/java/io/questdb/client/QuestDB.java

@@ -137,9 +137,32 @@ static QuestDB connect(CharSequence configurationString, HttpTokenProvider token
     /**
      * Borrows a {@link Sender} from the pool. The caller MUST call
      * {@link Sender#close()} on the returned instance to release it back to
-     * the pool. {@code close()} on a pooled Sender flushes pending rows
-     * before returning to the pool; a real disconnect only happens at
-     * {@link #close()} on this {@code QuestDB} handle.
+     * the pool. Close releases, flush ships, drain waits: {@code close()} on a
+     * pooled Sender returns the slot and by default ships the slot's pending
+     * rows once the oldest is older than {@code auto_flush_interval} or another
+     * auto-flush threshold trips, otherwise it only releases; rows left in the
+     * slot go out when an auto-flush threshold trips on a later append or
+     * release, or when the housekeeper settles the idle slot, within about one
+     * {@code auto_flush_interval} of it going idle. A lease that holds the slot
+     * without appending or closing holds those rows back until it does. Call
+     * {@link Sender#flush()} to ship now and
+     * {@link Sender#drain(long)} to wait for the server. Set
+     * {@code flush_on_close=on} to have {@code close()} flush, as before 1.3.12.
+     * With the default, one frame carries the rows of every lease that closed
+     * since the last ship, so a server rejection of that frame discards those
+     * leases' rows together; the error is logged by the error handler and thrown
+     * by a later call on that slot. Call {@link Sender#flush()} before close, or
+     * set {@code flush_on_close=on}, when a lease's rows must not share a frame.
+     * {@link Sender#reset()} on a pooled Sender discards only that lease's rows.
+     * Note that in this client "flush" means published to the store-and-forward
+     * ring, not acknowledged by the server. The free list is LIFO, so under
+     * steady load the pool shrinks to its working set and reopens connections
+     * on a burst; set {@code sender_pool_min} equal to {@code sender_pool_max}
+     * to keep every connection warm. Close-time errors are wrapped: only
+     * {@code LineSenderServerException} keeps its type, so code that catches
+     * another {@code LineSenderException} subclass around a pooled
+     * {@code close()} must look at {@code getCause()}. A real disconnect only
+     * happens at {@link #close()} on this {@code QuestDB} handle.
      * <p>
      * Allocation: zero at steady state -- the returned instance is a
      * pre-allocated decorator backed by a pre-allocated underlying Sender.