Skip to main content

config & doctor

Show and manage LynxDB configuration. The config command tree covers initialization, validation, hot-reload, individual settings, and connection profiles. The doctor command checks your environment.

config​

When run without a subcommand, displays the resolved configuration with all overrides applied.

lynxdb config [subcommand] [flags]

Persistent Flags​

Available on config and all its subcommands:

FlagDefaultDescription
--addrListen address override
--data-dirData directory override
--s3-bucketS3 bucket override
--s3-regionAWS region override
--s3-prefixS3 prefix override
--compaction-intervalCompaction interval override
--tiering-intervalTiering interval override
--cache-max-mbCache max size override
--log-levelLog level override

config init​

Create a default config file with all documented settings.

lynxdb config init [--system]
FlagDefaultDescription
--systemfalseWrite to /etc/lynxdb/config.yaml instead of user directory
# Create user config
lynxdb config init

# Create system-wide config
lynxdb config init --system

config validate​

Validate config file and show non-default values. Warns on unknown keys.

lynxdb config validate

config reload​

Send SIGHUP to a running server to reload its configuration. The server writes a PID file so this command can find it automatically.

lynxdb config reload

Hot-reloadable settings (no restart required):

  • log_level
  • retention
  • most query.* execution settings
  • ingest.mode, ingest.max_batch_size, and ingest.max_line_bytes
  • tail.*
  • http.idle_timeout, http.shutdown_timeout, and http.read_header_timeout
  • storage.compaction_rate_limit_mb

Settings that require a restart (server warns on reload):

  • listen
  • data_dir
  • tls.*
  • auth.*
  • no_ui
  • http.rate_limit
  • ingest.max_body_size and ingest-engine settings such as dedup/fsync
  • query.global_query_pool_bytes, query.spill_dir, and query.max_temp_dir_size_bytes
  • storage scheduler settings such as storage.compaction_workers

config get​

Show a single config value. Tab-completes known config keys.

lynxdb config get <key>
lynxdb config get retention
lynxdb config get storage.compression

config set​

Set a config value in the config file.

lynxdb config set <key> <value> [--dry-run]
FlagDefaultDescription
--dry-runfalseShow what would change without applying
lynxdb config set retention 30d
lynxdb config set storage.compression zstd
lynxdb config set retention 1d --dry-run

config edit​

Open config file in $EDITOR. Creates the file with defaults if it does not exist.

lynxdb config edit

config path​

Print the resolved config file path.

lynxdb config path

config reset​

Reset config file to defaults (with confirmation).

lynxdb config reset [--dry-run]
FlagDefaultDescription
--dry-runfalseShow what would be reset without applying

config add-profile​

Add or update a connection profile for quick server switching.

lynxdb config add-profile <name> --url <url> [--token <token>]
FlagDefaultDescription
--url(required)Server URL for the profile
--tokenAuthentication token (optional)
# Add a production profile
lynxdb config add-profile prod --url https://lynxdb.company.com --token xxx

# Add a staging profile without auth
lynxdb config add-profile staging --url https://staging.company.com

Use profiles with the global --profile / -p flag:

lynxdb query 'from main level=error | stats count()' --profile prod
lynxdb query 'from main level=error | stats count()' -p staging

Or set a default profile via environment variable:

export LYNXDB_PROFILE=prod
lynxdb query 'from main level=error | stats count()'

config list-profiles​

List all connection profiles.

lynxdb config list-profiles

config remove-profile​

Remove a connection profile.

lynxdb config remove-profile <name>

Configuration Precedence​

Settings are resolved in this order (highest to lowest priority):

  1. CLI flags (--addr, --data-dir, etc.)
  2. Environment variables (LYNXDB_LISTEN, LYNXDB_DATA_DIR, etc.)
  3. Project file (.lynxdbrc in current or parent directory)
  4. Config file (YAML)
  5. Compiled defaults

Config File Search Order​

When --config is not specified:

  1. LYNXDB_CONFIG environment variable
  2. ./lynxdb.yaml (current directory)
  3. $XDG_CONFIG_HOME/lynxdb/config.yaml (or ~/.config/lynxdb/config.yaml)
  4. ~/.lynxdb/config.yaml
  5. /etc/lynxdb/config.yaml

The first file found is used. If none exist, compiled defaults apply.

Project File (.lynxdbrc)​

A .lynxdbrc YAML file in the current or any parent directory can set per-project defaults:

server: https://staging.company.com
default_format: table
default_since: 6h
default_source: web
profile: staging

These are applied as defaults and are overridden by explicit CLI flags.

  • server, default_format, and profile affect root CLI defaults
  • default_since is applied to lynxdb query when --since is omitted
  • default_source is applied to lynxdb query, lynxdb ingest, and lynxdb import when --source is omitted

Example Config File​

listen: "localhost:3100"
data_dir: "/var/lib/lynxdb"
retention: "7d"
log_level: "info"

storage:
  compression: "lz4"
  row_group_size: 65536
  flush_threshold: "512mb"
  compaction_interval: "30s"
  compaction_workers: 2
  s3_bucket: ""
  s3_region: "us-east-1"
  cache_max_bytes: "1gb"
  cache_ttl: "5m"

query:
  sync_timeout: "30s"
  max_query_runtime: "5m"
  max_concurrent: 32
  default_result_limit: 1000
  max_result_limit: 50000

ingest:
  max_body_size: "100mb"
  max_batch_size: 1000

http:
  idle_timeout: "2m"
  shutdown_timeout: "30s"

doctor​

Run environment diagnostics. Checks binary, config, data directory, server connectivity, disk space, retention, and shell completion.

lynxdb doctor

Supports --format json.

Console Output​

  ok Binary        v0.1.0 (linux/amd64, go1.26.3)
  ok Config        /home/user/.config/lynxdb/config.yaml (valid)
  ok Data dir      /var/lib/lynxdb (42 GB free)
  ok Server        localhost:3100 (healthy, uptime 2d 5h)
  ok Events        3.4M total
  ok Storage       1.2 GB
  ok Retention     7d
  ok Completion    zsh detected

  All checks passed.

See Also​