questdb 0.1.0 → 0.1.1

data/test/extconf_link_flags_test.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   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.
+require "minitest/autorun"
+require "json"
+require "open3"
+require "rbconfig"
+require "tmpdir"
+
+# Generates a real Makefile with mkmf under each build Ruby's link settings
+# and checks the expanded link flags. The macOS values are copied from the
+# rbconfig.rb of the ruby/ruby-builder Rubies the release pipeline builds
+# with; 0.1.0's macOS gems linked libruby through them.
+#
+# The scenarios are hermetic: each sets every RbConfig key that reaches an
+# extension's link line, so the host Ruby cannot change the result. The test
+# still runs only on Linux hosts. Its subject is the fake configurations, so
+# other hosts add no coverage, and the release pipeline checks the real macOS
+# and Windows extensions with script/check-native-linkage.
+class ExtconfLinkFlagsTest < Minitest::Test
+  HELPER = File.expand_path("../ext/questdb_ingress/unlink_build_ruby.rb", __dir__)
+
+  # Every key mkmf's init_mkmf and the Makefile's DLDFLAGS/LIBS read.
+  NEUTRAL = {
+    "LDFLAGS" => "", "DLDFLAGS" => "", "ADDITIONAL_DLDFLAGS" => "", "EXTDLDFLAGS" => "",
+    "ARCH_FLAG" => "", "LIBS" => "", "DLDLIBS" => "", "ENABLE_SHARED" => "yes", "RUBY_SO_NAME" => "ruby",
+    "LIBRUBYARG" => "$(LIBRUBYARG_SHARED)", "LIBRUBYARG_SHARED" => "-l$(RUBY_SO_NAME)",
+    "LIBRUBYARG_STATIC" => "-l$(RUBY_SO_NAME)-static"
+  }.freeze
+
+  DARWIN_SHARED_31 = NEUTRAL.merge(
+    "RUBY_SO_NAME" => "ruby.3.1",
+    "EXTDLDFLAGS" => "$(LIBRUBYARG_SHARED)",
+    "DLDFLAGS" => "-L/usr/local/opt/gmp/lib -Wl,-undefined,dynamic_lookup"
+  ).freeze
+  DARWIN_STATIC_31 = NEUTRAL.merge(
+    "ENABLE_SHARED" => "no",
+    "LIBRUBYARG" => "$(LIBRUBYARG_STATIC)",
+    "LIBRUBYARG_SHARED" => "",
+    "EXTDLDFLAGS" => "-bundle_loader '$(BUILTRUBY)'",
+    "DLDFLAGS" => "-L/opt/homebrew/opt/gmp/lib -Wl,-undefined,dynamic_lookup"
+  ).freeze
+  DARWIN_SHARED_34 = NEUTRAL.merge(
+    "RUBY_SO_NAME" => "ruby.3.4",
+    "DLDFLAGS" => "-Wl,-multiply_defined,suppress"
+  ).freeze
+  LINUX = NEUTRAL
+  WINDOWS = NEUTRAL.merge("RUBY_SO_NAME" => "x64-ucrt-ruby340").freeze
+
+  # Simulated host Rubies with noisy values for every key, applied before the
+  # scenario: a hermetic scenario gives the same flags under each of them.
+  HOSTS = {
+    "linux" => { "LDFLAGS" => "-L. -fstack-protector-strong -rdynamic -Wl,-export-dynamic",
+                 "DLDFLAGS" => "-Wl,-z,relro", "LIBS" => "-lm -lpthread", "RUBY_SO_NAME" => "ruby" },
+    "macos-shared" => { "DLDFLAGS" => "-L/usr/local/opt/gmp/lib -Wl,-undefined,dynamic_lookup",
+                        "EXTDLDFLAGS" => "$(LIBRUBYARG_SHARED)", "RUBY_SO_NAME" => "ruby.3.2",
+                        "LDFLAGS" => "-L/usr/local/lib -Wl,-undefined,dynamic_lookup", "LIBS" => "-lpthread" },
+    "macos-static" => { "ENABLE_SHARED" => "no", "LIBRUBYARG" => "$(LIBRUBYARG_STATIC)", "LIBRUBYARG_SHARED" => "",
+                        "EXTDLDFLAGS" => "-bundle_loader '$(BUILTRUBY)'", "ADDITIONAL_DLDFLAGS" => "-Wl,-x" },
+    "windows" => { "RUBY_SO_NAME" => "x64-ucrt-ruby340", "LIBRUBYARG_SHARED" => "-lx64-ucrt-ruby340",
+                   "DLDFLAGS" => "-Wl,--enable-auto-image-base", "LIBS" => "-lshell32 -lws2_32",
+                   "DLDLIBS" => "-lx64-ucrt-ruby340", "ARCH_FLAG" => "-m64" }
+  }.freeze
+
+  PROBE = <<~'RUBY'
+    require "mkmf"
+    require "json"
+    [ENV.fetch("HOST_RBCONFIG"), ENV.fetch("FAKE_RBCONFIG")].map { |json| JSON.parse(json) }.reduce(:merge).each do |key, value|
+      RbConfig::MAKEFILE_CONFIG[key] = value
+      RbConfig::CONFIG[key] = value
+    end
+    init_mkmf(RbConfig::MAKEFILE_CONFIG, RbConfig::CONFIG)
+    if ENV["APPLY_HELPER"] == "1"
+      require ENV.fetch("HELPER")
+      QuestDBExtconf.unlink_build_ruby!(ENV.fetch("FAKE_HOST_OS"))
+    end
+    create_makefile("probe")
+  RUBY
+
+  def setup
+    skip "probes fake build Ruby configurations; runs on Linux hosts only" unless RUBY_PLATFORM.include?("linux")
+  end
+
+  def link_flags(config, host_os, apply:, host: {})
+    Dir.mktmpdir do |dir|
+      File.write(File.join(dir, "probe.c"), "void Init_probe(void) {}\n")
+      File.write(File.join(dir, "print.mk"), "print:\n\t@echo $(DLDFLAGS) $(LIBS)\n")
+      env = { "FAKE_RBCONFIG" => JSON.generate(config), "HOST_RBCONFIG" => JSON.generate(host),
+              "FAKE_HOST_OS" => host_os, "HELPER" => HELPER, "APPLY_HELPER" => apply ? "1" : "0" }
+      out, status = Open3.capture2e(env, RbConfig.ruby, "-e", PROBE, chdir: dir)
+      assert status.success?, out
+      flags, status = Open3.capture2e("make", "-s", "-f", "Makefile", "-f", "print.mk", "print", chdir: dir)
+      assert status.success?, flags
+      flags.strip
+    end
+  end
+
+  # Runs the block once per simulated host and checks the result does not
+  # depend on the host.
+  def each_host(config, host_os, apply:)
+    results = HOSTS.to_h { |name, host| [name, link_flags(config, host_os, apply: apply, host: host)] }
+    assert_equal 1, results.values.uniq.size, "flags depend on the host Ruby: #{results.inspect}"
+    results.values.first
+  end
+
+  def assert_unlinked(flags)
+    refute_match(/-lruby|libruby|bundle_loader|RUBY_SO_NAME|BUILTRUBY/, flags)
+  end
+
+  def test_macos_shared_ruby_31_does_not_link_libruby
+    assert_match(/-lruby\.3\.1/, each_host(DARWIN_SHARED_31, "darwin22", apply: false), "probe must see libruby")
+    flags = each_host(DARWIN_SHARED_31, "darwin22", apply: true)
+    assert_unlinked(flags)
+    assert_match(/-undefined,dynamic_lookup/, flags)
+  end
+
+  def test_macos_static_ruby_31_does_not_bind_to_the_executable
+    assert_match(/bundle_loader/, each_host(DARWIN_STATIC_31, "darwin23", apply: false), "probe must see -bundle_loader")
+    flags = each_host(DARWIN_STATIC_31, "darwin23", apply: true)
+    assert_unlinked(flags)
+    assert_match(/-undefined,dynamic_lookup/, flags)
+  end
+
+  def test_macos_shared_ruby_34_does_not_link_libruby
+    assert_match(/-lruby\.3\.4/, each_host(DARWIN_SHARED_34, "darwin24", apply: false), "probe must see libruby")
+    flags = each_host(DARWIN_SHARED_34, "darwin24", apply: true)
+    assert_unlinked(flags)
+    assert_match(/-undefined,dynamic_lookup/, flags)
+  end
+
+  def test_linux_does_not_link_libruby
+    assert_match(/-lruby/, each_host(LINUX, "linux-gnu", apply: false), "probe must see libruby")
+    flags = each_host(LINUX, "linux-gnu", apply: true)
+    assert_unlinked(flags)
+    refute_match(/dynamic_lookup/, flags)
+  end
+
+  def test_windows_keeps_the_ruby_dll
+    assert_match(/-lx64-ucrt-ruby340/, each_host(WINDOWS, "mingw32", apply: true))
+  end
+end

data/vendor/c-questdb-client/.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "7.1.0"
+current_version = "7.2.0"
 commit = false
 tag = false
 

data/vendor/c-questdb-client/CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.15.0)
-project(c-questdb-client VERSION 7.1.0)
+project(c-questdb-client VERSION 7.2.0)
 
 set(CPACK_PROJECT_NAME ${PROJECT_NAME})
 set(CPACK_PROJECT_VERSION ${PROJECT_VERSION})

data/vendor/c-questdb-client/cpp_test/qwp_mock_server.hpp

@@ -67,8 +67,12 @@ inline constexpr uint8_t ROLE_PRIMARY = 0x01;
 inline constexpr uint8_t ROLE_REPLICA = 0x02;
 inline constexpr uint8_t ROLE_PRIMARY_CATCHUP = 0x03;
 
-// SERVER_INFO capability bits.
+// SERVER_INFO capability bits (mirror
+// questdb-rs/src/egress/wire/capabilities.rs).
 inline constexpr uint32_t CAP_ZONE = 0x00000001u;
+inline constexpr uint32_t CAP_QUERY_FLAGS = 0x00000002u;
+inline constexpr uint32_t CAP_COMPRESSION = 0x00000004u;
+inline constexpr uint32_t CAP_QUERY_TIMEOUT = 0x00000008u;
 
 // ColumnKind wire codes (mirror questdb-rs/src/egress/column_kind.rs).
 inline constexpr uint8_t COL_BOOLEAN = 0x01;
@@ -102,6 +106,11 @@ inline constexpr uint8_t STATUS_INTERNAL_ERROR = 0x06;
 inline constexpr uint8_t STATUS_SECURITY_ERROR = 0x08;
 inline constexpr uint8_t STATUS_CANCELLED = 0x0A;
 inline constexpr uint8_t STATUS_LIMIT_EXCEEDED = 0x0B;
+inline constexpr uint8_t STATUS_QUERY_TIMEOUT = 0x0E;
+
+// QUERY_REQUEST `query_flags` bits (mirror query_request.rs).
+inline constexpr uint8_t QUERY_FLAG_RESET_DICT = 0x01;
+inline constexpr uint8_t QUERY_FLAG_TIMEOUT = 0x02;
 
 // CACHE_RESET masks.
 inline constexpr uint8_t CACHE_RESET_SYMBOLS = 0x01;

data/vendor/c-questdb-client/cpp_test/test_arrow_c.c

@@ -117,6 +117,43 @@ TEST(test_symbol_dict_full_is_a_distinct_appended_code)
         "neutral alias resolves to the same enumerator");
 }
 
+TEST(test_query_timeout_is_a_distinct_appended_code)
+{
+    /* A query that ran past its own timeout must be recognisable by code:
+     * callers branch on it to avoid retrying a write the server may have
+     * applied anyway. */
+    CHECK(
+        line_sender_error_query_timeout != line_sender_error_cancelled,
+        "query_timeout distinct from cancelled");
+    CHECK(
+        line_sender_error_query_timeout !=
+            line_sender_error_server_limit_exceeded,
+        "query_timeout distinct from server_limit_exceeded");
+    CHECK(
+        line_sender_error_query_timeout != line_sender_error_invalid_api_call,
+        "query_timeout distinct from invalid_api_call");
+    CHECK(
+        line_sender_error_query_timeout > line_sender_error_symbol_dict_full,
+        "query_timeout appended (not renumbered)");
+    CHECK(
+        line_sender_error_query_timeout == 38,
+        "query_timeout discriminant pinned at 38 for cached ABI consumers");
+    CHECK(
+        questdb_error_query_timeout == line_sender_error_query_timeout,
+        "neutral alias resolves to the same enumerator");
+}
+
+TEST(test_query_set_timeout_ms_null_query_is_tolerated)
+{
+    /* Proves the symbol links and argument-marshals under a plain C
+     * compiler (the Cython contract surface), and that the NULL-handle
+     * contract shared by every `qwp_reader_query_*` mutator holds: report
+     * and return, never crash. */
+    qwp_reader_query_set_timeout_ms(NULL, 1000);
+    qwp_reader_query_set_timeout_ms(NULL, 0);
+    CHECK(true, "NULL query handle did not crash");
+}
+
 TEST(test_egress_null_cursor_returns_error_tristate)
 {
     struct ArrowArray arr;
@@ -1609,6 +1646,8 @@ int main(void)
     RUN(test_appended_query_error_codes_have_distinct_values);
     RUN(test_appended_sender_error_codes_exist);
     RUN(test_symbol_dict_full_is_a_distinct_appended_code);
+    RUN(test_query_timeout_is_a_distinct_appended_code);
+    RUN(test_query_set_timeout_ms_null_query_is_tolerated);
     RUN(test_egress_null_cursor_returns_error_tristate);
     RUN(test_egress_null_out_array_returns_error_tristate);
     RUN(test_ingress_null_conn_returns_false);

data/vendor/c-questdb-client/cpp_test/test_reader_mock.cpp

@@ -38,6 +38,7 @@
 #include <chrono>
 #include <cstring>
 #include <exception>
+#include <limits>
 #include <memory>
 #include <mutex>
 #include <optional>
@@ -675,6 +676,433 @@ TEST_CASE("mock: QueryError(cancelled) surfaces as Cancelled")
 // and the server's CANCELLED status surfaces as the documented error code.
 // ---------------------------------------------------------------------------
 
+TEST_CASE("mock: QueryError(query_timeout) surfaces as QueryTimeout")
+{
+    run_query_error_test(qm::STATUS_QUERY_TIMEOUT, questdb_error_query_timeout);
+}
+
+// ---------------------------------------------------------------------------
+// Per-query timeout (CAP_QUERY_TIMEOUT / QUERY_FLAG_TIMEOUT / timeout_ms).
+// ---------------------------------------------------------------------------
+
+namespace
+{
+// A SERVER_INFO advertising the capabilities a current server sends.
+qm::ActionSendServerInfo server_info_with(uint32_t caps)
+{
+    qm::ActionSendServerInfo si;
+    si.capabilities = caps;
+    return si;
+}
+
+// Offset of the `query_flags` trailer in a QUERY_REQUEST with no binds:
+// msg_kind(1) + request_id(8) + varint sql_len(1) + sql + varint credit(1)
+// + varint bind_count(1).
+size_t trailer_offset(size_t sql_len)
+{
+    return 1 + 8 + 1 + sql_len + 1 + 1;
+}
+} // namespace
+
+TEST_CASE("mock: no timeout -> QUERY_REQUEST carries no trailer")
+{
+    // The baseline an older server has always seen. Byte-exactness here is
+    // what makes the feature safe to ship against one.
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+    auto cur = reader.execute("X"_utf8);
+    while (cur.next_batch())
+    {
+    }
+
+    auto reqs = srv.captured_requests();
+    REQUIRE(reqs.size() == 1);
+    CHECK(reqs[0].size() == trailer_offset(1));
+}
+
+TEST_CASE("mock: timeout_ms rides the wire after query_flags")
+{
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+    auto cur = reader.prepare("X"_utf8).timeout_ms(1000).execute();
+    while (cur.next_batch())
+    {
+    }
+
+    auto reqs = srv.captured_requests();
+    REQUIRE(reqs.size() == 1);
+    const auto& req = reqs[0];
+    const size_t p = trailer_offset(1);
+    // flags varint = QUERY_FLAG_TIMEOUT, then timeout_ms varint
+    // (1000 = 0xE8 0x07).
+    REQUIRE(req.size() == p + 3);
+    CHECK(req[p] == qm::QUERY_FLAG_TIMEOUT);
+    CHECK(req[p + 1] == 0xE8);
+    CHECK(req[p + 2] == 0x07);
+}
+
+TEST_CASE("mock: chrono timeout rounds a sub-millisecond value up to 1 ms")
+{
+    // Rounding down would mean "no timeout" — the opposite of the ask.
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+    auto cur = reader.prepare("X"_utf8)
+                   .timeout(std::chrono::microseconds{500})
+                   .execute();
+    while (cur.next_batch())
+    {
+    }
+
+    auto reqs = srv.captured_requests();
+    REQUIRE(reqs.size() == 1);
+    const auto& req = reqs[0];
+    const size_t p = trailer_offset(1);
+    REQUIRE(req.size() == p + 2);
+    CHECK(req[p] == qm::QUERY_FLAG_TIMEOUT);
+    CHECK(req[p + 1] == 1);
+}
+
+TEST_CASE("mock: chrono timeout converts seconds to milliseconds")
+{
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+    auto cur =
+        reader.prepare("X"_utf8).timeout(std::chrono::seconds{2}).execute();
+    while (cur.next_batch())
+    {
+    }
+
+    auto reqs = srv.captured_requests();
+    REQUIRE(reqs.size() == 1);
+    const auto& req = reqs[0];
+    const size_t p = trailer_offset(1);
+    // timeout_ms varint 2000 = 0xD0 0x0F.
+    REQUIRE(req.size() == p + 3);
+    CHECK(req[p] == qm::QUERY_FLAG_TIMEOUT);
+    CHECK(req[p + 1] == 0xD0);
+    CHECK(req[p + 2] == 0x0F);
+}
+
+TEST_CASE("mock: chrono timeout rejects negative and non-finite durations")
+{
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+    using ms_f = std::chrono::duration<double, std::milli>;
+    for (double v :
+         {-1.0,
+          std::numeric_limits<double>::quiet_NaN(),
+          std::numeric_limits<double>::infinity()})
+    {
+        auto q = reader.prepare("X"_utf8);
+        try
+        {
+            q.timeout(ms_f{v});
+            FAIL("negative or non-finite timeout must throw");
+        }
+        catch (const questdb::error& e)
+        {
+            CHECK(e.code() == questdb_error_invalid_api_call);
+        }
+    }
+}
+
+TEST_CASE("mock: chrono timeout saturates instead of overflowing")
+{
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+    using hours64 = std::chrono::duration<int64_t, std::ratio<3600>>;
+    auto cur = reader.prepare("X"_utf8).timeout(hours64::max()).execute();
+    while (cur.next_batch())
+    {
+    }
+
+    auto reqs = srv.captured_requests();
+    REQUIRE(reqs.size() == 1);
+    const auto& req = reqs[0];
+    const size_t p = trailer_offset(1);
+    // timeout_ms = INT64_MAX (the server reads a signed long): eight 0xFF
+    // continuation bytes, then 0x7F.
+    REQUIRE(req.size() == p + 10);
+    CHECK(req[p] == qm::QUERY_FLAG_TIMEOUT);
+    for (size_t i = 1; i < 9; ++i)
+        CHECK(req[p + i] == 0xFF);
+    CHECK(req[p + 9] == 0x7F);
+}
+
+TEST_CASE("mock: chrono zero timeout clears the request")
+{
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+    auto cur =
+        reader.prepare("X"_utf8).timeout(std::chrono::seconds{0}).execute();
+    while (cur.next_batch())
+    {
+    }
+
+    auto reqs = srv.captured_requests();
+    REQUIRE(reqs.size() == 1);
+    CHECK(reqs[0].size() == trailer_offset(1));
+}
+
+TEST_CASE("mock: connect-string query_timeout_ms applies to every query")
+{
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    const std::string conf =
+        "ws::addr=" + srv.addr() + ";query_timeout_ms=1000;";
+    eg::reader reader{questdb::ingress::utf8_view{conf}};
+
+    for (int i = 0; i < 2; ++i)
+    {
+        auto cur = reader.execute("X"_utf8);
+        while (cur.next_batch())
+        {
+        }
+    }
+
+    auto reqs = srv.captured_requests();
+    REQUIRE(reqs.size() == 2);
+    for (const auto& req : reqs)
+    {
+        const size_t p = trailer_offset(1);
+        REQUIRE(req.size() == p + 3);
+        CHECK(req[p] == qm::QUERY_FLAG_TIMEOUT);
+        CHECK(req[p + 1] == 0xE8);
+        CHECK(req[p + 2] == 0x07);
+    }
+}
+
+TEST_CASE("mock: per-query timeout overrides the connect-string default")
+{
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    const std::string conf =
+        "ws::addr=" + srv.addr() + ";query_timeout_ms=1000;";
+    eg::reader reader{questdb::ingress::utf8_view{conf}};
+    // Clearing it per query must also work, or a caller stuck with a
+    // profile-wide default could never opt a single query out.
+    auto cur = reader.prepare("X"_utf8).timeout_ms(0).execute();
+    while (cur.next_batch())
+    {
+    }
+
+    auto reqs = srv.captured_requests();
+    REQUIRE(reqs.size() == 1);
+    CHECK(reqs[0].size() == trailer_offset(1));
+}
+
+TEST_CASE("mock: failover replay re-sends the original timeout budget")
+{
+    // The replay patches only the request_id, so the new endpoint gets the
+    // full timeout again. Pinned so a change to that is deliberate.
+    qm::Script s_a = {
+        qm::ActionSendServerInfo{
+            qm::ROLE_STANDALONE,
+            "c",
+            "a",
+            0,
+            qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT},
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionHardDrop{},
+    };
+    qm::Script s_b = {
+        qm::ActionSendServerInfo{
+            qm::ROLE_STANDALONE,
+            "c",
+            "b",
+            0,
+            qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT},
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv_a({s_a});
+    qm::MockServer srv_b({s_b});
+
+    const std::string conf =
+        "ws::addr=" + srv_a.addr() + "," + srv_b.addr() +
+        ";failover_backoff_initial_ms=1;failover_backoff_max_ms=10";
+    eg::reader reader{questdb::ingress::utf8_view{conf}};
+
+    auto cur = reader.prepare("X"_utf8).timeout_ms(1000).execute();
+    while (cur.next_batch())
+    {
+    }
+
+    // Each endpoint saw one request, and both carried the same budget.
+    auto reqs_a = srv_a.captured_requests();
+    auto reqs_b = srv_b.captured_requests();
+    REQUIRE(reqs_a.size() == 1);
+    REQUIRE(reqs_b.size() == 1);
+    const size_t p = trailer_offset(1);
+    for (const auto* reqs : {&reqs_a, &reqs_b})
+    {
+        const auto& req = (*reqs)[0];
+        REQUIRE(req.size() == p + 3);
+        CHECK(req[p] == qm::QUERY_FLAG_TIMEOUT);
+        CHECK(req[p + 1] == 0xE8); // varint(1000), unchanged by the replay
+        CHECK(req[p + 2] == 0x07);
+    }
+    // The replay differs from the original only in the request_id, which is
+    // what makes the trailer survive byte-identically.
+    const auto& orig = reqs_a[0];
+    const auto& replay = reqs_b[0];
+    CHECK(orig.size() == replay.size());
+    CHECK(std::equal(orig.begin() + 9, orig.end(), replay.begin() + 9));
+}
+
+TEST_CASE("mock: timeout without CAP_QUERY_TIMEOUT fails before the wire")
+{
+    // Fail fast rather than degrade: running under the server default
+    // while the caller believes a 10-minute budget applied is how a dbt
+    // transform dies at 60 s with a confusing error.
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+
+    bool threw = false;
+    try
+    {
+        auto cur = reader.prepare("X"_utf8).timeout_ms(1000).execute();
+        while (cur.next_batch())
+        {
+        }
+    }
+    catch (const questdb::error& e)
+    {
+        threw = true;
+        CHECK(e.code() == questdb_error_unsupported_server);
+        // The message has to name the missing capability and point at the
+        // server-side knob, or the operator cannot act on it.
+        const std::string msg = e.what();
+        CHECK(msg.find("CAP_QUERY_TIMEOUT") != std::string::npos);
+        CHECK(msg.find("query.timeout") != std::string::npos);
+    }
+    CHECK(threw);
+    // Nothing reached the wire: the guard runs before the QUERY_REQUEST is
+    // encoded, so the server never sees a frame it would reject.
+    CHECK(srv.captured_requests().empty());
+}
+
+TEST_CASE("mock: timeout without any capabilities fails before the wire")
+{
+    qm::Script s = {
+        qm::ActionSendServerInfo{}, // capabilities = 0
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+
+    bool threw = false;
+    try
+    {
+        auto cur = reader.prepare("X"_utf8).timeout_ms(1000).execute();
+        while (cur.next_batch())
+        {
+        }
+    }
+    catch (const questdb::error& e)
+    {
+        threw = true;
+        CHECK(e.code() == questdb_error_unsupported_server);
+    }
+    CHECK(threw);
+    CHECK(srv.captured_requests().empty());
+}
+
+TEST_CASE("mock: a timed-out query leaves the connection usable")
+{
+    // The contract that makes pooling work: QUERY_TIMEOUT is per-query, so
+    // the next query runs on the same connection with no second handshake.
+    qm::Script s = {
+        server_info_with(qm::CAP_QUERY_FLAGS | qm::CAP_QUERY_TIMEOUT),
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendBuilt{[](int64_t rid) {
+            return qm::query_error_frame(
+                rid, qm::STATUS_QUERY_TIMEOUT, "timeout, query aborted");
+        }},
+        qm::ActionAwaitQueryRequest{},
+        qm::ActionSendResultEnd{},
+    };
+    qm::MockServer srv({s});
+    auto reader = connect_to(srv);
+
+    bool threw = false;
+    try
+    {
+        auto cur = reader.prepare("slow"_utf8).timeout_ms(1).execute();
+        while (cur.next_batch())
+        {
+        }
+    }
+    catch (const questdb::error& e)
+    {
+        threw = true;
+        CHECK(e.code() == questdb_error_query_timeout);
+    }
+    REQUIRE(threw);
+
+    // Second query on the same reader: it must go through.
+    auto cur2 = reader.execute("after"_utf8);
+    while (cur2.next_batch())
+    {
+    }
+
+    auto reqs = srv.captured_requests();
+    REQUIRE(reqs.size() == 2);
+    // Both requests arrived on the one scripted connection, which the mock
+    // serves per slot — so no reconnect happened between them.
+    CHECK(reqs[0][0] == qm::MSG_QUERY_REQUEST);
+    CHECK(reqs[1][0] == qm::MSG_QUERY_REQUEST);
+}
+
 TEST_CASE("mock: cursor::cancel writes MSG_CANCEL and surfaces Cancelled")
 {
     // After the QueryRequest, server holds the response open; the test