配置 GreptimeDB

GreptimeDB 提供了层次化的配置能力，按照下列优先顺序来生效配置（每个项目都会覆盖下面的项目）：

• Greptime 命令行选项
• 配置文件选项
• 环境变量
• 默认值

你只需要设置所需的配置项。 GreptimeDB 将为未配置的任何设置分配默认值。

如何设置配置项

Greptime 命令行选项

你可以使用命令行参数指定多个配置项。 例如，以配置的 HTTP 地址启动 GreptimeDB 的独立模式：

1. greptime standalone start --http-addr 127.0.0.1:4000

有关 Greptime 命令行支持的所有选项，请参阅 GreptimeDB 命令行界面。

配置文件选项

你可以在 TOML 文件中指定配置项。 例如，创建一个名为 standalone.example.toml 的配置文件，如下所示：

1. [storage]
2. type = "File"
3. data_home = "/tmp/greptimedb/"

然后使用命令行参数 -c [file_path] 指定配置文件。

1. greptime [standalone | frontend | datanode | metasrv]  start -c config/standalone.example.toml

例如以 standalone 模式启动 GreptimeDB：

1. greptime standalone start -c standalone.example.toml

示例文件

以下是每个 GreptimeDB 组件的示例配置文件，包括所有可用配置项。 在实际场景中，你只需要配置所需的选项，不需要像示例文件中那样配置所有选项。

• 独立模式
• 前端
• 数据节点
• 流节点
• 元服务

环境变量

配置文件中的每个项目都可以映射到环境变量。 例如，使用环境变量设置数据节点的 data_home 配置项：

1. # ...
2. [storage]
3. data_home = "/data/greptimedb"
4. # ...

使用以下 shell 命令以以下格式设置环境变量：

1. export GREPTIMEDB_DATANODE__STORAGE__DATA_HOME=/data/greptimedb

环境变量规则

• 每个环境变量应具有组件前缀，例如：

• GREPTIMEDB_FRONTEND

• GREPTIMEDB_METASRV
• GREPTIMEDB_DATANODE
• GREPTIMEDB_STANDALONE
• 使用**双下划线 __**作为分隔符。例如，数据结构 storage.data_home 转换为 STORAGE__DATA_HOME。

环境变量还接受以逗号 , 分隔的列表，例如：

1. GREPTIMEDB_METASRV__META_CLIENT__METASRV_ADDRS=127.0.0.1:3001,127.0.0.1:3002,127.0.0.1:3003

协议选项

协议选项适用于 frontend 和 standalone 子命令，它指定了协议服务器地址和其他协议相关的选项。

下面的示例配置包含了所有协议选项的默认值。 你可以在配置文件中更改这些值或禁用某些协议。 例如禁用 OpenTSDB 协议支持，可以将 enable 参数设置为 false。 请注意，为了保障数据库的正常工作，无法禁用 HTTP 和 gRPC 协议。

1. [http]
2. addr = "127.0.0.1:4000"
3. timeout = "30s"
4. body_limit = "64MB"

6. [grpc]
7. bind_addr = "127.0.0.1:4001"
8. runtime_size = 8

10. [mysql]
11. enable = true
12. addr = "127.0.0.1:4002"
13. runtime_size = 2

15. [mysql.tls]
16. mode = "disable"
17. cert_path = ""
18. key_path = ""

20. [postgres]
21. enable = true
22. addr = "127.0.0.1:4003"
23. runtime_size = 2

25. [postgres.tls]
26. mode = "disable"
27. cert_path = ""
28. key_path = ""

30. [opentsdb]
31. enable = true

33. [influxdb]
34. enable = true

36. [prom_store]
37. enable = true

下表描述了每个选项的详细信息：

对 MySQL 和 Postgres 接口，我们支持 TLS 配置

存储选项

存储选项在 datanode 和 standalone 模式下有效，它指定了数据库数据目录和其他存储相关的选项。

GreptimeDB 支持将数据保存在本地文件系统， AWS S3 以及其兼容服务（比如 MinIO、digitalocean space、腾讯 COS、百度对象存储（BOS）等），Azure Blob Storage 和阿里云 OSS。

文件存储配置范例：

1. [storage]
2. type = "File"
3. data_home = "/tmp/greptimedb/"

s3 配置范例：

1. [storage]
2. type = "S3"
3. bucket = "test_greptimedb"
4. root = "/greptimedb"
5. access_key_id = "<access key id>"
6. secret_access_key = "<secret access key>"

存储服务的 http 客户端

[storage.http_client] 设置了向存储服务发送请求的 http 客户端的各种配置。

仅当存储服务类型是 “S3”，“Oss”，“Azblob” 或 “Gcs” 时生效。

存储引擎提供商

[[storage.providers]] 用来设置存储引擎的提供商列表。基于这个配置，你可以为每张表指定不同的存储引擎，具体请参考 create table:

1. # Allows using multiple storages
2. [[storage.providers]]
3. name = "S3"
4. type = "S3"
5. bucket = "test_greptimedb"
6. root = "/greptimedb"
7. access_key_id = "<access key id>"
8. secret_access_key = "<secret access key>"

10. [[storage.providers]]
11. name = "Gcs"
12. type = "Gcs"
13. bucket = "test_greptimedb"
14. root = "/greptimedb"
15. credential_path = "<gcs credential path>"

所有配置的这些存储引擎提供商的 name 都可以在创建表时用作 storage 选项。

对于同样提供商的存储，比如你希望使用不同 S3 bucket 来作为不同表的存储引擎，你就可以设置不同的 name，并在创建表的时候指定 storage 选项。

对象存储缓存

在使用 AWS S3、阿里云 OSS 或 Azure Blob Storage 等远程存储服务时，查询过程中获取数据通常会很耗时，尤其在公有云环境。为了解决这个问题，GreptimeDB 提供了本地缓存机制来加速重复数据的访问。

从 v0.11 版本开始，GreptimeDB 默认启用远程对象存储的本地文件缓存。读取和写入缓存容量都设置为 5GiB。

通常你无需专门配置缓存，除非你需要修改缓存的大小

1. [storage]
2. type = "S3"
3. bucket = "test_greptimedb"
4. root = "/greptimedb"
5. access_key_id = "<access key id>"
6. secret_access_key = "<secret access key>"
7. cache_capacity = "10GiB"
8. # cache_path = "/path/to/cache/home"

cache_path 指定存储缓存文件的本地目录，而 cache_capacity 则决定缓存目录中允许的最大文件总大小（以字节为单位）。你可以通过将 cache_path 设置为空字符串来禁用读取缓存。默认的缓存目录位于 {data_home} 目录下。我们建议你不用配置 cache_path，因为数据库会自动设置该目录。

自 v0.12 之后，写入缓存不再是实验性的功能。你可以通过修改 mito 的配置调整缓存的大小

1. [[region_engine]]
2. [region_engine.mito]

4. write_cache_size = "10GiB"

更详细的信息请参阅性能调优技巧。

WAL 选项

datanode 和 standalone 在 [wal] 部分可以配置 Write-Ahead-Log 的对应参数：

Local WAL

1. [wal]
2. file_size = "256MB"
3. purge_threshold = "4GB"
4. purge_interval = "10m"
5. read_batch_size = 128
6. sync_write = false

• dir: WAL 的日志目录， 当使用文件 File 存储的时候, 默认值为{data_home}/wal 。当使用对象存储的时候，必须明确指定。
• file_size: 单个日志文件的最大大小，默认为 256MB。
• purge_threshold 和 purge_interval: 控制清除任务的触发阈值和间隔
• sync_write: 是否在写入每条日志的时候调用 l fsync 刷盘。

Remote WAL

1. [wal]
2. provider = "kafka"
3. broker_endpoints = ["127.0.0.1:9092"]
4. max_batch_bytes = "1MB"
5. consumer_wait_timeout = "100ms"
6. backoff_init = "500ms"
7. backoff_max = "10s"
8. backoff_base = 2
9. backoff_deadline = "5mins"
10. overwrite_entry_start_id = false

• broker_endpoints：Kafka 端点
• max_batch_bytes：单个 producer batch 的最大值
• consumer_wait_timeout：consumer 的等待超时时间
• backoff_init：backoff 初始延迟
• backoff_max：：backoff 最大延迟
• backoff_base：：backoff 指数
• backoff_deadline：重试的截止时间
• overwrite_entry_start_id: 该选项确保在 Kafka 消息被误删除时，系统仍然能够成功重放内存表数据，而不会抛出超出范围（out-of-range）的错误。然而，启用此选项可能会导致意外的数据丢失，因为系统会跳过缺失的条目，而不是将其视为严重错误。

Remote WAL 鉴权 (Optional)

1. [wal.sasl]
2. type = "SCRAM-SHA-512"
3. username = "user"
4. password = "secret"

Kafka 客户端 SASL 鉴权配置，支持的 SASL 机制 : PLAIN, SCRAM-SHA-256, SCRAM-SHA-512.

Remote WAL TLS (Optional)

1. [wal.tls]
2. server_ca_cert_path = "/path/to/server_cert"
3. client_cert_path = "/path/to/client_cert"
4. client_key_path = "/path/to/key"

Kafka 客户端 TLS 配置，支持 TLS（使用系统 CA 证书），TLS（使用特定 CA 证书），mTLS。

配置示例:

TLS (使用系统 CA 证书)

1. [wal.tls]

TLS (使用特定 CA 证书)

1. [wal.tls]
2. server_ca_cert_path = "/path/to/server_cert"

mTLS

1. [wal.tls]
2. server_ca_cert_path = "/path/to/server_cert"
3. client_cert_path = "/path/to/client_cert"
4. client_key_path = "/path/to/key"

Logging 选项

frontend、metasrv、datanode 和 standalone 都可以在 [logging] 部分配置 log、tracing 相关参数：

1. [logging]
2. dir = "/tmp/greptimedb/logs"
3. level = "info"
4. enable_otlp_tracing = false
5. otlp_endpoint = "localhost:4317"
6. append_stdout = true
7. [logging.tracing_sample_ratio]
8. default_ratio = 1.0

• dir: log 输出目录。
• level: log 输出的日志等级，日志等级有 info, debug, error, warn，默认等级为 info。
• enable_otlp_tracing：是否打开分布式追踪，默认不开启。
• otlp_endpoint：使用基于 gRPC 的 OTLP 协议导出 tracing 的目标端点，默认值为 localhost:4317。
• append_stdout：是否将日志打印到 stdout。默认是true。
• tracing_sample_ratio：该字段可以配置 tracing 的采样率，如何使用 tracing_sample_ratio，请参考 如何配置 tracing 采样率。

如何使用分布式追踪，请参考 Tracing

Region 引擎选项

datanode 和 standalone 在 [region_engine] 部分可以配置不同存储引擎的对应参数。目前只可以配置存储引擎 mito 的选项。

部分常用的选项如下

1. [[region_engine]]
2. [region_engine.mito]
3. num_workers = 8
4. manifest_checkpoint_distance = 10
5. max_background_jobs = 4
6. auto_flush_interval = "1h"
7. global_write_buffer_size = "1GB"
8. global_write_buffer_reject_size = "2GB"
9. sst_meta_cache_size = "128MB"
10. vector_cache_size = "512MB"
11. page_cache_size = "512MB"
12. sst_write_buffer_size = "8MB"
13. scan_parallelism = 0

15. [region_engine.mito.index]
16. aux_path = ""
17. staging_size = "2GB"
18. metadata_cache_size = "64MiB"
19. content_cache_size = "128MiB"
20. content_cache_page_size = "64KiB"

22. [region_engine.mito.inverted_index]
23. create_on_flush = "auto"
24. create_on_compaction = "auto"
25. apply_on_query = "auto"
26. mem_threshold_on_create = "64M"
27. intermediate_path = ""

29. [region_engine.mito.memtable]
30. type = "time_series"

此外，mito 也提供了一个实验性质的 memtable。该 memtable 主要优化大量时间序列下的写入性能和内存占用。其查询性能可能会不如默认的 time_series memtable。

1. [region_engine.mito.memtable]
2. type = "partition_tree"
3. index_max_keys_per_shard = 8192
4. data_freeze_threshold = 32768
5. fork_dictionary_bytes = "1GiB"

以下是可供使用的选项

设定 meta client

meta_client 选项适用于 datanode 和 frontend 模块，用于指定 Metasrv 的相关信息。

1. [meta_client]
2. metasrv_addrs = ["127.0.0.1:3002"]
3. timeout = "3s"
4. connect_timeout = "1s"
5. ddl_timeout = "10s"
6. tcp_nodelay = true

通过 meta_client 配置 metasrv 客户端，包括：

• metasrv_addrs， Metasrv 地址列表，对应 Metasrv 启动配置的 server address。
• timeout， 操作超时时长，默认为 3 秒。
• connect_timeout，连接服务器超时时长，默认为 1 秒。
• ddl_timeout， DDL 执行的超时时间，默认 10 秒。
• tcp_nodelay，接受连接时的 TCP_NODELAY 选项，默认为 true。

指标监控选项

这些选项用于将系统监控指标保存到 GreptimeDB 本身。 有关如何使用此功能的说明，请参见 监控 指南。

1. [export_metrics]
2. # Whether to enable export_metrics
3. enable=true
4. # Export time interval
5. write_interval = "30s"

• enable: 是否启用导出指标功能，默认为 false。
• write_interval: 指标导出时间间隔。

self_import 方法

仅 frontend 和 standalone 支持使用 self_import 方法导出指标。

1. [export_metrics]
2. # Whether to enable export_metrics
3. enable=true
4. # Export time interval
5. write_interval = "30s"
6. [export_metrics.self_import]
7. db = "information_schema"

• db: 默认的数据库为 information_schema，你也可以创建另一个数据库来保存系统指标。

remote_write 方法

datanode、frontend、metasrv 和 standalone 支持使用 remote_write 方法导出指标。 它将指标发送到与 Prometheus Remote-Write protocol 兼容的接受端。

1. [export_metrics]
2. # Whether to enable export_metrics
3. enable=true
4. # Export time interval
5. write_interval = "30s"
6. [export_metrics.remote_write]
7. # URL specified by Prometheus Remote-Write protocol
8. url = "http://127.0.0.1:4000/v1/prometheus/write?db=information_schema"
9. # Some optional HTTP parameters, such as authentication information
10. headers = { Authorization = "Basic Z3JlcHRpbWVfdXNlcjpncmVwdGltZV9wd2Q=" }

• url: Prometheus Remote-Write 协议指定的 URL。
• headers: 一些可选的 HTTP 参数，比如认证信息。

Mode 选项

mode 选项在 datanode、frontend 和 standalone 中可用，它指定了组件的运行模式。

在分布式 GreptimeDB 的 datanode 和 frontend 的配置文件中，需要将值设置为 distributed：

1. mode = "distributed"

在 standalone GreptimeDB 的配置文件中，需要将值设置为 standalone：

1. mode = "standalone"

心跳配置

心跳配置在 frontend 和 datanode 中可用。

1. [heartbeat]
2. interval = "3s"
3. retry_interval = "3s"

默认时区配置

default_timezone 选项适用于 frontend 模块和 standalone 模式，默认值为 UTC。 它指定了与 GreptimeDB 交互时的客户端默认时区。 如果在客户端中指定了时区，此选项将在该客户端会话中被覆盖。

1. default_timezone = "UTC"

default_timezone 的值可以是任何时区名称，例如 Europe/Berlin 或 Asia/Shanghai。 有关客户端时区如何影响数据的写入和查询，请参阅时区文档。

仅限于 Metasrv 的配置

1. # 工作主目录。
2. data_home = "/tmp/metasrv/"
3. # metasrv 的绑定地址，默认为 "127.0.0.1:3002"。
4. bind_addr = "127.0.0.1:3002"
5. # frontend 和 datanode 连接到 metasrv 的通信服务器地址，本地默认为 "127.0.0.1:3002"。
6. server_addr = "127.0.0.1:3002"
7. # metasrv 存储端服务器地址，默认为 "127.0.0.1:2379"。
8. # 根据你的存储服务器类型配置地址，例如：
9. # - 使用 "127.0.0.1:2379" 连接到 etcd
10. # - 使用 "password=password dbname=postgres user=postgres host=localhost port=5432" 连接到 postgres
11. store_addr = "127.0.0.1:2379"
12. # Datanode 选择器类型。
13. # - "lease_based" (默认值)
14. # - "load_based"
15. # 详情请参阅 "https://docs.greptime.com/contributor-guide/meta/selector"
16. selector = "lease_based"
17. # 将数据存储在内存中，默认值为 false。
18. use_memory_store = false
19. ## 是否启用 region failover。
20. ## 该功能仅适用于运行在集群模式下的 GreptimeDB，并且
21. ## - 使用 Remote WAL
22. ## - 使用共享存储（例如 s3）。
23. enable_region_failover = false
24. # metasrv 的数据库类型.
25. ## 可选项：
26. ## - "etcd_store" (默认值)
27. ## - "memory_store" (纯内存存储 - 仅用于测试)
28. ## - "postgres_store"
29. backend = "etcd_store"

31. ## Procedure 选项
32. [procedure]

34. ## 最大重试次数
35. max_retry_times = 12

37. ## 程序的初始重试延迟
38. retry_delay = "500ms"

40. # Failure detector 选项
41. [failure_detector]

43. ## Failure detector 检测阈值
44. threshold = 8.0

46. ## 心跳间隔的最小标准差，用于计算可接受的变化。
47. min_std_deviation = "100ms"

49. ## 心跳之间可接受的暂停时间长度。
50. acceptable_heartbeat_pause = "10000ms"

52. ## 首次心跳间隔的估计值。
53. first_heartbeat_estimate = "1000ms"

55. ## Datanode 选项。
56. [datanode]

58. ## Datanode 客户端配置。
59. [datanode.client]

61. ## 操作超时时间
62. timeout = "10s"

64. ## 连接服务器超时时间。
65. connect_timeout = "10s"

67. ## 接受连接时的 `TCP_NODELAY` 选项，默认为 true。
68. tcp_nodelay = true

70. [wal]
71. # 可用的 WAL 提供者：
72. # - `raft_engine`（默认）：由于 metasrv 目前仅涉及远程 WAL，因此没有 raft-engine WAL 配置。
73. # - `kafka`：在 datanode 中使用 kafka WAL 提供者时，metasrv **必须** 配置 kafka WAL 配置。
74. provider = "raft_engine"

76. # Kafka WAL 配置。

78. ## Kafka 集群的代理端点。
79. broker_endpoints = ["127.0.0.1:9092"]

81. ## 自动为 WAL 创建 topics
82. ## 设置为 `true` 则自动为 WAL 创建 topics
83. ## 否则，使用名为 `topic_name_prefix_[0..num_topics)` 的 topics
84. auto_create_topics = true

86. ## Topic 数量。
87. num_topics = 64

89. ## Topic selector 类型。
90. ## 可用的 selector 类型：
91. ## - `round_robin`（默认）
92. selector_type = "round_robin"

94. ## Kafka topic 通过连接 `topic_name_prefix` 和 `topic_id` 构建。
95. topic_name_prefix = "greptimedb_wal_topic"

97. ## 每个分区的预期副本数。
98. replication_factor = 1

100. ## 超过此时间创建 topic 的操作将被取消。
101. create_topic_timeout = "30s"

103. ## Kafka 客户端的 backoff 初始时间。
104. backoff_init = "500ms"

106. ## Kafka 客户端的 backoff 最大时间。
107. backoff_max = "10s"

109. ## backoff 指数，即下一个 backoff 时间 = 该指数 * 当前 backoff 时间。
110. backoff_base = 2

112. ## 如果总等待时间达到截止时间，则停止重新连接。如果此配置缺失，则重新连接不会终止。
113. backoff_deadline = "5mins"

仅限于 Datanode 的配置

1. node_id = 42
2. [grpc]
3. bind_addr = "127.0.0.1:3001"
4. server_addr = "127.0.0.1:3001"
5. runtime_size = 8

仅限于 Frontend 的配置

1. [datanode]
2. [datanode.client]
3. connect_timeout = "1s"
4. tcp_nodelay = true