如何将DuckDB线程数从默认16固定设置为1？

问题现象 #

执行SET threads TO 1;或PRAGMA threads=1;后，查询duckdb_settings()显示threads值为1，但执行查询后通过htop观察到进程线程数又回到16，复现代码如下：

>>> import duckdb # line 1
>>> duckdb.execute("SET threads TO 1;") # line 2
<duckdb.duckdb.DuckDBPyConnection object at 0x7fb537744630>
>>> duckdb.execute("SELECT 1;").df() # line 3
   1
0  1
>>> q = "SELECT * FROM duckdb_settings() WHERE name = 'threads';"
>>> duckdb.sql(q).df()
      name value                                      description input_type   scope
0  threads     1  The number of total threads used by the system.     BIGINT  GLOBAL

原因分析 #

直接使用duckdb.execute()这类全局API时，底层可能会复用或创建新的连接实例，导致你设置的全局threads配置没有被后续操作的连接继承。另外，DuckDB的线程池默认有动态调整逻辑，全局设置的方式无法保证所有连接都严格遵循指定的线程数。

解决方案 #

方案1：创建显式连接并设置线程数

通过创建独立的连接实例，在该连接上设置线程数，后续所有查询都使用这个连接执行，确保配置持续生效：

import duckdb
# 创建连接
con = duckdb.connect()
# 在连接上设置线程数
con.execute("SET threads TO 1;")
# 使用该连接执行查询
con.execute("SELECT 1;").df()
# 验证线程数设置
q = "SELECT * FROM duckdb_settings() WHERE name = 'threads';"
print(con.sql(q).df())

方案2：创建连接时直接指定线程数（更推荐）

在创建连接时通过config参数直接指定线程数，从初始化阶段就固定线程池大小，避免后续配置丢失：

import duckdb
# 创建连接时指定线程数
con = duckdb.connect(config={"threads": "1"})
# 执行查询
con.execute("SELECT 1;").df()
# 验证设置
q = "SELECT * FROM duckdb_settings() WHERE name = 'threads';"
print(con.sql(q).df())

使用显式连接可以确保线程数设置始终生效，因为所有操作都绑定在同一个连接实例上，不会出现全局API导致的配置不统一问题。

内容的提问来源于stack exchange，提问作者Tapabrata Mukherjee