ClickHouse客户端连接失败主因是服务端未启用远程TCP监听，需配置config.xml中<listen_host>0.0.0.0</listen_host>并重启服务；client构造后必须显式调用connect()；批量插入应使用Block而非execute()；CMake链接需指定clickhouse-cpp-lib。
connect() 失败但没报错，其实是没开 TCP 协议
ClickHouse 默认只监听本地 localhost:9000 的 TCP 连接，而且服务端默认关闭了 HTTP 接口（9004）和原生协议（9000）的远程访问。用 clickhouse-cpp 调 Client::connect() 时卡住或静默失败，大概率是服务端没配好。
检查并改 /etc/clickhouse-server/config.xml：
- 确认
<listen_host>0.0.0.0</listen_host>已启用（不是注释掉的） - 确认
<tcp_port>9000</tcp_port>存在且未被注释 - 如果用 HTTP 模式（不推荐，
clickhouse-cpp主要走原生协议），还要开<http_port>8123</http_port>，但这个库不走 HTTP
改完记得 sudo systemctl restart clickhouse-server，再用 netstat -tuln | grep :9000 确认端口真在监听。
Client 构造后必须显式调 connect()，不能靠构造函数自动连
clickhouse-cpp 的 Client 类构造函数只是初始化对象，不建立连接；真正发请求前必须手动调 connect()，否则后续 execute() 或 select() 会直接崩溃或抛 std::runtime_error，错误信息类似 "Not connected"。
立即学习“C++免费学习笔记（深入）”；
正确写法示例：
Client client(ClientOptions().setHost("127.0.0.1").setPort(9000));
client.connect(); // 必须这一步
client.execute("CREATE DATABASE IF NOT EXISTS test");
- 连接失败时
connect()会抛异常，建议加try/catch - 如果复用
Client实例，注意它不自动重连；连接断开后再次调connect()是安全的（内部会先 close 当前 socket） - 别在多线程里共享一个
Client实例——它不是线程安全的；每个线程应持有一个独立实例
INSERT 性能差？别用 execute() 逐条插，改用 Block + appendRow()
用 client.execute("INSERT INTO t VALUES (1, 'a')") 插单行，在高并发或大批量场景下性能极差：每次都要走 SQL 解析、计划生成、事务开销。实测比批量插入慢 10–100 倍。
正确做法是用 Block 构建数据块，再调 client.insert()：
Block block;
block.appendColumn("x", Type::create<UInt64>());
block.appendColumn("s", Type::create<String>());
block.appendRow(1UL, "hello");
block.appendRow(2UL, "world");
client.insert("test.t", block);
-
appendColumn()的类型名必须和表定义严格一致（比如 ClickHouse 里的UInt64对应Type::create<uint64>()</uint64>，不是uint64_t） - 列顺序必须和表结构顺序一致，不能靠列名匹配
- 每块数据建议控制在 1k–10k 行之间；太小吞吐上不去，太大可能触发内存限制或超时
编译时报 undefined reference 到 libclickhouse-cpp-lib，链接漏了静态库
CMake 找不到符号，常见于只写了 find_package(clickhouse-cpp) 却没 link 对应的 target。官方 CMakeLists.txt 里导出的是 clickhouse-cpp-lib（带 -lib 后缀），不是 clickhouse-cpp。
正确 CMake 写法：
find_package(clickhouse-cpp REQUIRED) add_executable(myapp main.cpp) target_link_libraries(myapp clickhouse-cpp-lib) // 注意是 clickhouse-cpp-lib，不是 clickhouse-cpp
- 如果自己从源码编译安装，确保
make install后.so或.a文件真出现在CMAKE_INSTALL_PREFIX/lib下 - macOS 上还可能遇到
dyld: library not loaded，需加set(CMAKE_MACOSX_RPATH ON)并确认RPATH包含库路径 - 别把
clickhouse-cpp和clickhouse-cpp-clang（LLVM 工具链专用）混用，后者不提供运行时库
类型映射、连接池管理、空值处理这些细节，都藏在 Block 构造和 Column 类型选择里——稍不注意就 segfault 或数据错位，得对着头文件里的 Type.h 和表 schema 一行行核对。
