feat(facade): add write-only mode so the handle starts without a server

The QuestDB facade always built a reader (QueryClientPool), which prewarms
synchronously and fail-fast (default query_pool_min=1, QwpQueryClient has no
async connect). So a down server / read primary sank the whole facade build,
taking the write side with it.

Add QuestDBBuilder.writeOnly(): build an ingest-only handle that never
constructs the query pool, so the read side cannot fail startup. A query
config is no longer required in this mode (any query config set is ignored),
and query()/newQuery() throw a clear "write-only" IllegalStateException.

- QuestDBImpl gains a write-only public constructor + a writeOnly flag on the
  full constructor; the 12-arg white-box test-seam constructor stays unchanged
  (delegates with writeOnly=false). queryPool/queryThreadLocal are null in
  write-only mode.
- PoolHousekeeper tolerates a null query pool.
- QuestDBBuilder.buildWriteOnly() validates + resolves only the sender/shared
  pool knobs from the ingest config.

Pair with initial_connect_retry=async (or sender_pool_min=0) on the ingest
config so the write side does not fail-fast either -> the facade starts with
no server present.

Tests: QuestDBWriteOnlyTest proves the facade builds with no server, that
query()/newQuery() are disabled, that no query config is required, and that an
async warm sender can buffer a write while serverless.

Author: bluestreak01

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

@@ -72,6 +72,10 @@ 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() {
     }
@@ -89,6 +93,21 @@ 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 a
+     * query configuration is not required (any query config set is ignored).
+     * <p>
+     * Pair with {@code initial_connect_retry=async} (or {@code sender_pool_min=0})
+     * on the ingest config so the write side does not fail-fast either.
+     */
+    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
@@ -141,6 +160,9 @@ public QuestDB build() {
         if (ingestConfig == null) {
             throw new IllegalStateException("ingest configuration is required; call fromConfig() or ingestConfig()");
         }
+        if (writeOnly) {
+            return buildWriteOnly();
+        }
         if (queryConfig == null) {
             throw new IllegalStateException("query configuration is required; call fromConfig() or queryConfig()");
         }
@@ -184,6 +206,34 @@ 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() {
+        ConfigString ingestCs = ConfigString.parse(ingestConfig);
+        ConfigView ingestView = new ConfigView(ingestCs);
+        Sender.LineSenderBuilder.validateWsConfigString(ingestConfig);
+        // Only the ingest view applies; pass it for both sides so the existing
+        // resolvers (which cross-check ingest vs query) read a single source.
+        resolvePoolInt(senderPoolMin, "sender_pool_min", ingestView, ingestView, DEFAULT_POOL_MIN, this::senderPoolMin);
+        resolvePoolInt(senderPoolMax, "sender_pool_max", ingestView, ingestView, DEFAULT_POOL_MAX, this::senderPoolMax);
+        resolvePoolLong(acquireTimeoutMillis, "acquire_timeout_ms", ingestView, ingestView, DEFAULT_ACQUIRE_TIMEOUT_MILLIS, this::acquireTimeoutMillis);
+        resolvePoolLong(idleTimeoutMillis, "idle_timeout_ms", ingestView, ingestView, DEFAULT_IDLE_TIMEOUT_MILLIS, this::idleTimeoutMillis);
+        resolvePoolLong(maxLifetimeMillis, "max_lifetime_ms", ingestView, ingestView, DEFAULT_MAX_LIFETIME_MILLIS, this::maxLifetimeMillis);
+        resolvePoolLong(housekeeperIntervalMillis, "housekeeper_interval_ms", ingestView, ingestView, DEFAULT_HOUSEKEEPER_INTERVAL_MILLIS, this::housekeeperIntervalMillis);
+        return new QuestDBImpl(
+                ingestConfig,
+                senderPoolMin,
+                senderPoolMax,
+                acquireTimeoutMillis,
+                idleTimeoutMillis,
+                maxLifetimeMillis,
+                housekeeperIntervalMillis,
+                errorHandler,
+                connectionListener
+        );
+    }
+
     /**
      * Sets a single configuration string used for both ingest and egress. The
      * schema must be {@code ws} or {@code wss}.

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

@@ -126,7 +126,10 @@ private void runLoop() {
                 // thread and stop all future reaping for the life of the handle.
             }
             try {
-                queryPool.reapIdle();
+                // queryPool is null for a write-only (ingest-only) handle.
+                if (queryPool != null) {
+                    queryPool.reapIdle();
+                }
             } catch (Throwable ignored) {
                 // Same rationale as the senderPool guard above: best-effort,
                 // must never propagate, and Throwable (not RuntimeException) so

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

@@ -66,7 +66,26 @@ public QuestDBImpl(
     ) {
         this(ingestConfig, queryConfig, senderMin, senderMax, queryMin, queryMax,
                 acquireTimeoutMillis, idleTimeoutMillis, maxLifetimeMillis,
-                housekeeperIntervalMillis, null, null, errorHandler, connectionListener);
+                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);
     }
 
     // Package-private constructor exposing the senderFactory and connectHook test
@@ -91,7 +110,7 @@ public QuestDBImpl(
     ) {
         this(ingestConfig, queryConfig, senderMin, senderMax, queryMin, queryMax,
                 acquireTimeoutMillis, idleTimeoutMillis, maxLifetimeMillis,
-                housekeeperIntervalMillis, senderFactory, connectHook, null, null);
+                housekeeperIntervalMillis, senderFactory, connectHook, null, null, false);
     }
 
     // Full constructor adding the ingest-side errorHandler/connectionListener,
@@ -112,7 +131,8 @@ public QuestDBImpl(
             IntFunction<Sender> senderFactory,
             Consumer<QwpQueryClient> connectHook,
             SenderErrorHandler errorHandler,
-            SenderConnectionListener connectionListener
+            SenderConnectionListener connectionListener,
+            boolean writeOnly
     ) {
         SenderPool builtSenderPool = null;
         QueryClientPool builtQueryPool = null;
@@ -126,9 +146,13 @@ public QuestDBImpl(
                     // server; the housekeeper drives it via runStartupRecoveryStep().
                     true,
                     errorHandler, connectionListener);
-            builtQueryPool = new QueryClientPool(
-                    queryConfig, queryMin, queryMax, acquireTimeoutMillis,
-                    idleTimeoutMillis, maxLifetimeMillis, connectHook);
+            // 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);
+            }
             builtHousekeeper = new PoolHousekeeper(builtSenderPool, builtQueryPool, housekeeperIntervalMillis);
             builtHousekeeper.start();
         } catch (Throwable e) {
@@ -158,7 +182,7 @@ public QuestDBImpl(
         this.senderPool = builtSenderPool;
         this.queryPool = builtQueryPool;
         this.housekeeper = builtHousekeeper;
-        this.queryThreadLocal = ThreadLocal.withInitial(() -> new QueryImpl(queryPool));
+        this.queryThreadLocal = writeOnly ? null : ThreadLocal.withInitial(() -> new QueryImpl(queryPool));
     }
 
     @Override
@@ -219,16 +243,24 @@ 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();

core/src/test/java/io/questdb/client/test/QuestDBWriteOnlyTest.java

@@ -0,0 +1,97 @@
+/*+*****************************************************************************
+ *     ___                  _   ____  ____
+ *    / _ \ _   _  ___  ___| |_|  _ \| __ )
+ *   | | | | | | |/ _ \/ __| __| | | |  _ \
+ *   | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+ *    \__\_\\__,_|\___||___/\__|____/|____/
+ *
+ *  Copyright (c) 2014-2019 Appsicle
+ *  Copyright (c) 2019-2026 QuestDB
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ ******************************************************************************/
+
+package io.questdb.client.test;
+
+import io.questdb.client.QuestDB;
+import io.questdb.client.Sender;
+import io.questdb.client.test.cutlass.qwp.client.TestPorts;
+import org.junit.Assert;
+import org.junit.Test;
+
+/**
+ * A write-only (ingest-only) {@link QuestDB} facade skips the read pool, which
+ * is otherwise fail-fast at startup -- so the handle builds even when the
+ * server / read primary is unavailable.
+ */
+public class QuestDBWriteOnlyTest {
+
+    @Test
+    public void testWriteOnlyDoesNotRequireQueryConfig() {
+        int port = TestPorts.findUnusedPort();
+        // Only an ingest config is supplied -- no queryConfig()/fromConfig().
+        try (QuestDB db = QuestDB.builder()
+                .ingestConfig("ws::addr=localhost:" + port + ";sender_pool_min=0;")
+                .writeOnly()
+                .build()) {
+            Assert.assertNotNull(db);
+        }
+    }
+
+    @Test
+    public void testWriteOnlyIngestWorksWhileServerless() {
+        int port = TestPorts.findUnusedPort();
+        // Warm one sender in async mode against a dead port: build() returns an
+        // unconnected-but-usable sender; writes buffer until the wire is up.
+        try (QuestDB db = QuestDB.builder()
+                .fromConfig("ws::addr=localhost:" + port + ";sender_pool_min=1;sender_pool_max=1"
+                        + ";initial_connect_retry=async"
+                        + ";reconnect_max_duration_millis=400;reconnect_initial_backoff_millis=10"
+                        + ";reconnect_max_backoff_millis=50;close_flush_timeout_millis=0;")
+                .writeOnly()
+                .build()) {
+            Sender sender = db.borrowSender();
+            Assert.assertNotNull("a sender must be available with no server present", sender);
+            // Buffering a row against an unconnected sender must not throw.
+            sender.table("t").longColumn("v", 1L).atNow();
+        }
+    }
+
+    @Test
+    public void testWriteOnlyStartsWithoutServerAndDisablesQuery() {
+        int port = TestPorts.findUnusedPort();
+        // No server at `port`. A normal facade builds the read pool eagerly
+        // (query_pool_min defaults to 1) and would fail-fast here; write-only
+        // skips it, and sender_pool_min=0 means no eager ingest connect either,
+        // so build() performs no network I/O and succeeds.
+        try (QuestDB db = QuestDB.builder()
+                .fromConfig("ws::addr=localhost:" + port + ";sender_pool_min=0;")
+                .writeOnly()
+                .build()) {
+            assertQueryDisabled(db::query);
+            assertQueryDisabled(db::newQuery);
+        }
+    }
+
+    private static void assertQueryDisabled(Runnable read) {
+        try {
+            read.run();
+            Assert.fail("query/read must be disabled on a write-only client");
+        } catch (IllegalStateException expected) {
+            Assert.assertTrue(
+                    "message should explain write-only: " + expected.getMessage(),
+                    expected.getMessage().toLowerCase().contains("write-only"));
+        }
+    }
+}