配置

Goose 提供了许多配置选项，可用于改变系统行为。

这些配置选项可以通过 SET 语句 或 PRAGMA 语句 进行设置。 你可以使用 RESET 语句 将其重置回初始值。

可以通过 current_setting() 标量函数 或 goose_settings() 表函数 查询配置项的当前值。例如：

SELECT current_setting('memory_limit') AS memlimit;

或者：

SELECT value AS memlimit
FROM goose_settings()
WHERE name = 'memory_limit';

示例

将系统的内存上限设置为 10 GB。

SET memory_limit = '10GB';

将系统配置为使用 1 个线程。

SET threads TO 1;

开启日志并将日志级别设为 debug。 关于日志级别的更多细节，请参阅 日志级别。

SET enable_logging = true;
SET logging_level = 'debug';

写入一条 debug 级别、connection 作用域的单条日志消息：

SELECT write_log('A new client has connected.', level := 'debug', scope := 'connection');

写入一条 debug 级别、connection 作用域，且带自定义 log_type 的单条日志消息：

SELECT write_log(
        'A new duck has connected to the lake.', 
        level := 'debug', 
        scope := 'connection', 
        log_type := 'goose.docs.example.quack'
    );

查看 DEBUG 日志级别的日志：

SELECT * FROM goose_logs WHERE log_level = 'DEBUG';

查看 QueryLog 类型的日志：

SELECT * FROM goose_logs WHERE type = 'QueryLog';

查看当前日志相关设置：

SELECT * FROM goose_settings() WHERE name LIKE '%logging%';

在长时间运行的查询期间启用进度条输出：

SET enable_progress_bar = true;

将默认的 NULL 排序设为 NULLS LAST：

SET default_null_order = 'nulls_last';

返回某个特定配置项的当前值：

SELECT current_setting('threads') AS threads;

threads
10

查询某个特定配置项：

SELECT *
FROM goose_settings()
WHERE name = 'threads';

name	value	说明	input_type	scope
threads	1	系统使用的总线程数。	BIGINT	GLOBAL

显示所有可用配置项列表：

SELECT *
FROM goose_settings();

将系统内存上限重置回默认值：

RESET memory_limit;

密钥管理器

Goose 提供了一个密钥管理器，为所有会使用密钥的后端（例如 AWS S3）提供统一的密钥使用界面。

配置参考

配置选项具有不同的默认作用域（scope）：GLOBAL 与 LOCAL。下面按作用域列出所有可用配置选项。

全局配置选项

名称	说明	类型	默认值
Calendar	当前日历	VARCHAR	系统（区域设置）日历
TimeZone	当前时区	VARCHAR	系统（区域设置）时区
access_mode	数据库访问模式（AUTOMATIC、READ_ONLY 或 READ_WRITE）	VARCHAR	automatic
allocator_background_threads	是否启用分配器后台线程	BOOLEAN	false
allocator_bulk_deallocation_flush_threshold	当批量释放内存超过该阈值时，刷新未完成的分配	VARCHAR	512.0 MiB
allocator_flush_threshold	完成任务后触发分配器刷新时的峰值分配阈值	VARCHAR	128.0 MiB
allow_asterisks_in_http_paths	允许用户可查询的 URL 路径中包含 * 字符	BOOLEAN	false
allow_community_extensions	允许加载社区构建的扩展	BOOLEAN	true
allow_extensions_metadata_mismatch	允许加载元数据不兼容的扩展	BOOLEAN	false
allow_parser_override_extension	允许扩展覆盖当前解析器	VARCHAR	DEFAULT
allow_persistent_secrets	允许创建持久化密钥，并在重启时进行存储与加载	BOOLEAN	true
allow_unredacted_secrets	允许打印未脱敏的密钥	BOOLEAN	false
allow_unsigned_extensions	允许加载签名无效或缺失签名的扩展	BOOLEAN	false
allowed_directories	始终允许被查询的目录/前缀列表——即使 enable_external_access 为 false 也生效	VARCHAR[]	[]
allowed_paths	始终允许被查询的文件列表——即使 enable_external_access 为 false 也生效	VARCHAR[]	[]
arrow_large_buffer_size	导出 Arrow 时，字符串/二进制/UUID/位串等是否使用 large buffer	BOOLEAN	false
arrow_lossless_conversion	当 Goose 类型在 Arrow 中没有明确的原生/规范映射时，使用 goose.type_name 扩展名以无损导出类型	BOOLEAN	false
arrow_output_list_view	导出 Arrow 格式时，LIST 列是否使用 ListView 作为物理布局	BOOLEAN	false
arrow_output_version	字符串是否使用 Utf8View（而不是 Utf8）格式输出	VARCHAR	1.0
asof_loop_join_threshold	ASOF 连接左侧需要的最大行数；低于该值时使用嵌套循环连接	UBIGINT	64
auto_checkpoint_skip_wal_threshold	估算的 WAL 写入量达到该阈值时，会跳过写 WAL 而只做 checkpoint；跳过写 WAL 意味着 checkpoint 期间并发提交会被阻塞	UBIGINT	100000
auto_fallback_to_full_download	在可能的情况下，允许自动回退为整文件下载	BOOLEAN	true
autoinstall_extension_repository	覆盖自动加载时扩展安装所使用的自定义端点	VARCHAR
autoinstall_known_extensions	当查询依赖已知扩展时，是否允许自动安装这些扩展	BOOLEAN	true
autoload_known_extensions	当查询依赖已知扩展时，是否允许自动加载这些扩展	BOOLEAN	true
binary_as_string	在 Parquet 文件中，将二进制数据解释为字符串	BOOLEAN	false
block_allocator_memory	块分配器允许使用的物理内存（该内存不会被释放，且无法下调）	VARCHAR	0 bytes
ca_cert_file	自签名证书所使用的自定义证书文件路径	VARCHAR
catalog_error_max_schemas	在 catalog 中生成 “did you mean...” 类错误提示时，系统最多扫描的 schema 数量	UBIGINT	100
checkpoint_threshold, wal_autocheckpoint	自动触发 checkpoint 的 WAL 大小阈值（例如 1GB）	VARCHAR	16.0 MiB
custom_extension_repository	覆盖远程扩展安装所使用的自定义端点	VARCHAR
custom_user_agent	Goose 调用方提供的元数据（User-Agent 等）	VARCHAR
default_block_size	新建 Goose 数据库文件的默认块大小（“新建”指文件尚不存在）	UBIGINT	262144
default_collation	未指定时使用的默认 collation（排序规则）	VARCHAR
default_null_order, null_order	未指定时使用的 NULL 排序（NULLS_FIRST 或 NULLS_LAST）	VARCHAR	NULLS_LAST
default_order	未指定时使用的默认排序方向（ASC 或 DESC）	VARCHAR	ASCENDING
default_secret_storage	允许切换密钥的默认存储方式	VARCHAR	local_file
deprecated_using_key_syntax	配置是否使用已弃用的 USING KEY CTE union 语法	VARCHAR	DEFAULT
disable_database_invalidation	遇到致命错误时禁用数据库实例失效处理。需谨慎使用，因为致命错误后 Goose 无法保证行为正确	BOOLEAN	false
disable_parquet_prefetching	禁用 Parquet 的预取机制	BOOLEAN	false
disable_timestamptz_casts	禁用从 timestamp 到 timestamptz 的类型转换	BOOLEAN	false
disabled_compression_methods	禁用一组压缩方法（逗号分隔）	VARCHAR
disabled_filesystems	禁用指定文件系统以阻止访问（例如 LocalFileSystem）	VARCHAR
disabled_log_types	设置被禁用的 logger 列表	VARCHAR
goose_api	Goose 的 API 使用面（接口范围）	VARCHAR	cli
dynamic_or_filter_threshold	从 hash join 动态生成 OR 过滤条件的最大数量	UBIGINT	50
enable_curl_server_cert_verification	为 CURL 后端启用服务端证书校验	BOOLEAN	true
enable_external_access	允许数据库访问外部状态（例如加载/安装模块、COPY TO/FROM、CSV 读取器、pandas 替换扫描等）	BOOLEAN	true
enable_external_file_cache	允许将外部文件（例如 Parquet）缓存到内存中	BOOLEAN	true
enable_fsst_vectors	允许在 FSST 压缩段扫描时输出压缩向量，以利用延迟解压	BOOLEAN	false
enable_geoparquet_conversion	若已加载 spatial 扩展，则在 GeoParquet 文件中尝试解码/编码几何（geometry）数据	BOOLEAN	true
enable_global_s3_configuration	自动从环境变量获取 AWS 凭据	BOOLEAN	true
enable_http_metadata_cache	是否使用全局 HTTP 元数据来缓存 HTTP 元数据	BOOLEAN	false
enable_logging	启用日志记录器	BOOLEAN	1
enable_macro_dependencies	允许创建的 MACRO 对其引用对象（例如表）建立依赖关系	BOOLEAN	false
enable_object_cache	[占位符] 旧设置——无实际效果	BOOLEAN	false
enable_server_cert_verification	启用服务端证书校验	BOOLEAN	false
enable_view_dependencies	允许创建的 VIEW 对其引用对象（例如表）建立依赖关系	BOOLEAN	false
enabled_log_types	设置启用的 logger 列表	VARCHAR
errors_as_json	将错误信息以结构化 JSON 输出，而不是原始字符串	BOOLEAN	false
experimental_metadata_reuse	实验性：在 checkpoint 时复用 row group 与表元数据	BOOLEAN	true
explain_output	EXPLAIN 语句的输出（ALL、OPTIMIZED_ONLY、PHYSICAL_ONLY）	VARCHAR	PHYSICAL_ONLY
extension_directories	设置用于存放扩展的目录列表	VARCHAR[]	[]
extension_directory	设置用于存放扩展的目录	VARCHAR
external_threads	用于 Goose 任务的外部线程数量	UBIGINT	1
file_search_path	用于搜索输入文件的目录列表（逗号分隔）	VARCHAR
force_download	强制在前置阶段下载文件	BOOLEAN	false
force_mbedtls_unsafe	启用 mbedtls 加密（警告：使用不安全）	BOOLEAN	false
force_variant_shredding	强制 checkpoint 时发生的 VARIANT shredding 使用提供的 schema	VARCHAR	INVALID
geometry_minimum_shredding_size	启用 GEOMETRY shredding 的最小 rowgroup 大小；设为 -1 可完全禁用。默认值为 rowgroup 的 1/4	BIGINT	30000
home_directory	设置系统使用的 home 目录	VARCHAR
http_keep_alive	保持连接存活（keep alive）。将其设为 false 在遇到连接失败时可能有帮助	BOOLEAN	true
http_proxy_password	HTTP 代理密码	VARCHAR
http_proxy_username	HTTP 代理用户名	VARCHAR
http_proxy	HTTP 代理主机	VARCHAR
http_retries	发生 I/O 错误时的 HTTP 重试次数	UBIGINT	3
http_retry_backoff	用于指数递增重试等待时间的回退系数（backoff factor）	FLOAT	4
http_retry_wait_ms	两次重试之间的等待时间	UBIGINT	100
http_timeout	HTTP 超时时间（读/写/连接/重试），单位：秒	UBIGINT	30
httpfs_client_implementation	选择要使用的 HTTPUtil 实现	VARCHAR	default
ieee_floating_point_ops	使用 IEE754 兼容的浮点运算（返回 NAN 而不是 errors/NULL）	BOOLEAN	true
ignore_unknown_crs	在创建几何类型或导入地理空间数据时忽略未知的坐标参考系（CRS）	BOOLEAN	false
immediate_transaction_mode	事务是按需延迟启动，还是在调用 BEGIN TRANSACTION 时立即启动	BOOLEAN	false
index_scan_max_count	索引扫描（index scan）的最大计数阈值：若匹配行数小于 MAX(index_scan_max_count, index_scan_percentage * total_row_count)，则使用索引扫描而不是全表扫描（table scan）	UBIGINT	2048
index_scan_percentage	索引扫描（index scan）百分比阈值：若匹配行数小于 MAX(index_scan_max_count, index_scan_percentage * total_row_count)，则使用索引扫描而不是全表扫描（table scan）	DOUBLE	0.001
integer_division	/ 运算符默认执行整数除法还是浮点除法	BOOLEAN	false
lambda_syntax	配置是否使用已弃用的单箭头运算符（->）作为 lambda 函数语法	VARCHAR	DEFAULT
late_materialization_max_rows	在 LIMIT/SAMPLE 中触发 late materialization 的最大行数	UBIGINT	50
lock_configuration	是否允许修改配置	BOOLEAN	false
log_query_path	指定查询日志写入路径（默认：NULL，不记录查询日志）	VARCHAR
logging_level	记录到日志中的日志级别	VARCHAR	WARNING
logging_mode	决定记录哪些类型的日志消息	VARCHAR	LEVEL_ONLY
logging_storage	设置日志存储（memory/stdout/file/<custom>）	VARCHAR	shell_log_storage
max_expression_depth	解析器允许的最大表达式深度。警告：增大该值并使用很深的表达式可能导致栈溢出	UBIGINT	1000
max_memory, memory_limit	系统可用的最大内存（例如 1GB）	VARCHAR	80% of RAM
max_temp_directory_size	（设置后）temp_directory 中允许存放的最大数据量（例如 1GB）	VARCHAR	90% of available disk space
max_vacuum_tasks	在一次 checkpoint 期间可调度的最大 vacuum 任务数	UBIGINT	100
merge_http_secret_into_s3_request	将 HTTP 密钥参数合并到 S3 请求中	BOOLEAN	true
merge_join_threshold	选择 merge join 时，任一表允许的最大行数	UBIGINT	1000
nested_loop_join_threshold	选择嵌套循环 join 时，任一表允许的最大行数	UBIGINT	5
old_implicit_casting	允许与 VARCHAR 之间进行隐式类型转换	BOOLEAN	false
order_by_non_integer_literal	允许按非整数常量排序——按此类常量排序不会产生效果	BOOLEAN	false
ordered_aggregate_threshold	在排序前累积的行数，用于调优	UBIGINT	262144
parquet_metadata_cache	缓存 Parquet 元数据——在多次读取同一文件时很有用	BOOLEAN	false
partitioned_write_flush_threshold	使用 PARTITION_BY 写入时，达到该行数阈值后刷新线程状态	UBIGINT	524288
partitioned_write_max_open_files	使用 PARTITION_BY 写入时，系统在刷新到磁盘前允许保持打开的最大文件数	UBIGINT	100
password	使用的密码。为兼容旧行为会忽略	VARCHAR
perfect_ht_threshold	使用完美哈希表（perfect hash table）的字节阈值	UBIGINT	12
pin_threads	是否将线程绑定到 CPU 核（仅 Linux；默认 AUTO：当核心数超过 64 时启用）	VARCHAR	auto
pivot_filter_threshold	从 filtered aggregates 切换到带专用 pivot 算子的 LIST 的阈值	UBIGINT	20
pivot_limit	pivot 语句中 pivot 列的最大数量	UBIGINT	100000
prefer_range_joins	在混合谓词的情况下强制使用 range join	BOOLEAN	false
prefetch_all_parquet_files	对所有类型的 Parquet 文件使用预取机制	BOOLEAN	false
preserve_identifier_case	是否保留标识符大小写（而不是始终将所有未加引号的标识符转为小写）	BOOLEAN	true
preserve_insertion_order	是否保留插入顺序。若设为 false，系统可以对不含 ORDER BY 子句的任何结果进行重排	BOOLEAN	true
produce_arrow_string_view	Arrow 字符串是否使用 Utf8View（而不是 Utf8）格式输出	BOOLEAN	false
s3_access_key_id	S3 访问密钥 ID（Access Key ID）	VARCHAR	NULL
s3_allow_recursive_globbing	S3 类存储上的 glob 是否使用递归策略进行优化（替代方案为 listing）	BOOLEAN	true
s3_endpoint	S3 端点（Endpoint）	VARCHAR	NULL
s3_kms_key_id	S3 KMS 密钥 ID（Key ID）	VARCHAR	NULL
s3_region	S3 区域（Region）	VARCHAR	NULL
s3_requester_pays	S3 使用“请求方付费（requester pays）”模式	BOOLEAN	false
s3_secret_access_key	S3 访问密钥（Secret Access Key）	VARCHAR	NULL
s3_session_token	S3 会话令牌（Session Token）	VARCHAR	NULL
s3_uploader_max_filesize	S3 上传器最大文件大小（50GB 到 5TB 之间）	VARCHAR	800GB
s3_uploader_max_parts_per_file	S3 上传器每个文件的最大分片数（1 到 10000 之间）	UBIGINT	10000
s3_uploader_thread_limit	S3 上传器全局线程上限	UBIGINT	50
s3_url_compatibility_mode	在 S3 URL 上禁用 glob 与查询参数	BOOLEAN	false
s3_url_style	S3 URL 风格	VARCHAR	vhost
s3_use_ssl	S3 使用 SSL	BOOLEAN	true
s3_version_id_pinning	为一致性将 S3 读取固定到某个特定对象版本	BOOLEAN	false
scalar_subquery_error_on_multiple_rows	当标量子查询返回多行时：返回随机一行，而不是返回错误	BOOLEAN	true
scheduler_process_partial	在重新调度前对任务进行部分处理——使不同查询之间的调度更加公平	BOOLEAN	false
secret_directory	设置用于存放持久化密钥的目录	VARCHAR	~/.goose/stored_secrets
storage_block_prefetch	在哪些场景下使用存储块预取（storage block prefetching）	VARCHAR	REMOTE_ONLY
storage_compatibility_version	在 checkpoint 时序列化，并与指定的 Goose 版本保持兼容	VARCHAR	v0.10.2
temp_directory	设置写入临时文件的目录	VARCHAR	⟨database_name⟩.tmp or .tmp (in in-memory mode)
temp_file_encryption	若数据库已加密，则加密所有临时文件	BOOLEAN	false
threads, worker_threads	系统使用的总线程数	BIGINT	# CPU cores
unsafe_disable_etag_checks	禁用 ETag 一致性检查	BOOLEAN	false
user, username	使用的用户名。为兼容旧行为会忽略	VARCHAR
validate_external_file_cache	缓存校验模式：VALIDATE_ALL（默认，校验所有缓存项）、VALIDATE_REMOTE（仅校验远程缓存项）、NO_VALIDATION（禁用缓存校验）	VARCHAR	VALIDATE_ALL
variant_minimum_shredding_size	启用 VARIANT shredding 的最小 rowgroup 大小；设为 -1 可完全禁用。默认值为 rowgroup 的 1/4	BIGINT	30000
wal_autocheckpoint_entries	当 WAL 条目数达到或超过 N 时触发自动 checkpoint（0 = 禁用）	UBIGINT	0
warnings_as_errors	将所有警告升级为错误	BOOLEAN	false
write_buffer_row_group_count	在批量导入时，刷新前要缓冲的 row group 数量。降低该值可减少内存占用	UBIGINT	5
zstd_min_string_length	启用 ZSTD 压缩的（平均）字符串长度阈值，默认 4096	UBIGINT	4096

本地配置选项

名称	说明	类型	默认值
custom_profiling_settings	接受一个 JSON 以启用自定义指标	VARCHAR	{"ATTACH_LOAD_STORAGE_LATENCY": "true", "ATTACH_REPLAY_WAL_LATENCY": "true", "BLOCKED_THREAD_TIME": "true", "CHECKPOINT_LATENCY": "true", "COMMIT_LOCAL_STORAGE_LATENCY": "true", "CPU_TIME": "true", "CUMULATIVE_CARDINALITY": "true", "CUMULATIVE_ROWS_SCANNED": "true", "EXTRA_INFO": "true", "LATENCY": "true", "OPERATOR_CARDINALITY": "true", "OPERATOR_NAME": "true", "OPERATOR_ROWS_SCANNED": "true", "OPERATOR_TIMING": "true", "OPERATOR_TYPE": "true", "QUERY_NAME": "true", "RESULT_SET_SIZE": "true", "ROWS_RETURNED": "true", "SYSTEM_PEAK_BUFFER_MEMORY": "true", "SYSTEM_PEAK_TEMP_DIR_SIZE": "true", "TOTAL_BYTES_READ": "true", "TOTAL_BYTES_WRITTEN": "true", "TOTAL_MEMORY_ALLOCATED": "true", "WAITING_TO_ATTACH_LATENCY": "true", "WAL_REPLAY_ENTRY_COUNT": "true", "WRITE_TO_WAL_LATENCY": "true"}
enable_http_logging	（已弃用）启用 HTTP 日志	BOOLEAN	true
enable_profiling	启用 profiling，并设置输出格式（JSON、QUERY_TREE、QUERY_TREE_OPTIMIZER）	VARCHAR	NULL
enable_progress_bar_print	当 enable_progress_bar 为 true 时，控制是否打印进度条	BOOLEAN	true
enable_progress_bar	启用进度条，在长查询时向终端输出进度	BOOLEAN	true
http_logging_output	（已弃用）HTTP 日志输出保存的文件；为空时打印到终端	VARCHAR
profile_output, profiling_output	profiling 输出保存的文件；为空时打印到终端	VARCHAR
profiling_coverage	profiling 覆盖范围（SELECT 或 ALL）	VARCHAR	SELECT
profiling_mode	profiling 模式（STANDARD 或 DETAILED）	VARCHAR	NULL
progress_bar_time	设置在开始打印进度条前，查询需运行的时长（毫秒）	BIGINT	2000
schema	设置默认搜索 schema，等价于将 search_path 设为单个值	VARCHAR	main
search_path	将默认 catalog 搜索路径设置为逗号分隔的值列表	VARCHAR
streaming_buffer_size	从流式结果拉取数据时可用于缓冲的最大内存（例如 1GB）	VARCHAR	976.5 KiB