Configuration

GreptimeDB supports layered configuration with the following precedence order (where each item overrides the one below it):

• Greptime command line options
• Configuration file options
• Environment variables
• Default values

You only need to set up the configurations you require. GreptimeDB will assign default values for any settings not configured.

How to set up configurations

Greptime command line options

You can specify several configurations using command line arguments. For example, to start GreptimeDB in standalone mode with a configured HTTP address:

greptime standalone start --http-addr 127.0.0.1:4000

For all the options supported by the Greptime command line, refer to the GreptimeDB Command Line Interface.

Configuration file options

You can specify configurations in a TOML file. For example, create a configuration file standalone.example.toml as shown below:

[storage]
type = "File"
data_home = "greptimedb_data"

Then, specify the configuration file using the command line argument -c [file_path].

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

For example, to start in standalone mode:

greptime standalone start -c standalone.example.toml

Example files

Below are example configuration files for each GreptimeDB component, including all available configurations. In actual scenarios, you only need to configure the required options and do not need to configure all options as in the sample file.

• standalone
• frontend
• datanode
• flownode
• metasrv

Helm Configurations

When deploying GreptimeDB on Kubernetes using Helm charts, you can configure certain settings directly in the Helm values.yaml file. Please refer to the Helm configuration documentation for all Helm-supported configurations.

For configurations that are available only in the options section of this document, you can inject complete TOML configuration files into your deployment.

Environment variable

Every item in the configuration file can be mapped to environment variables. For example, to set the data_home configuration item for the datanode using an environment variable:

# ...
[storage]
data_home = "/data/greptimedb"
# ...

Use the following shell command to set the environment variable in the following format:

export GREPTIMEDB_DATANODE__STORAGE__DATA_HOME=/data/greptimedb

Environment Variable Rules

• Each environment variable should have the component prefix, for example:

  • GREPTIMEDB_FRONTEND
  • GREPTIMEDB_METASRV
  • GREPTIMEDB_DATANODE
  • GREPTIMEDB_STANDALONE

• Use double underscore __ separators. For example, the data structure storage.data_home is transformed to STORAGE__DATA_HOME.

The environment variable also accepts lists that are separated by commas ,, for example:

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

Options

In this section, we will introduce some main configuration options. For all options, refer to the Configuration Reference on Github.

Protocol options

Protocol options are valid in frontend and standalone subcommands, specifying protocol server addresses and other protocol-related options.

NOTE

The HTTP protocol configuration is available for all GreptimeDB components: frontend, datanode, flownode, and metasrv.

Below is an example configuration with the most commonly used options for all protocols that require attention. You can change the values or disable certain protocols in your configuration file. For example, to disable OpenTSDB protocol support, set the enable parameter to false. Note that HTTP and gRPC protocols cannot be disabled for the database to function correctly.

[http]
# HTTP server binding address. Defaults to "127.0.0.1:4000" and therefore listens only on the loopback interface, so external hosts cannot reach it.
# For production, adjust this to an accessible IP address or domain based on your network configuration.
addr = "127.0.0.1:4000"
timeout = "30s"
body_limit = "64MB"
# Maximum total memory (bytes) for all concurrent HTTP request bodies, rejects requests immediately when exceeded, defaults to "0" (unlimited)
# Limits memory usage for HTTP writes on a single node to prevent OOM from fast writes, only tracks HTTP body size, excludes decompression and internal processing memory
# Recommended to adjust after evaluating with `greptime_servers_http_memory_usage_bytes` metric, this option provides auxiliary protection only
max_total_body_memory = "0"
enable_cors = true
prom_validation_mode = "strict"

[grpc]
# gRPC service binding address, defaults to "127.0.0.1:4001".
# The default configuration only listens on the loopback address and is inaccessible from external hosts. For production, adjust to an accessible IP address or domain based on your network configuration.
bind_addr = "127.0.0.1:4001"
# Communication address registered with metasrv for other nodes to discover and connect, can be IP address or domain
# This value is only for external registration and does not affect the local listening `grpc.bind_addr`; it defaults to 127.0.0.1, so other nodes cannot connect via the metasrv-returned address.
# If left empty or unset, the server automatically uses the first network interface's IP address with the same port as `grpc.bind_addr`
server_addr = "127.0.0.1:4001"
runtime_size = 8
# Maximum total memory (bytes) for all concurrent gRPC request messages, rejects requests immediately when exceeded, defaults to "0" (unlimited)
# Limits memory usage for gRPC writes on a single node to prevent OOM from fast writes, only tracks gRPC message size, excludes decompression and internal processing memory
# Recommended to adjust after evaluating with `greptime_servers_grpc_memory_usage_bytes` metric, this option provides auxiliary protection only
max_total_message_memory = "0"
# To enable TLS for gRPC traffic, add a `[grpc.tls]` section; field details are listed in the TLS table below.

[mysql]
# Whether to enable the MySQL protocol, defaults to true.
enable = true
# MySQL server address. Defaults to "127.0.0.1:4002" and therefore listens only on the loopback interface, so external hosts cannot reach it.
# For production, adjust this to an accessible IP address or domain based on your network configuration.
addr = "127.0.0.1:4002"
# To enable TLS for MySQL, add a `[mysql.tls]` section; field details are listed in the TLS table below.

[postgres]
# Whether to enable the PostgreSQL protocol, defaults to true.
enable = true
# PostgreSQL server address. Defaults to "127.0.0.1:4003" and therefore listens only on the loopback interface, so external hosts cannot reach it.
# For production, adjust this to an accessible IP address or domain based on your network configuration.
addr = "127.0.0.1:4003"
# To enable TLS for PostgreSQL, add a `[postgres.tls]` section; field details are listed in the TLS table below.

[opentsdb]
# Whether to enable OpenTSDB protocol support over the HTTP API, defaults to true.
enable = true

[influxdb]
# Whether to enable InfluxDB line protocol support over the HTTP API, defaults to true.
enable = true

[jaeger]
# Whether to enable Jaeger trace ingestion over the HTTP API, defaults to true.
enable = true

[prom_store]
# Whether to enable Prometheus remote read/write endpoints, defaults to true.
enable = true
# Whether to use Metric Engine when handling Prometheus remote write requests, defaults to true.
with_metric_engine = true

You can enable TLS for MySQL, Postgres and gRPC by adding [mysql.tls], [postgres.tls] or [grpc.tls] sections to your configuration. The following table lists the shared fields for these TLS sections:

Option	Key	Type	Description
mysql.tls, postgres.tls or grpc.tls			TLS configuration for MySQL / Postgres / gRPC
	mode	String	TLS mode, options are disable, prefer and require
	cert_path	String	File path for TLS certificate
	key_path	String	File path for TLS private key
	watch	Boolean	Watch file system changes and reload certificate and key file

Query options

The query options are valid in standalone, datanode and frontend modes, which controls the query engine's behavior.

The following table describes the options in detail:

Option	Key	Type	Description
parallelism	Integer	0	Parallelism of the query engine. Default to 0, which means the number of CPU cores.

A sample configuration:

[query]
parallelism = 0

Storage options

The storage options are valid in datanode and standalone mode, which specify the database data directory and other storage-related options.

GreptimeDB supports storing data in local file system, AWS S3 and compatible services (including MinIO, digitalocean space, Tencent Cloud Object Storage(COS), Baidu Object Storage(BOS) and so on), Azure Blob Storage and Aliyun OSS.

Option	Key	Type	Description
storage			Storage options
	type	String	Storage type, supports "File", "S3", "Gcs", "Azblob", and "Oss"
	enable_read_cache	Boolean	Whether to enable read cache. Enabled by default when using object storage. Recommended for better performance with object storage
	cache_path	String	Read cache directory path for object storage. Defaults to {data_home}/cache. Set to empty string to disable cache
	cache_capacity	String	Maximum cache capacity. Recommended to set larger if disk space is sufficient. Examples: "10GB", "512MB"
File			Local file storage options, valid when type="File"
	data_home	String	Database storage root directory, "./greptimedb_data" by default
S3			AWS S3 storage options, valid when type="S3"
	name	String	The storage provider name, default is S3
	bucket	String	The S3 bucket name
	root	String	The root path in S3 bucket
	endpoint	String	The API endpoint of S3
	region	String	The S3 region
	access_key_id	String	The S3 access key id
	secret_access_key	String	The S3 secret access key
	enable_virtual_host_style	Boolean	Send API requests in virtual host style instead of path style. Default is false.
Oss			Aliyun OSS storage options, valid when type="Oss"
	name	String	The storage provider name, default is Oss
	bucket	String	The OSS bucket name
	root	String	The root path in OSS bucket
	endpoint	String	The API endpoint of OSS
	access_key_id	String	The OSS AccessKey ID
	access_key_secret	String	The OSS AccessKey Secret
Azblob			Azure Blob Storage options, valid when type="Azblob"
	name	String	The storage provider name, default is Azblob
	container	String	The container name
	root	String	The root path in container
	endpoint	String	The API endpoint of Azure Blob Storage
	account_name	String	The account name of Azure Blob Storage
	account_key	String	The access key
	sas_token	String	The shared access signature
Gsc			Google Cloud Storage options, valid when type="Gsc"
	name	String	The storage provider name, default is Gsc
	root	String	The root path in Gsc bucket
	bucket	String	The Gsc bucket name
	scope	String	The Gsc service scope
	credential_path	String	The Gsc credentials path
	endpoint	String	The API endpoint of Gsc

A file storage sample configuration:

[storage]
type = "File"
data_home = "./greptimedb_data/"

A S3 storage sample configuration:

[storage]
type = "S3"
bucket = "test_greptimedb"
root = "/greptimedb"
access_key_id = "<access key id>"
secret_access_key = "<secret access key>"

# Read cache configuration
enable_read_cache = true
#+ cache_path = ""
cache_capacity = "10GB"

Storage http client

[storage.http_client] sets the options for the http client that is used to send requests to the storage service.

Only applied for storage types "S3", "Oss", "Azblob" and "Gcs".

Key	Type	Default	Description
pool_max_idle_per_host	Integer	1024	The maximum idle connection per host allowed in the pool.
connect_timeout	String	"30s" (30 seconds)	The timeout for only the connect phase of a http client.
timeout	String	"30s" (30 seconds)	The total request timeout, applied from when the request starts connecting until the response body has finished. Also considered a total deadline.
pool_idle_timeout	String	"90s" (90 seconds)	The timeout for idle sockets being kept-alive.
skip_ssl_validation	Boolean	false	Whether to skip SSL certificate verification. Security Notice: Setting skip_ssl_validation = true disables certificate verification, making connections vulnerable to man-in-the-middle attacks. Only use this in development or trusted private networks. Default: false

Storage engine provider

[[storage.providers]] setups the table storage engine providers. Based on these providers, you can create a table with a specified storage, see create table:

# Allows using multiple storages
[[storage.providers]]
name = "S3"
type = "S3"
bucket = "test_greptimedb"
root = "/greptimedb"
access_key_id = "<access key id>"
secret_access_key = "<secret access key>"

[[storage.providers]]
name = "Gcs"
type = "Gcs"
bucket = "test_greptimedb"
root = "/greptimedb"
credential_path = "<gcs credential path>"

All configured providers' names can be used as the storage option when creating tables.

For storage from the same provider, if you want to use different S3 buckets as storage engines for different tables, you can set different name values and specify the storage option when creating the table.

Object storage cache

When using remote storage services like AWS S3, Alibaba Cloud OSS, or Azure Blob Storage, fetching data during queries can be time-consuming. To address this, GreptimeDB provides a local cache mechanism to speed up repeated data access.

GreptimeDB enables local file caching for remote object storage by default, with both read and write cache capacity set to 5GiB.

Usually you don't have to configure the cache unless you want to specify the cache capacity.

[storage]
type = "S3"
bucket = "test_greptimedb"
root = "/greptimedb"
access_key_id = "<access key id>"
secret_access_key = "<secret access key>"
cache_capacity = "10GiB"
#+ cache_path = "/path/to/cache/home"

The cache_path specifies the home directory for storing cache files, while cache_capacity determines the maximum total file size allowed in the cache directory in bytes. You can disable the read cache by setting cache_path to an empty string. The default cache path is under the {data_home}. We recommend that you don't set the cache_path because the database can choose it automatically.

The write cache is no longer experimental since v0.12. When using object storage, write cache is automatically enabled by default. You can configure it in the mito config:

[[region_engine]]
[region_engine.mito]

# Write cache is automatically enabled when using object storage
enable_write_cache = true
#+ write_cache_path = ""
write_cache_size = "10GiB"
#+ write_cache_ttl = ""

Available write cache options:

Key	Type	Default	Description
enable_write_cache	Boolean	false	Whether to enable write cache. Automatically enabled when using object storage. Recommended for performance
write_cache_path	String	""	File system path for write cache. Defaults to {data_home}. Leave empty for automatic path selection
write_cache_size	String	5GiB	Write cache capacity. Recommended to set larger if disk space is sufficient
write_cache_ttl	String	Unset	TTL (time-to-live) for write cache entries. Example: "7d" for 7 days

Read Performance Tuning Tips for more detailed info.

WAL options

GreptimeDB supports two WAL storage options—Local WAL and Remote WAL. See the WAL Overview for a comparison of the two. For detailed configurations, refer to the Local WAL and Remote WAL documentation.

Logging options

frontend, metasrv, datanode and standalone can all configure log and tracing related parameters in the [logging] section:

[logging]
dir = "./greptimedb_data/logs"
level = "info"
enable_otlp_tracing = false
otlp_endpoint = "http://localhost:4318/v1/traces"
otlp_export_protocol = "http"
append_stdout = true
log_format = "text"
max_log_files = 720

[logging.tracing_sample_ratio]
default_ratio = 1.0

Available logging options:

Key	Type	Default	Description
dir	String	./greptimedb_data/logs	Log output directory. Set to empty string to disable file logging
level	String	info	Log level. Available: info, debug, warn, error
log_format	String	text	Log format. Available: text, json
max_log_files	Integer	720	Maximum number of log files to keep
append_stdout	Boolean	true	Whether to append logs to stdout
enable_otlp_tracing	Bool	false	Whether to enable OTLP tracing
otlp_endpoint	String	http://localhost:4318/v1/traces	OTLP tracing endpoint URL
otlp_export_protocol	String	http	OTLP export protocol. Available: http, grpc
tracing_sample_ratio	--	--	Tracing sampling configuration. See tracing sampling rate
tracing_sample_ratio.default_ratio	Float	1.0	Default sampling ratio. Valid range: [0, 1]. 1 means all traces sampled, 0 means none

How to use distributed tracing, please reference Tracing

Region engine options

The parameters corresponding to different storage engines can be configured for datanode and standalone in the [region_engine] section. Currently, only options for mito region engine is available.

Frequently used options:

[[region_engine]]
[region_engine.mito]
num_workers = 8
worker_channel_size = 128
worker_request_batch_size = 64
manifest_checkpoint_distance = 10
#+ compress_manifest = false
max_background_jobs = 4
#+ max_background_flushes = 4
#+ max_background_compactions = 2
#+ max_background_purges = 8
auto_flush_interval = "1h"
global_write_buffer_size = "1GB"
global_write_buffer_reject_size = "2GB"
sst_meta_cache_size = "128MB"
vector_cache_size = "512MB"
page_cache_size = "512MB"
selector_result_cache_size = "512MB"
sst_write_buffer_size = "8MB"
parallel_scan_channel_size = 32
max_concurrent_scan_files = 384
scan_parallelism = 0
#+ min_compaction_interval = "0m"
#+ allow_stale_entries = false

[region_engine.mito.index]
aux_path = ""
staging_size = "2GB"
staging_ttl = "7d"
metadata_cache_size = "64MiB"
content_cache_size = "128MiB"
content_cache_page_size = "64KiB"
result_cache_size = "128MiB"

[region_engine.mito.inverted_index]
create_on_flush = "auto"
create_on_compaction = "auto"
apply_on_query = "auto"
mem_threshold_on_create = "auto"

[region_engine.mito.fulltext_index]
create_on_flush = "auto"
create_on_compaction = "auto"
apply_on_query = "auto"
mem_threshold_on_create = "auto"

[region_engine.mito.bloom_filter_index]
create_on_flush = "auto"
create_on_compaction = "auto"
apply_on_query = "auto"
mem_threshold_on_create = "auto"

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

The mito engine provides an experimental memtable which optimizes for write performance and memory efficiency under large amounts of time-series. Its read performance might not as fast as the default time_series memtable.

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

Available options:

Key	Type	Default	Descriptions
num_workers	Integer	8	Number of region workers.
worker_channel_size	Integer	128	Request channel size of each worker.
worker_request_batch_size	Integer	64	Max batch size for a worker to handle requests.
manifest_checkpoint_distance	Integer	10	Number of meta action updated to trigger a new checkpoint for the manifest.
compress_manifest	Boolean	false	Whether to compress manifest and checkpoint file by gzip.
max_background_jobs	Integer	4	Max number of running background jobs
max_background_flushes	Integer	Auto	Max number of running background flush jobs. Defaults to 1/2 of cpu cores.
max_background_compactions	Integer	Auto	Max number of running background compaction jobs. Defaults to 1/4 of cpu cores.
max_background_purges	Integer	Auto	Max number of running background purge jobs. Defaults to number of cpu cores.
auto_flush_interval	String	1h	Interval to auto flush a region if it has not flushed yet.
global_write_buffer_size	String	1GB	Global write buffer size for all regions. If not set, it's default to 1/8 of OS memory with a max limitation of 1GB.
global_write_buffer_reject_size	String	2GB	Global write buffer size threshold to reject write requests. If not set, it's default to 2 times of global_write_buffer_size
sst_meta_cache_size	String	128MB	Cache size for SST metadata. Setting it to 0 to disable the cache. If not set, it's default to 1/32 of OS memory with a max limitation of 128MB.
vector_cache_size	String	512MB	Cache size for vectors and arrow arrays. Setting it to 0 to disable the cache. If not set, it's default to 1/16 of OS memory with a max limitation of 512MB.
page_cache_size	String	512MB	Cache size for pages of SST row groups. Setting it to 0 to disable the cache. If not set, it's default to 1/8 of OS memory.
selector_result_cache_size	String	512MB	Cache size for time series selector (e.g. last_value()). Setting it to 0 to disable the cache. If not set, it's default to 1/8 of OS memory.
sst_write_buffer_size	String	8MB	Buffer size for SST writing.
parallel_scan_channel_size	Integer	32	Capacity of the channel to send data from parallel scan tasks to the main task.
max_concurrent_scan_files	Integer	384	Maximum number of SST files to scan concurrently.
scan_parallelism	Integer	0	Parallelism to scan a region (default: 1/4 of cpu cores). - 0: using the default value (1/4 of cpu cores). - 1: scan in current thread. - n: scan in parallelism n.
min_compaction_interval	String	0m	Minimum time interval between two compactions. Default is 0 (no restrictions).
allow_stale_entries	Boolean	false	Whether to allow stale WAL entries read during replay.
index	--	--	The options for index in Mito engine.
index.aux_path	String	""	Auxiliary directory path for the index in the filesystem. This path is used to store intermediate files for creating the index and staging files for searching the index. It defaults to {data_home}/index_intermediate. The default name for this directory is index_intermediate for backward compatibility. This path contains two subdirectories: __intm for storing intermediate files used during index creation, and staging for storing staging files used during index searching.
index.staging_size	String	2GB	The maximum capacity of the staging directory.
index.staging_ttl	String	7d	TTL of the staging directory. Defaults to 7 days. Set to "0s" to disable TTL.
index.metadata_cache_size	String	64MiB	Cache size for index metadata.
index.content_cache_size	String	128MiB	Cache size for index content.
index.content_cache_page_size	String	64KiB	Page size for index content cache.
index.result_cache_size	String	128MiB	Cache size for index result.
inverted_index	--	--	The options for inverted index in Mito engine.
inverted_index.create_on_flush	String	auto	Whether to create the index on flush. - auto: automatically - disable: never
inverted_index.create_on_compaction	String	auto	Whether to create the index on compaction. - auto: automatically - disable: never
inverted_index.apply_on_query	String	auto	Whether to apply the index on query - auto: automatically - disable: never
inverted_index.mem_threshold_on_create	String	auto	Memory threshold for index creation. - auto: automatically determine based on system memory (default) - unlimited: no memory limit - [size] e.g. 64MB: fixed memory threshold
fulltext_index	--	--	The options for full-text index in Mito engine.
fulltext_index.create_on_flush	String	auto	Whether to create the index on flush. - auto: automatically (default) - disable: never
fulltext_index.create_on_compaction	String	auto	Whether to create the index on compaction. - auto: automatically (default) - disable: never
fulltext_index.apply_on_query	String	auto	Whether to apply the index on query. - auto: automatically (default) - disable: never
fulltext_index.mem_threshold_on_create	String	auto	Memory threshold for index creation. - auto: automatically determine based on system memory (default) - unlimited: no memory limit - [size] e.g. 64MB: fixed memory threshold
bloom_filter_index	--	--	The options for bloom filter index in Mito engine.
bloom_filter_index.create_on_flush	String	auto	Whether to create the bloom filter on flush. - auto: automatically (default) - disable: never
bloom_filter_index.create_on_compaction	String	auto	Whether to create the bloom filter on compaction. - auto: automatically (default) - disable: never
bloom_filter_index.apply_on_query	String	auto	Whether to apply the bloom filter on query. - auto: automatically (default) - disable: never
bloom_filter_index.mem_threshold_on_create	String	auto	Memory threshold for bloom filter creation. - auto: automatically determine based on system memory (default) - unlimited: no memory limit - [size] e.g. 64MB: fixed memory threshold
memtable.type	String	time_series	Memtable type. - time_series: time-series memtable - partition_tree: partition tree memtable (experimental)
memtable.index_max_keys_per_shard	Integer	8192	The max number of keys in one shard. Only available for partition_tree memtable.
memtable.data_freeze_threshold	Integer	32768	The max rows of data inside the actively writing buffer in one shard. Only available for partition_tree memtable.
memtable.fork_dictionary_bytes	String	1GiB	Max dictionary bytes. Only available for partition_tree memtable.

Specify meta client

The meta_client options are valid in datanode and frontend mode, which specify the Metasrv client information.

[meta_client]
metasrv_addrs = ["127.0.0.1:3002"]
timeout = "3s"
heartbeat_timeout = "500ms"
connect_timeout = "1s"
ddl_timeout = "10s"
tcp_nodelay = true

# Metadata cache configuration
metadata_cache_max_capacity = 100000
metadata_cache_ttl = "10m"
metadata_cache_tti = "5m"

Available meta client options:

Key	Type	Default	Description
metasrv_addrs	Array	--	The Metasrv address list
timeout	String	3s	Operation timeout
heartbeat_timeout	String	500ms	Heartbeat timeout
connect_timeout	String	1s	Connect server timeout
ddl_timeout	String	10s	DDL execution timeout
tcp_nodelay	Boolean	true	TCP_NODELAY option for accepted connections
metadata_cache_max_capacity	Integer	100000	Maximum capacity of the metadata cache
metadata_cache_ttl	String	10m	TTL (time-to-live) of the metadata cache
metadata_cache_tti	String	5m	TTI (time-to-idle) of the metadata cache

Monitor metrics options

These options are used to save system metrics to GreptimeDB itself. For instructions on how to use this feature, please refer to the Monitoring guide.

[export_metrics]
# Whether to enable export_metrics
enable=true
# Export time interval
write_interval = "30s"

• enable: Whether to enable export_metrics, false by default.
• write_interval: Export time interval.

self_import method

If you are using standalone, you can use the self_import method to export metrics to GreptimeDB itself.

[export_metrics]
# Whether to enable export_metrics
enable=true
# Export time interval
write_interval = "30s"
[export_metrics.self_import]
db = "information_schema"

• db: The default database used by self_import is information_schema. You can also create another database for saving system metrics.

remote_write method

The remote_write method is supported by datanode, frontend, metasrv, and standalone. It sends metrics to a receiver compatible with the Prometheus Remote-Write protocol.

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

• url: URL specified by Prometheus Remote-Write protocol.
• headers: Some optional HTTP parameters, such as authentication information.

Heartbeat configuration

Heartbeat configuration is available in frontend and datanode.

[heartbeat]
interval = "3s"
retry_interval = "3s"

Key	Type	Default	Description
heartbeat	--	--	--
heartbeat.interval	String	3s	Interval for sending heartbeat messages to the Metasrv.
heartbeat.retry_interval	String	3s	Interval for retrying to establish the heartbeat connection to the Metasrv. Note that this option is ignored in Datanode heartbeat implementation because the Datanode must renew its lease through heartbeat within the keep-alive mechanism's lease period. It has a special retry strategy and doesn't allow custom configuration.

Default time zone configuration

The default_timezone option is applicable in both frontend and standalone modes, with a default value of UTC. It specifies the default client timezone for interactions with GreptimeDB. If the time zone is specified in the clients, this option will be overridden for that client session.

default_timezone = "UTC"

The default_timezone value can be any named time zone, such as Europe/Berlin or Asia/Shanghai. For information on how the client time zone affects data ingestion and querying, refer to the Time Zone guide.

Metasrv-only configuration

# The working home directory.
data_home = "./greptimedb_data"
# Store server address default to etcd store.
# For postgres store, the format is:
# "password=password dbname=postgres user=postgres host=localhost port=5432"
# For mysql store, the format is:
# "mysql://user:password@ip:port/dbname"
# For etcd store, the format is:
# "127.0.0.1:2379"
store_addrs = ["127.0.0.1:2379"]
# If it's not empty, the metasrv will store all data with this key prefix.
store_key_prefix = ""
# The datastore for meta server.
# Available values:
# - `etcd_store` (default value)
# - `memory_store`
# - `postgres_store`
# - `mysql_store`
backend = "etcd_store"
# Table name in RDS to store metadata. Effect when using a RDS kvbackend.
# **Only used when backend is RDS kvbacken.**
meta_table_name = "greptime_metakv"
# Advisory lock id in PostgreSQL for election. Effect when using PostgreSQL as kvbackend
# Only used when backend is `postgres_store`.
meta_election_lock_id = 1
# Datanode selector type.
# - `round_robin` (default value)
# - `lease_based`
# - `load_based`
# For details, please see "https://docs.greptime.com/developer-guide/metasrv/selector".
selector = "round_robin"
# Store data in memory, false by default.
use_memory_store = false
# Whether to enable region failover.
# This feature is only available on GreptimeDB running on cluster mode and
# - Using Remote WAL
# - Using shared storage (e.g., s3).
enable_region_failover = false
## The delay before starting region failure detection.
## This delay helps prevent Metasrv from triggering unnecessary region failovers before all Datanodes are fully started.
## Especially useful when the cluster is not deployed with GreptimeDB Operator and maintenance mode is not enabled.
region_failure_detector_initialization_delay = "10m"
# Whether to allow region failover on local WAL.
# **This option is not recommended to be set to true,
# because it may lead to data loss during failover.**
allow_region_failover_on_local_wal = false

## Procedure storage options.
[procedure]

## Procedure max retry time.
max_retry_times = 12

## Initial retry delay of procedures, increases exponentially
retry_delay = "500ms"

## Max running procedures.
## The maximum number of procedures that can be running at the same time.
## If the number of running procedures exceeds this limit, the procedure will be rejected.
max_running_procedures = 128

# Failure detectors options.
# GreptimeDB uses the Phi Accrual Failure Detector algorithm to detect datanode failures.
[failure_detector]

## Maximum acceptable φ before the peer is treated as failed.
## Lower values react faster but yield more false positives.
threshold = 8.0

## The minimum standard deviation of the heartbeat intervals.
## So tiny variations don't make φ explode. Prevents hypersensitivity when heartbeat intervals barely vary.
min_std_deviation = "100ms"

## The acceptable pause duration between heartbeats.
## Additional extra grace period to the learned mean interval before φ rises, absorbing temporary network hiccups or GC pauses.
acceptable_heartbeat_pause = "10000ms"

## Datanode options.
[datanode]

## Datanode client options.
[datanode.client]

## Operation timeout.
timeout = "10s"

## Connect server timeout.
connect_timeout = "10s"

## `TCP_NODELAY` option for accepted connections.
tcp_nodelay = true

[wal]
# Available wal providers:
# - `raft_engine` (default): there're none raft-engine wal config since metasrv only involves in remote wal currently.
# - `kafka`: metasrv **have to be** configured with kafka wal config when using kafka wal provider in datanode.
provider = "raft_engine"

# Kafka wal config.

## The broker endpoints of the Kafka cluster.
broker_endpoints = ["127.0.0.1:9092"]

## Automatically create topics for WAL.
## Set to `true` to automatically create topics for WAL.
## Otherwise, use topics named `topic_name_prefix_[0..num_topics)`
auto_create_topics = true

## Number of topics.
num_topics = 64

## Topic selector type.
## Available selector types:
## - `round_robin` (default)
selector_type = "round_robin"

## A Kafka topic is constructed by concatenating `topic_name_prefix` and `topic_id`.
topic_name_prefix = "greptimedb_wal_topic"

## Expected number of replicas of each partition.
replication_factor = 1

## Above which a topic creation operation will be cancelled.
create_topic_timeout = "30s"

# The Kafka SASL configuration.
# **It's only used when the provider is `kafka`**.
# Available SASL mechanisms:
# - `PLAIN`
# - `SCRAM-SHA-256`
# - `SCRAM-SHA-512`
# [wal.sasl]
# type = "SCRAM-SHA-512"
# username = "user_kafka"
# password = "secret"

# The Kafka TLS configuration.
# **It's only used when the provider is `kafka`**.
# [wal.tls]
# server_ca_cert_path = "/path/to/server_cert"
# client_cert_path = "/path/to/client_cert"
# client_key_path = "/path/to/key"

Key	Type	Default	Descriptions
data_home	String	./greptimedb_data/metasrv/	The working home directory.
bind_addr	String	127.0.0.1:3002	The bind address of metasrv.
server_addr	String	127.0.0.1:3002	The communication server address for frontend and datanode to connect to metasrv, "127.0.0.1:3002" by default for localhost.
store_addrs	Array	["127.0.0.1:2379"]	Store server address. Configure the address based on your backend type, for example: - Use "127.0.0.1:2379" to connect to etcd - Use "password=password dbname=postgres user=postgres host=localhost port=5432" to connect to postgres - Use "mysql://user:password@ip:port/dbname" to connect to mysql
selector	String	lease_based	Datanode selector type. - lease_based (default value). - load_based For details, see Selector
use_memory_store	Bool	false	Store data in memory.
enable_region_failover	Bool	false	Whether to enable region failover. This feature is only available on GreptimeDB running on cluster mode and - Using Remote WAL - Using shared storage (e.g., s3).
region_failure_detector_initialization_delay	String	10m	The delay before starting region failure detection. This delay helps prevent Metasrv from triggering unnecessary region failovers before all Datanodes are fully started. Especially useful when the cluster is not deployed with GreptimeDB Operator and maintenance mode is not enabled.
allow_region_failover_on_local_wal	Bool	false	Whether to allow region failover on local WAL. This option is not recommended to be set to true, because it may lead to data loss during failover.
backend	String	etcd_store	The datastore for metasrv. - etcd_store (default) - memory_store (In memory metadata storage - only used for testing.) - postgres_store - mysql_store
meta_table_name	String	greptime_metakv	Table name in RDS to store metadata. Effect when using a RDS kvbackend. Only used when backend is postgres_store or mysql_store.
meta_election_lock_id	Integer	1	Advisory lock id in PostgreSQL for election. Effect when using PostgreSQL as kvbackend Only used when backend is postgres_store.
procedure	--	--	Procedure storage options.
procedure.max_retry_times	Integer	12	Procedure max retry time.
procedure.retry_delay	String	500ms	Initial retry delay of procedures, increases exponentially
procedure.max_running_procedures	Integer	128	The maximum number of procedures that can be running at the same time. If the number of running procedures exceeds this limit, the procedure will be rejected.
failure_detector	--	--	--
failure_detector.threshold	Float	8.0	Maximum acceptable φ before the peer is treated as failed. Lower values react faster but yield more false positives.
failure_detector.min_std_deviation	String	100ms	The minimum standard deviation of the heartbeat intervals. So tiny variations don't make φ explode. Prevents hypersensitivity when heartbeat intervals barely vary.
failure_detector.acceptable_heartbeat_pause	String	10000ms	The acceptable pause duration between heartbeats. Additional extra grace period to the learned mean interval before φ rises, absorbing temporary network hiccups or GC pauses.
datanode	--	--	Datanode options.
datanode.client	--	--	Datanode client options.
datanode.client.timeout	String	10s	Operation timeout.
datanode.client.connect_timeout	String	10s	Connect server timeout.
datanode.client.tcp_nodelay	Bool	true	TCP_NODELAY option for accepted connections.
wal	--	--	--
wal.provider	String	raft_engine	--
wal.broker_endpoints	Array	--	The broker endpoints of the Kafka cluster.
wal.auto_prune_interval	String	0s	Interval of automatically WAL pruning. Set to 0s to disable automatically WAL pruning which delete unused remote WAL entries periodically.
wal.trigger_flush_threshold	Integer	0	The threshold to trigger a flush operation of a region in automatically WAL pruning. Metasrv will send a flush request to flush the region when: trigger_flush_threshold + prunable_entry_id < max_prunable_entry_id where: - prunable_entry_id is the maximum entry id that can be pruned of the region. Entries before prunable_entry_id are not used by this region. - max_prunable_entry_id is the maximum prunable entry id among all regions in the same topic. Entries before max_prunable_entry_id are not used by any region. Set to 0 to disable the flush operation.
wal.auto_prune_parallelism	Integer	10	Concurrent task limit for automatically WAL pruning. Each task is responsible for WAL pruning for a kafka topic.
wal.num_topics	Integer	64	Number of topics.
wal.selector_type	String	round_robin	Topic selector type. Available selector types: - round_robin (default)
wal.topic_name_prefix	String	greptimedb_wal_topic	A Kafka topic is constructed by concatenating topic_name_prefix and topic_id.
wal.replication_factor	Integer	1	Expected number of replicas of each partition.
wal.create_topic_timeout	String	30s	Above which a topic creation operation will be cancelled.
wal.sasl	String	--	The Kafka SASL configuration.
wal.sasl.type	String	--	The SASL mechanisms, available values: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512.
wal.sasl.username	String	--	The SASL username.
wal.sasl.password	String	--	The SASL password.
wal.tls	String	--	The Kafka TLS configuration.
wal.tls.server_ca_cert_path	String	--	The path of trusted server ca certs.
wal.tls.client_cert_path	String	--	The path of client cert (Used for enable mTLS).
wal.tls.client_key_path	String	--	The path of client key (Used for enable mTLS).

Datanode-only configuration

node_id = 42
[grpc]
bind_addr = "127.0.0.1:3001"
server_addr = "127.0.0.1:3001"
runtime_size = 8

Key	Type	Description
node_id	Integer	The datanode identifier, should be unique.
grpc.bind_addr	String	The address to bind the gRPC server, "127.0.0.1:3001" by default.
grpc.server_addr	String	The address advertised to the metasrv, and used for connections from outside the host. If left empty or unset, the server will automatically use the IP address of the first network interface on the host, with the same port number as the one specified in grpc.bind_addr.
grpc.runtime_size	Integer	The number of gRPC server worker threads, 8 by default.

Frontend-only configuration

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

Key	Type	Default	Description
datanode	--	--	Datanode options.
datanode.client	--	--	Datanode client options.
datanode.client.connect_timeout	String	1s	Connect server timeout.
datanode.client.tcp_nodelay	Bool	true	TCP_NODELAY option for accepted connections.