Skip to content

Native TCP: CompressionMethod::ZSTD is not honored for server -> client blocks (network_compression_method never sent) #556

Description

@claude

Description

When a client is configured with ClientOptions().SetCompressionMethod(CompressionMethod::ZSTD), only the client → server direction actually uses ZSTD. The server → client direction still uses the server's default codec (LZ4).

The reason is that the native TCP query packet only carries a boolean "compression enabled" flag; the selected codec is never propagated to the server:

  • clickhouse/client.cpp:349-351 — compression_ is set to CompressionState::Enable for any method other than None; the specific method is discarded.
  • clickhouse/client.cpp:1087 — WireFormat::WriteUInt64(*output_, compression_); writes only that enable flag.
  • clickhouse/client.cpp:447 — CompressedOutput correctly uses options_.compression_method for the outgoing (client → server) data blocks.

To make the server compress its responses with ZSTD, the client must send the network_compression_method (and, for a configured level, network_zstd_compression_level) setting in the per-query settings section of the query packet (clickhouse/client.cpp:1067-1080). It never does.

The read path is not broken — CompressedInput::Decompress (clickhouse/base/compressed.cpp:105-131) accepts both LZ4 and ZSTD method bytes — so nothing fails; the selected codec is just silently not honored in one direction.

Additionally, there is no option to configure a ZSTD compression level at all: ClientOptions (clickhouse/client.h:107) only exposes compression_method.

This is the C++ equivalent of ClickHouse/clickhouse-go#1993.

ClickHouse server version

26.7.5.10 (verified against a running server over the native protocol on port 9000).

Reproduction

The server-side effective value of network_compression_method for the query is what determines how the server compresses the result blocks it sends back, so it can be observed directly from the client:

#include <clickhouse/client.h>
#include <iostream>

using namespace clickhouse;

int main() {
    Client client(ClientOptions()
                      .SetHost("localhost")
                      .SetPort(9000)
                      .SetCompressionMethod(CompressionMethod::ZSTD));

    client.Select(
        "SELECT name, value FROM system.settings WHERE name IN "
        "('network_compression_method', 'network_zstd_compression_level')",
        [](const Block& block) {
            for (size_t i = 0; i < block.GetRowCount(); ++i) {
                std::cout << (*block[0]->As<ColumnString>())[i] << " = "
                          << (*block[1]->As<ColumnString>())[i] << std::endl;
            }
        });
    return 0;
}

Expected output (codec honored in both directions):

network_compression_method = ZSTD
network_zstd_compression_level = <configured level>

Actual output:

network_compression_method = LZ4
network_zstd_compression_level = 1

i.e. the server compresses everything it sends back to this client with LZ4, even though ZSTD was requested.

Suggested fix

In Client::Impl::SendQuery (clickhouse/client.cpp, per-query settings block around lines 1067-1080), when options_.compression_method != CompressionMethod::None and the setting is not already present in query.GetQuerySettings(), send:

  • network_compression_method = "ZSTD" / "LZ4" matching options_.compression_method
  • network_zstd_compression_level = the configured level, if a new ClientOptions field for it is added (e.g. SetCompressionLevel), when the method is ZSTD

Link

Original report against the Go client: ClickHouse/clickhouse-go#1993

Activity

  1. polyglotAI-bot commented on Nov 18, 2026

    @polyglotAI-bot
    Collaborator

    Recommendation: Keep open — maintainer decision, then review PR #568
    PR #568 sends the selected codec, but with it every query of a user with readonly = 1 fails when that codec is not the server default (output below). Decide if the client sends network_compression_method always or only when the caller opts in. Then review PR #568: its test file needs a rebase on master.

    Analysis: The query packet carries only the compression flag (clickhouse/client.cpp:1104). compression_method selects only the codec of the blocks that the client sends (clickhouse/client.cpp:347, :446). The per-query settings (clickhouse/client.cpp:1084-1096) never contain network_compression_method, so the server compresses its blocks with its own default. ClickHouse 26.9 changed that default from LZ4 (level 1) to ZSTD (level 3) (system.settings_changes): servers up to 26.8 (26.3 and 26.8 LTS in the CI matrix) ignore a ZSTD choice, and 26.9 and later ignore an LZ4 choice. The client decodes both codecs, so no error shows; a per-query network_compression_method setting is a workaround for users that can change settings. ClientOptions has no field for the ZSTD level (clickhouse/client.h:107).

    Reproduction: complete program and output
    #include <clickhouse/client.h>
    
    #include <cstdlib>
    #include <exception>
    #include <iostream>
    #include <string>
    
    using namespace clickhouse;
    
    static const char* Name(CompressionMethod m) {
        switch (m) {
            case CompressionMethod::None: return "None";
            case CompressionMethod::LZ4: return "LZ4";
            case CompressionMethod::ZSTD: return "ZSTD";
        }
        return "?";
    }
    
    static ClientOptions Options(CompressionMethod method, const std::string& user) {
        const char* host = std::getenv("CLICKHOUSE_HOST");
        const char* port = std::getenv("CLICKHOUSE_PORT");
        return ClientOptions()
            .SetHost(host ? host : "localhost")
            .SetPort(port ? std::stoi(port) : 9000)
            .SetUser(user)
            .SetCompressionMethod(method);
    }
    
    // Prints the values that the server uses for this query. The server compresses
    // the blocks that it sends to the client with network_compression_method.
    static void RunCase(const std::string& user, CompressionMethod method, bool per_query_setting) {
        std::cout << "user=" << user << " client method=" << Name(method)
                  << (per_query_setting ? " + query setting network_compression_method=ZSTD" : "")
                  << ": ";
        try {
            Client client(Options(method, user));
            Query query("SELECT name, value FROM system.settings "
                        "WHERE name IN ('network_compression_method', 'network_zstd_compression_level') "
                        "ORDER BY name");
            if (per_query_setting) {
                query.SetSetting("network_compression_method", QuerySettingsField{"ZSTD", 0});
            }
            query.OnData([](const Block& block) {
                for (size_t i = 0; i < block.GetRowCount(); ++i) {
                    std::cout << (*block[0]->As<ColumnString>())[i] << "="
                              << (*block[1]->As<ColumnString>())[i] << " ";
                }
            });
            client.Select(query);
            std::cout << std::endl;
        } catch (const std::exception& e) {
            std::cout << "exception: " << e.what() << std::endl;
        }
    }
    
    int main() {
        Client admin(Options(CompressionMethod::None, "default"));
        admin.Execute("DROP USER IF EXISTS triage_ro_556");
        admin.Execute("CREATE USER triage_ro_556 IDENTIFIED WITH no_password SETTINGS readonly = 1");
        admin.Execute("GRANT SELECT ON system.settings TO triage_ro_556");
    
        RunCase("default", CompressionMethod::None, false);
        RunCase("default", CompressionMethod::LZ4, false);
        RunCase("default", CompressionMethod::ZSTD, false);
        RunCase("default", CompressionMethod::ZSTD, true);
        // A user with readonly = 1 cannot change settings.
        RunCase("triage_ro_556", CompressionMethod::LZ4, false);
        RunCase("triage_ro_556", CompressionMethod::ZSTD, false);
    
        admin.Execute("DROP USER triage_ro_556");
        return 0;
    }

    Built with the default options (2.x API), Release, -DWITH_OPENSSL=ON. With CompressionMethod::None the server does not compress, so the value in the first line has no effect.

    Output on master (58453c2), ClickHouse 26.10.4.207:

    user=default client method=None: network_compression_method=ZSTD network_zstd_compression_level=3 
    user=default client method=LZ4: network_compression_method=ZSTD network_zstd_compression_level=3 
    user=default client method=ZSTD: network_compression_method=ZSTD network_zstd_compression_level=3 
    user=default client method=ZSTD + query setting network_compression_method=ZSTD: network_compression_method=ZSTD network_zstd_compression_level=3 
    user=triage_ro_556 client method=LZ4: network_compression_method=ZSTD network_zstd_compression_level=3 
    user=triage_ro_556 client method=ZSTD: network_compression_method=ZSTD network_zstd_compression_level=3 
    

    Output on master (58453c2), ClickHouse 26.7.38.18:

    user=default client method=None: network_compression_method=LZ4 network_zstd_compression_level=1 
    user=default client method=LZ4: network_compression_method=LZ4 network_zstd_compression_level=1 
    user=default client method=ZSTD: network_compression_method=LZ4 network_zstd_compression_level=1 
    user=default client method=ZSTD + query setting network_compression_method=ZSTD: network_compression_method=ZSTD network_zstd_compression_level=1 
    user=triage_ro_556 client method=LZ4: network_compression_method=LZ4 network_zstd_compression_level=1 
    user=triage_ro_556 client method=ZSTD: network_compression_method=LZ4 network_zstd_compression_level=1 
    

    Output with the library changes of PR #568 (clickhouse/client.cpp, clickhouse/client.h) applied on master, ClickHouse 26.10.4.207:

    user=default client method=None: network_compression_method=ZSTD network_zstd_compression_level=3 
    user=default client method=LZ4: network_compression_method=LZ4 network_zstd_compression_level=3 
    user=default client method=ZSTD: network_compression_method=ZSTD network_zstd_compression_level=3 
    user=default client method=ZSTD + query setting network_compression_method=ZSTD: network_compression_method=ZSTD network_zstd_compression_level=3 
    user=triage_ro_556 client method=LZ4: exception: DB::Exception: Cannot modify 'network_compression_method' setting in readonly mode
    user=triage_ro_556 client method=ZSTD: network_compression_method=ZSTD network_zstd_compression_level=3 
    

    The same, ClickHouse 26.7.38.18:

    user=default client method=None: network_compression_method=LZ4 network_zstd_compression_level=1 
    user=default client method=LZ4: network_compression_method=LZ4 network_zstd_compression_level=1 
    user=default client method=ZSTD: network_compression_method=ZSTD network_zstd_compression_level=1 
    user=default client method=ZSTD + query setting network_compression_method=ZSTD: network_compression_method=ZSTD network_zstd_compression_level=1 
    user=triage_ro_556 client method=LZ4: network_compression_method=LZ4 network_zstd_compression_level=1 
    user=triage_ro_556 client method=ZSTD: exception: DB::Exception: Cannot modify 'network_compression_method' setting in readonly mode
    

    Automated triage by Polyglot AI. Classification added on 2026-11-19. A maintainer makes the final decision.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions