Client Configuration

This document describes the configuration options for the Spiral client.

Configuration can be set via:

File: ~/.spiral.toml
Environment variables: Prefixed with SPIRAL__ (double underscore)
Runtime overrides: Override values when initializing the client, using the dot notation

Top level

Main configuration for the Spiral client, that can affect many different parts of the client.

Field	Default	Environment Variable	Description
`file_format`	`vortex`	`SPIRAL__FILE_FORMAT`	File format for table storage

Authn

Authentication related settings

Field	Default	Environment Variable	Description
`authn.device_code`	`false`	`SPIRAL__AUTHN__DEVICE_CODE`	Whether to force device code authentication flow. This exist as an override when e.g. ssh-ing into an environment machine.
`authn.token`	`-`	`SPIRAL__AUTHN__TOKEN`	Optional authentication token

Cache

Client cache limits and constraints

Field	Default	Environment Variable	Description
`cache.enabled`	`false`	`SPIRAL__CACHE__ENABLED`	Cache is currently disabled by default.
`cache.memory_capacity_bytes`	`2 * (1 << 30)`	`SPIRAL__CACHE__MEMORY_CAPACITY_BYTES`	Memory cache size in bytes.
`cache.disk_capacity_bytes`	`20 * (1 << 30)`	`SPIRAL__CACHE__DISK_CAPACITY_BYTES`	Disk cache size in bytes.
`cache.disk_path`	`-`	`SPIRAL__CACHE__DISK_PATH`	Disk cache path override. If not set, defaults to $XDG_CACHE_HOME/spiral or ~/.cache/spiral

Limits

Client resource limits and constraints

Field	Default	Environment Variable	Description
`limits.batch_readahead`	`min (num_cpus :: get ()`	`SPIRAL__LIMITS__BATCH_READAHEAD`	Maximum number of concurrent shards to evaluate, “read ahead”, when scanning. Defaults to min(number of CPU cores, 64).
`limits.partition_max_bytes`	`128 * 1024 * 1024`	`SPIRAL__LIMITS__PARTITION_MAX_BYTES`	Maximum number of bytes in an uncompressed fragment file.
`limits.transaction_retries`	`3`	`SPIRAL__LIMITS__TRANSACTION_RETRIES`	Maximum number of transaction retries on conflict before giving up.
`limits.transaction_manifest_max_rows`	`-`	`SPIRAL__LIMITS__TRANSACTION_MANIFEST_MAX_ROWS`	Maximum number of rows in manifest when compacting transaction.
`limits.key_space_max_rows`	`100_000_000`	`SPIRAL__LIMITS__KEY_SPACE_MAX_ROWS`	Maximum number of rows in a key space. Compaction keeps fragments across column groups aligned to L1 key spaces. When this limit is larger, the L1 key spaces might change more frequently, causing a re-alignment to happen. When this limit is smaller, more fragments may have to be split due to key space boundaries.
`limits.http_max_retries`	`10`	`SPIRAL__LIMITS__HTTP_MAX_RETRIES`	Maximum number of HTTP request retries on transient errors.
`limits.write_max_concurrency`	`None`	`SPIRAL__LIMITS__WRITE_MAX_CONCURRENCY`	Maximum number of concurrent write operations when writing table fragments.
`limits.scan_max_concurrency`	`16`	`SPIRAL__LIMITS__SCAN_MAX_CONCURRENCY`	Maximum number of concurrent operations when evaluating multiple nodes during scans.
`limits.fragment_cache_bytes`	`256 * 1024 * 1024`	`SPIRAL__LIMITS__FRAGMENT_CACHE_BYTES`	Maximum in-memory footprint (in bytes) of the fragment cache.

Server

API endpoint configuration for the Spiral control plane

Field	Default	Environment Variable	Description
`server.url`	`https://api.spiraldb.com`	`SPIRAL__SERVER__URL`	The SpiralDB API endpoint URL

Spfs

SpFS (Spiral File System) configuration

Field	Default	Environment Variable	Description
`spfs.url`	`https://spfs.spiraldb.dev`	`SPIRAL__SPFS__URL`	The SpFS (Spiral File System) endpoint URL