第9章 QuestDB 服务器配置详解
本页介绍了配置 QuestDB 服务器参数的方法。
可以通过以下方式进行配置:
- 位于根目录的
server.conf配置文件 - 环境变量
- 命令行选项,用于指定根目录、服务标签及 Web 控制台重新部署等启动行为
如果配置文件中未包含某项设置,且环境变量中也未定义,则使用默认值。
note:针对 Windows 用户。输入路径值时,请使用
\\或/代替原生路径分隔符\。👍 C:\\path\\to\\file\\path
👍 C:/path/to/file
👎 C:\path\to\file
单个反斜杠会被 Java 属性解析器视为转义序列的起始。
环境变量
配置文件中所有设置都可以通过环境变量进行设定或覆盖。如果某个键同时在 server.conf 文件和环境中变量中定义,环境变量将优先,配置文件中的值将被忽略。
为了使这些配置在 QuestDB 中通过环境变量生效,它们必须符合以下格式:
QDB_<KEY_OF_THE_PROPERTY>
其中 <KEY_OF_THE_PROPERTY> 等于配置键名称。为了将 server.conf 中的键正确格式化为环境变量,必须满足以下条件:
- 添加
QDB_前缀 - 使用大写字母
- 将所有点号
.替换为下划线_
例如,查询超时的服务器配置键必须按如下方式传递:
server.conf 键:query.timeout 环境变量:QDB_QUERY_TIMEOUT
note:QuestDB 在启动时应用这些配置更改,必须重启正在运行的实例才能使配置更改生效。
示例
以下配置属性用于自定义查询超时时间:
conf/server.conf
query.timeout=120s
通过环境变量自定义查询超时:
export QDB_QUERY_TIMEOUT=120s
从文件读取密钥
QuestDB 支持通过 _FILE 后缀约定从文件读取敏感配置值。这在 Kubernetes 等容器化环境中非常有用,因为机密数据通常以文件形式挂载,而非作为环境变量传递。
当设置了 _FILE 变体时,QuestDB 将从指定文件路径读取机密值。此机制同时适用于环境变量和 server.conf 中的属性。
用法
环境变量:
QDB_PG_PASSWORD_FILE=/run/secrets/pg-password
属性文件:
server.conf
pg.password.file=/run/secrets/pg-password
配置项环境变量pg.passwordQDB_PG_PASSWORD_FILEpg.readonly.passwordQDB_PG_READONLY_PASSWORD_FILEhttp.passwordQDB_HTTP_PASSWORD_FILE
企业版配置项以下额外配置项仅在 QuestDB Enterprise 中可用:
配置项环境变量acl.admin.passwordQDB_ACL_ADMIN_PASSWORD_FILEacl.oidc.tls.keystore.passwordQDB_ACL_OIDC_TLS_KEYSTORE_PASSWORD_FILEreplication.object.storeQDB_REPLICATION_OBJECT_STORE_FILEcold.storage.object.storeQDB_COLD_STORAGE_OBJECT_STORE_FILEbackup.object.store.*QDB_BACKUP_OBJECT_STORE_*_FILE
Kubernetes 相关示例请参见 Kubernetes 部署指南。 可重新加载的配置项 某些配置项无需重启服务器即可重新加载。方法是:在 server.conf 文件中修改配置值,然后执行 reload_config SQL 函数:重新加载服务器配置SELECT reload_config();
每个键都有一个可重载属性(reloadable property),用于标识该键是否支持重载。如果支持,即可调用 reload_config 函数重新加载配置。例如,查询、视图刷新和 WAL 应用等基于工作负载的内存限制均支持重载。 所有支持重载的属性也可通过服务器查询获取: Query reloadable properties(SHOW PARAMETERS) WHERE reloadable = true;
命令行选项 QuestDB 可通过命令行启动、停止并传入配置选项。在 Windows 系统上,QuestDB 服务器还支持启动交互式会话。 选项说明 以下章节介绍了通过命令行启动 QuestDB 服务器时可传入的选项。 LinuxmacOS(Homebrew)Windows./questdb.sh [start|stop|status] [-d dir] [-f] [-n] [-t tag]
questdb [start|stop|status] [-d dir] [-f] [-n] [-t tag]
questdb.exe [start|stop|status|install|remove] \
[-d dir] [-f] [-j JAVA_HOME] [-t tag]
启动 start 命令用于将 QuestDB 作为服务启动。 选项 说明 -d 接受一个目录路径作为参数,该目录将用作 QuestDB 的根目录。更多信息及默认值请参见下方的“默认根目录”章节。 -t 接受一个字符串作为服务标签。此选项允许用户运行并独立管理多个 QuestDB 服务。若省略此选项,默认标签为 questdb。 -f 强制重新部署 Web Console。若未指定此选项,Web Console 会被缓存,仅在缺失时才会部署。 -n 不响应 HUP 信号。此设置可使你在关闭启动 QuestDB 的终端窗口后,服务依然保持运行状态。 -j 仅限 Windows 使用!此选项允许指定 JAVA_HOME 的路径。 注意 当运行多个 QuestDB 服务时,必须在 start 和 stop 命令中使用标签来区分不同的服务。如果仅指定了标签标志而启动多个服务,会导致端口和根目录冲突。每个新服务都应拥有独立的配置文件,或者在启动时指定不同的端口和根目录选项。 将 QuestDB 作为 Windows 服务运行时,可通过以下两种方式查看状态: - Windows 事件查看器:在“应用程序和服务”日志中查找源为 "QuestDB" 的事件。 - 服务日志文件:位于 $dataDir\log\service-%Y-%m-%dT%H-%M-%S.txt (默认为 C:\Windows\System32\qdbroot\log\service-%Y-%m-%dT%H-%M-%S.txt )。 Linux macOS (Homebrew) Windows ./questdb.sh start [-d dir] [-f] [-n] [-t tag] questdb start [-d dir] [-f] [-n] [-t tag] questdb.exe start [-d dir] [-f] [-j JAVA_HOME] [-t tag] 默认根目录 QuestDB 的默认根目录如下: Linux macOS (Homebrew) Windows $HOME/.questdb Mac Apple Silicon (M1 或 M2) 芯片路径:/opt/homebrew/var/questdb Mac Intel 芯片路径:/usr/local/var/questdb C:\Windows\System32\qdbroot 停止 stop 命令用于停止服务。 选项 说明 -t 接受一个字符串作为标签,根据标签停止服务。若省略此选项,默认标签为 questdb。 Linux macOS (Homebrew) Windows ./questdb.sh stop questdb stop questdb.exe stop 状态 status 命令用于显示服务状态。 选项 说明 -t 接受一个字符串作为标签,根据标签停止服务。若省略此选项,默认为 questdb。 Linux macOS (Homebrew) Windows ./questdb.sh status questdb status questdb.exe status 安装(Windows) install —— 安装 Windows 版 QuestDB 服务,该服务会在系统启动时自动运行。 questdb.exe install 卸载(Windows) remove —— 移除 Windows 版 QuestDB 服务,之后系统启动时不再自动运行。 questdb.exe remove 交互式运行(Windows) 直接运行 questdb.exe 即可以交互方式启动 QuestDB,它会在当前 Shell 窗口中运行,关闭 Shell 时 QuestDB 也会随之停止。 默认根目录 以交互方式启动时,QuestDB 的根目录默认为当前目录。 停止 在终端中按 Ctrl+C 即可停止,或直接关闭终端。 配置校验 数据库启动时会检查配置问题,例如无效或已废弃的设置项。问题分为提示(advisory)和错误(error)两类。提示类问题只会记录日志,不会阻止数据库启动,通常是设置项已废弃的警告;而配置错误则可以选择性地让数据库启动失败。 config.validation.strict 默认值:false 可热更新:否 启用后,如果存在配置错误,启动将失败。建议启用严格校验。 配置参考 完整的配置参考按子系统划分,每个页面列出所有可用的配置项,包括默认值、是否支持运行时热更新,以及说明。 用于指定缓冲区和内存页大小的参数格式为 n