feat(facade): replace writeOnly with lazy_connect (read-capable tolerant startup)

Drop write-only mode (it permanently disabled reads -- query()/newQuery()
threw for the life of the handle) in favour of a read-capable tolerant-startup
flag, lazy_connect, reachable from the connect string.

lazy_connect=true:
- a) starts even when the server is down -- the ingest side connects async and
     the read pool defaults to query_pool_min=0, so neither side fail-fasts;
- b) buffers writes while the server is down (async sender);
- c) reads once the server is up -- the read pool stays ENABLED and connects
     lazily on the first query.

Because both sides must start non-blocking, a knob that forces a blocking /
fail-fast startup is a configuration conflict, rejected up front with a clear
remedy:
- initial_connect_retry other than async (off/false/on/true/sync), and
- an explicit query_pool_min > 0 (connect string or builder call).

Changes:
- ConfigSchema: write_only -> lazy_connect (Side.POOL; both clients ignore it).
- ConfigView.getBool: accept true/false (and on/off).
- QuestDBBuilder: remove writeOnly()/buildWriteOnly(); build() resolves
  lazy_connect, validates the two conflicts, defaults query_pool_min to 0 and
  injects initial_connect_retry=async when unset.
- QuestDBImpl: remove the write-only constructor/flag and requireQueryEnabled;
  the query pool is always built (the white-box reflection seam is unchanged).
- Tests: QuestDBWriteOnlyTest -> QuestDBLazyConnectTest (start+write while down,
  reads stay enabled, both conflicts via string and builder, true/on parsing);
  QuestDBServerRecoveryTest now dogfoods lazy_connect=true for the full
  down->write->up->read lifecycle; PoolConfigHonoredTest drift guard skips the
  flag.

Author: bluestreak01

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

@@ -41,7 +41,10 @@
  * Configuration: one {@code ws}/{@code wss} string describes the whole cluster
  * (a single {@code addr} server list) and both the ingest and query pools
  * connect across it. Use {@link #connect(CharSequence)} for the common case, or
- * {@link #builder()} for pool sizing, the ingest callbacks, and write-only mode.
+ * {@link #builder()} for pool sizing and the ingest callbacks. To tolerate the
+ * server being down at startup, set {@code lazy_connect=true} in the config
+ * (async ingest + lazy reads; reads stay enabled and connect once the server
+ * is up).
  * <p>
  * Thread safety: instances are safe to share. {@link #borrowSender()} and
  * {@link #query()} may be called concurrently from any thread; the pool
@@ -51,7 +54,7 @@ public interface QuestDB extends Closeable {
 
     /**
      * Builder for advanced configuration (pool sizes, acquisition timeouts,
-     * ingest callbacks, write-only mode).
+     * ingest callbacks).
      */
     static QuestDBBuilder builder() {
         return new QuestDBBuilder();
@@ -64,8 +67,9 @@ static QuestDBBuilder builder() {
      * protocol), so one string configures both clients. List every cluster node
      * in a single {@code addr} server list and both pools connect across it.
      * <p>
-     * Use {@link #builder()} for pool sizing, the ingest callbacks, and
-     * write-only mode.
+     * Use {@link #builder()} for pool sizing and the ingest callbacks. To
+     * tolerate the server being down at startup, set {@code lazy_connect=true}
+     * in the config (async ingest + lazy reads, reads still enabled).
      *
      * @param configurationString a {@code ws}/{@code wss} config string (see
      *                            {@link Sender#fromConfig} or

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

@@ -35,8 +35,13 @@
 
 /**
  * Builder for {@link QuestDB}. Most callers use {@link QuestDB#connect(CharSequence)};
- * this builder adds pool sizing, idle/lifetime knobs, the acquire timeout, the
- * ingest callbacks, and write-only mode.
+ * this builder adds pool sizing, idle/lifetime knobs, the acquire timeout, and
+ * the ingest callbacks.
+ * <p>
+ * To tolerate the server being down at startup, set {@code lazy_connect=true}
+ * in the config: the ingest side connects asynchronously (writes buffer until
+ * the wire is up) and the read pool connects lazily on first use. Reads stay
+ * fully enabled -- they just connect once the server is available.
  * <p>
  * One configuration string describes the whole QuestDB cluster (see
  * {@link #fromConfig}): list every node in a single {@code addr} server list and
@@ -72,10 +77,6 @@ public final class QuestDBBuilder {
     private int queryPoolMin = UNSET;
     private int senderPoolMax = UNSET;
     private int senderPoolMin = UNSET;
-    // When true, build() creates only the ingest (Sender) side: no query pool
-    // is constructed, so the facade starts even when the server / read primary
-    // is down, and query() is disabled. A query config is not required.
-    private boolean writeOnly;
 
     QuestDBBuilder() {
     }
@@ -93,26 +94,6 @@ public QuestDBBuilder acquireTimeoutMillis(long millis) {
         return this;
     }
 
-    /**
-     * Builds an ingest-only (write-only) handle: no query/read pool is created,
-     * so the facade starts even when the server / read primary is unavailable
-     * (the read side is normally fail-fast and would sink the whole facade).
-     * {@link QuestDB#query()} / {@link QuestDB#newQuery()} are disabled, and the
-     * read-side config keys are ignored.
-     * <p>
-     * Write-only also defaults the ingest side to a non-blocking async initial
-     * connect, so {@code build()} returns promptly even with the server down and
-     * the sender pool warm ({@code sender_pool_min >= 1}); writes buffer until
-     * the wire comes up. Override by setting {@code initial_connect_retry}
-     * explicitly in the config.
-     * <p>
-     * Equivalent to the {@code write_only=on} connect-string key.
-     */
-    public QuestDBBuilder writeOnly() {
-        this.writeOnly = true;
-        return this;
-    }
-
     /**
      * Sets the async connection-event listener applied to every pooled ingest
      * {@link Sender}. The listener observes connect / disconnect / failover
@@ -167,11 +148,6 @@ public QuestDB build() {
         }
         ConfigString cs = ConfigString.parse(config);
         ConfigView view = new ConfigView(cs);
-        // Write-only may be requested via the builder (writeOnly()) or the
-        // connect string (write_only=on); either skips the read pool.
-        if (writeOnly || view.getBoolOnOff("write_only", false)) {
-            return buildWriteOnly(view);
-        }
         // Validate the single cluster config exactly as both pools will, but
         // without connecting: the full Sender parse plus validateParameters
         // (ingress value keys are registry-STRING, so only the real parse
@@ -182,17 +158,28 @@ public QuestDB build() {
         Sender.LineSenderBuilder.validateWsConfigString(config);
         QwpQueryClient.validateConfig(view, "wss".equals(cs.schema()));
 
+        // lazy_connect: tolerate a down server at startup without disabling
+        // reads. The ingest side connects asynchronously (writes buffer until the
+        // wire is up) and the read pool defaults to min=0 -- it connects lazily
+        // on the first query once the server is up. Reads stay enabled.
+        boolean lazyConnect = view.getBool("lazy_connect", false);
+        String ingestConfig = config;
+        if (lazyConnect) {
+            ingestConfig = resolveLazyConnect(view);
+        }
+
         resolvePoolInt(senderPoolMin, "sender_pool_min", view, DEFAULT_POOL_MIN, this::senderPoolMin);
         resolvePoolInt(senderPoolMax, "sender_pool_max", view, DEFAULT_POOL_MAX, this::senderPoolMax);
-        resolvePoolInt(queryPoolMin, "query_pool_min", view, DEFAULT_POOL_MIN, this::queryPoolMin);
+        // lazy_connect makes the read pool lazy (min=0); without it the default min is 1.
+        resolvePoolInt(queryPoolMin, "query_pool_min", view, lazyConnect ? 0 : DEFAULT_POOL_MIN, this::queryPoolMin);
         resolvePoolInt(queryPoolMax, "query_pool_max", view, DEFAULT_POOL_MAX, this::queryPoolMax);
         resolvePoolLong(acquireTimeoutMillis, "acquire_timeout_ms", view, DEFAULT_ACQUIRE_TIMEOUT_MILLIS, this::acquireTimeoutMillis);
         resolvePoolLong(idleTimeoutMillis, "idle_timeout_ms", view, DEFAULT_IDLE_TIMEOUT_MILLIS, this::idleTimeoutMillis);
         resolvePoolLong(maxLifetimeMillis, "max_lifetime_ms", view, DEFAULT_MAX_LIFETIME_MILLIS, this::maxLifetimeMillis);
         resolvePoolLong(housekeeperIntervalMillis, "housekeeper_interval_ms", view, DEFAULT_HOUSEKEEPER_INTERVAL_MILLIS, this::housekeeperIntervalMillis);
 
         return new QuestDBImpl(
-                config,
+                ingestConfig,
                 config,
                 senderPoolMin,
                 senderPoolMax,
@@ -207,34 +194,43 @@ public QuestDB build() {
         );
     }
 
-    // Ingest-only build path: validates and resolves the sender + shared pool
-    // knobs from the ingest config alone and constructs a QuestDBImpl with no
-    // query pool. Never touches the read side, so a down server cannot fail it.
-    private QuestDB buildWriteOnly(ConfigView view) {
-        Sender.LineSenderBuilder.validateWsConfigString(config);
-        // writeOnly() owns "starts even when the server is down": default the
-        // ingest side to a non-blocking async initial connect so prewarming a
-        // sender (sender_pool_min >= 1) against a down server cannot fail-fast
-        // the build. An explicit initial_connect_retry in the user's string still
-        // wins (last-write-wins -- see withDefaultAsyncConnect).
-        String senderConfig = withDefaultAsyncConnect(config);
-        resolvePoolInt(senderPoolMin, "sender_pool_min", view, DEFAULT_POOL_MIN, this::senderPoolMin);
-        resolvePoolInt(senderPoolMax, "sender_pool_max", view, DEFAULT_POOL_MAX, this::senderPoolMax);
-        resolvePoolLong(acquireTimeoutMillis, "acquire_timeout_ms", view, DEFAULT_ACQUIRE_TIMEOUT_MILLIS, this::acquireTimeoutMillis);
-        resolvePoolLong(idleTimeoutMillis, "idle_timeout_ms", view, DEFAULT_IDLE_TIMEOUT_MILLIS, this::idleTimeoutMillis);
-        resolvePoolLong(maxLifetimeMillis, "max_lifetime_ms", view, DEFAULT_MAX_LIFETIME_MILLIS, this::maxLifetimeMillis);
-        resolvePoolLong(housekeeperIntervalMillis, "housekeeper_interval_ms", view, DEFAULT_HOUSEKEEPER_INTERVAL_MILLIS, this::housekeeperIntervalMillis);
-        return new QuestDBImpl(
-                senderConfig,
-                senderPoolMin,
-                senderPoolMax,
-                acquireTimeoutMillis,
-                idleTimeoutMillis,
-                maxLifetimeMillis,
-                housekeeperIntervalMillis,
-                errorHandler,
-                connectionListener
-        );
+    // Validates the lazy_connect contract and returns the ingest config to use:
+    // the original string with a non-blocking async initial connect injected
+    // when the user did not set one. lazy_connect requires BOTH sides to start
+    // non-blocking, so an explicit knob that forces a blocking / fail-fast
+    // startup is a configuration conflict and is rejected with a clear remedy.
+    private String resolveLazyConnect(ConfigView view) {
+        // (1) ingest side: only initial_connect_retry=async is non-blocking;
+        // off/false/on/true/sync all block or fail-fast at startup.
+        String mode = view.getStr("initial_connect_retry");
+        if (mode != null && !"async".equalsIgnoreCase(mode)) {
+            throw new IllegalArgumentException(
+                    "conflicting configuration: lazy_connect=true needs a non-blocking startup, but "
+                            + "initial_connect_retry=" + mode + " makes the initial connect block / fail-fast. "
+                            + "Resolve by removing initial_connect_retry (lazy_connect implies "
+                            + "initial_connect_retry=async) or setting initial_connect_retry=async.");
+        }
+        // (2) read side: lazy_connect requires query_pool_min=0 so the read pool
+        // does not eagerly fail-fast at startup. An explicit query_pool_min > 0
+        // (builder call or connect string) contradicts that.
+        int explicitQueryMin;
+        if (queryPoolMin != UNSET) {
+            explicitQueryMin = queryPoolMin; // explicit builder call
+        } else if (view.has("query_pool_min")) {
+            explicitQueryMin = view.getInt("query_pool_min", UNSET); // connect string
+        } else {
+            explicitQueryMin = 0; // unset -> lazy default of 0
+        }
+        if (explicitQueryMin > 0) {
+            throw new IllegalArgumentException(
+                    "conflicting configuration: lazy_connect=true needs query_pool_min=0 (the read pool "
+                            + "connects lazily on first use and must not fail-fast at startup), but query_pool_min="
+                            + explicitQueryMin + " was set. Resolve by removing query_pool_min (lazy_connect "
+                            + "defaults it to 0) or setting query_pool_min=0.");
+        }
+        // No explicit initial_connect_retry -> inject async so the ingest build
+        // is non-blocking. An explicit async needs no injection.
+        return mode == null ? withDefaultAsyncConnect(config) : config;
     }
 
     /**
@@ -382,11 +378,11 @@ public java.util.Map<String, Object> poolConfigSnapshotForTest() {
         return m;
     }
 
-    // writeOnly() owns "starts even when the server is down". Inject a
-    // non-blocking async initial connect right after the schema separator so
-    // build() never blocks or fail-fast on a down server. Placed first so an
-    // explicit initial_connect_retry later in the user's string overrides it
-    // (last-write-wins).
+    // Inject a non-blocking async initial connect right after the schema
+    // separator so lazy_connect's build never blocks or fail-fast on a down
+    // server. Only used when the user set no initial_connect_retry of their own
+    // (resolveLazyConnect rejects an explicit blocking mode rather than silently
+    // overriding it), so placement is immaterial -- there is no competing value.
     private static String withDefaultAsyncConnect(String config) {
         int sep = config.indexOf("::");
         // sep >= 0: fromConfig() validated a ws/wss schema, so "::" is present.

core/src/main/java/io/questdb/client/impl/ConfigSchema.java

@@ -112,7 +112,7 @@ public final class ConfigSchema {
         longRange("idle_timeout_ms", Side.POOL, OPEN, OPEN_MAX, false, false);
         longRange("max_lifetime_ms", Side.POOL, OPEN, OPEN_MAX, false, false);
         longRange("housekeeper_interval_ms", Side.POOL, OPEN, OPEN_MAX, false, false);
-        boolOnOff("write_only", Side.POOL); // facade routing flag: build an ingest-only handle
+        boolOnOff("lazy_connect", Side.POOL); // facade flag: tolerant non-blocking startup (async ingest + lazy reads)
 
         // RESERVED -- accepted no-op (error-policy keys reserved by the spec).
         str("on_internal_error", Side.RESERVED);

core/src/main/java/io/questdb/client/impl/ConfigView.java

@@ -95,6 +95,25 @@ public static String relocatedHint(String key) {
         return RELOCATED_HINTS.get(key);
     }
 
+    /**
+     * A boolean flag accepting {@code true}/{@code false} (and {@code on}/{@code off}
+     * for consistency with the rest of the connect-string surface). Returns
+     * {@code dflt} when the key is absent; throws on any other value.
+     */
+    public boolean getBool(String key, boolean dflt) {
+        String v = getStr(key);
+        if (v == null) {
+            return dflt;
+        }
+        if ("true".equals(v) || "on".equals(v)) {
+            return true;
+        }
+        if ("false".equals(v) || "off".equals(v)) {
+            return false;
+        }
+        throw new IllegalArgumentException("invalid " + key + ": " + v + " (expected true, false)");
+    }
+
     public boolean getBoolOnOff(String key, boolean dflt) {
         String v = getStr(key);
         if (v == null) {

core/src/main/java/io/questdb/client/impl/QuestDBImpl.java

@@ -66,26 +66,7 @@ public QuestDBImpl(
     ) {
         this(ingestConfig, queryConfig, senderMin, senderMax, queryMin, queryMax,
                 acquireTimeoutMillis, idleTimeoutMillis, maxLifetimeMillis,
-                housekeeperIntervalMillis, null, null, errorHandler, connectionListener, false);
-    }
-
-    // Write-only (ingest-only) handle: no query pool is created, so build()
-    // never touches the read side and the facade starts even when the
-    // server / read primary is unavailable. query()/newQuery() are disabled.
-    public QuestDBImpl(
-            String ingestConfig,
-            int senderMin,
-            int senderMax,
-            long acquireTimeoutMillis,
-            long idleTimeoutMillis,
-            long maxLifetimeMillis,
-            long housekeeperIntervalMillis,
-            SenderErrorHandler errorHandler,
-            SenderConnectionListener connectionListener
-    ) {
-        this(ingestConfig, null, senderMin, senderMax, 0, 0,
-                acquireTimeoutMillis, idleTimeoutMillis, maxLifetimeMillis,
-                housekeeperIntervalMillis, null, null, errorHandler, connectionListener, true);
+                housekeeperIntervalMillis, null, null, errorHandler, connectionListener);
     }
 
     // Package-private constructor exposing the senderFactory and connectHook test
@@ -110,7 +91,7 @@ public QuestDBImpl(
     ) {
         this(ingestConfig, queryConfig, senderMin, senderMax, queryMin, queryMax,
                 acquireTimeoutMillis, idleTimeoutMillis, maxLifetimeMillis,
-                housekeeperIntervalMillis, senderFactory, connectHook, null, null, false);
+                housekeeperIntervalMillis, senderFactory, connectHook, null, null);
     }
 
     // Full constructor adding the ingest-side errorHandler/connectionListener,
@@ -131,8 +112,7 @@ public QuestDBImpl(
             IntFunction<Sender> senderFactory,
             Consumer<QwpQueryClient> connectHook,
             SenderErrorHandler errorHandler,
-            SenderConnectionListener connectionListener,
-            boolean writeOnly
+            SenderConnectionListener connectionListener
     ) {
         SenderPool builtSenderPool = null;
         QueryClientPool builtQueryPool = null;
@@ -146,13 +126,9 @@ public QuestDBImpl(
                     // server; the housekeeper drives it via runStartupRecoveryStep().
                     true,
                     errorHandler, connectionListener);
-            // Write-only: skip the read side entirely so a down server / read
-            // primary cannot fail the facade build.
-            if (!writeOnly) {
-                builtQueryPool = new QueryClientPool(
-                        queryConfig, queryMin, queryMax, acquireTimeoutMillis,
-                        idleTimeoutMillis, maxLifetimeMillis, connectHook);
-            }
+            builtQueryPool = new QueryClientPool(
+                    queryConfig, queryMin, queryMax, acquireTimeoutMillis,
+                    idleTimeoutMillis, maxLifetimeMillis, connectHook);
             builtHousekeeper = new PoolHousekeeper(builtSenderPool, builtQueryPool, housekeeperIntervalMillis);
             builtHousekeeper.start();
         } catch (Throwable e) {
@@ -182,7 +158,7 @@ public QuestDBImpl(
         this.senderPool = builtSenderPool;
         this.queryPool = builtQueryPool;
         this.housekeeper = builtHousekeeper;
-        this.queryThreadLocal = writeOnly ? null : ThreadLocal.withInitial(() -> new QueryImpl(queryPool));
+        this.queryThreadLocal = ThreadLocal.withInitial(() -> new QueryImpl(queryPool));
     }
 
     @Override
@@ -243,24 +219,16 @@ public Completion executeSql(CharSequence sql, QwpColumnBatchHandler handler) {
 
     @Override
     public Query newQuery() {
-        requireQueryEnabled();
         return new QueryImpl(queryPool);
     }
 
     @Override
     public Query query() {
-        requireQueryEnabled();
         QueryImpl q = queryThreadLocal.get();
         q.resetIfDone();
         return q;
     }
 
-    private void requireQueryEnabled() {
-        if (queryPool == null) {
-            throw new IllegalStateException("query/read is disabled on a write-only QuestDB client");
-        }
-    }
-
     @Override
     public void releaseSender() {
         senderPool.releaseCurrentThread();