varc.toml reference

This is the complete user-facing reference for varc.toml schema version 1. The schema is strict: unknown fields, wrong TOML types, unsupported values, invalid resource names, and unsupported schema versions are errors.

For task-oriented walkthroughs, read Set up and run the CLI, Benchmark, or Migration. For bounded JavaScript and TypeScript automation, see Scripts. For Redis-aware SELECT, UPDATE, and EXPLAIN statements, see SQL.

Discovery and shared syntax

Varc uses the first configuration source that applies:

1. --config <PATH>;
2. the path in VARC_CONFIG; or
3. the nearest varc.toml, walking from the current directory to the Git repository root.

Outside a Git repository, automatic discovery checks only the current directory. Explicit relative configuration paths resolve from the current directory. Paths inside the document resolve from the directory containing varc.toml; they do not expand environment variables or ~.

Resource names are case-sensitive and contain 1–64 ASCII letters, digits, underscores, or hyphens. Duration strings are one positive integer followed by ms, s, m, or h. Fractional and compound durations are invalid.

Root

schema_version = 1
default_connection = "local"

[cli]
format = "human"
non_interactive = false

[licensing]
token_env = "VARC_CLI_TOKEN"

Field	Type	Required/default	Meaning
schema_version	integer	required	Must equal 1.
default_connection	string	unset	Connection selected when no higher-precedence selector applies.
cli	table	defaults	Output and interactivity defaults.
licensing	table	defaults	CLI Token and licensing-authority settings.
connections	table	{}	Named Redis-compatible connections.
benchmarks	table	{}	Named benchmark definitions.
migrations	table	{}	Named one-shot migrations.
scripts	table	{}	Named JavaScript or TypeScript scripts.
queries	table	{}	Named Redis-aware SQL files.

[cli]

Field	Type	Default	Values
format	string	human	human or json.
non_interactive	boolean	false	Refuse prompts.

--format overrides the file. --non-interactive and the file setting combine as logical OR.

[licensing]

Field	Type	Default	Meaning
token_env	string	VARC_CLI_TOKEN	Environment variable containing the CLI Token.
authority_url	string	build service	Absolute HTTP(S) licensing-authority base URL.

Environment names start with an ASCII letter or underscore and continue with ASCII letters, digits, or underscores. Put the variable name here, never the token itself.

Connections

[connections.local]
url_env = "REDIS_URL"
topology = "standalone"
protocol = "resp3"
read_mode = "read_write"
connect_timeout_ms = 5000
command_timeout_ms = 10000

[connections.<name>]

Field	Type	Default	Meaning
url	string	unset	Primary Redis-compatible URL.
url_env	string	unset	Environment variable containing the URL.
topology	string	standalone	standalone, cluster, or sentinel.
seeds	string array	[]	Additional Cluster seed or Sentinel URLs.
sentinel_master	string	unset	Required Sentinel master/service name.
database	integer	URL or 0	Non-negative; Cluster requires 0.
username	string	URL value	Redis ACL username.
password	string	URL value	Literal Redis password; environment is preferred.
password_env	string	unset	Redis password environment variable.
sentinel_username	string	unset	Sentinel control-plane ACL username.
sentinel_password	string	unset	Literal Sentinel password.
sentinel_password_env	string	unset	Sentinel password environment variable.
protocol	string	resp3	resp2 or resp3.
read_mode	string	read_write	read_write or read_only.
ca_cert	path	system roots	Custom TLS CA certificate.
client_cert	path	unset	mTLS client certificate; requires client_key.
client_key	path	unset	mTLS private key; requires client_cert.
skip_verify	boolean	false	Disable TLS certificate verification.
tls_server_name	string	URL host	Override the TLS server name.
connect_timeout_ms	integer	client default	Positive connection timeout.
command_timeout_ms	integer	client default	Positive response timeout.

Accepted schemes are redis://, rediss://, valkey://, and valkeys://. Dragonfly normally uses a Redis scheme. The default port is 6379. A URL path may contain one numeric database. Queries, fragments, and multi-segment paths are rejected.

The primary URL is selected from --url, --url-env, connection url_env, exactly one populated REDIS_URL/VALKEY_URL/DRAGONFLY_URL, then connection url. Multiple automatic variables are ambiguous.

Connection names resolve from --connection, the current benchmark, script, or query’s connection, VARC_CONNECTION, default_connection, the sole configured connection, or an implicit connection from URL discovery.

Topology rules:

• Standalone forbids additional seeds.
• Cluster accepts several seeds and requires database 0.
• Sentinel requires sentinel_master; its endpoints are control-plane nodes.
• Every endpoint must use the same TLS mode. Seed URLs cannot select a database or contain conflicting credentials.
• TLS settings require rediss:// or valkeys://.
• client_cert and client_key must appear together.

Benchmarks

Each [benchmarks.<name>] has execution policy and exactly one nested workload.

Field	Type	Required/default	Meaning
connection	string	connection selection	Named connection.
database	integer	connection DB or 0	Non-negative; Cluster requires 0.
clients_per_runner	integer	1	1 through the effective licensed/native limit.
pipeline	integer	1	Commands per pipeline, 1–1000.
requests	integer	one termination	Positive global request count.
duration	string	one termination	Positive duration; excludes requests.
rate_per_second	integer	unlimited	Positive global rate.
seed_keys	integer	unset	Pre-seed 1–10,000,000 namespaced string keys.
warmup	duration	unset	Warmup phase.
ramp	duration	unset	Ramp-up phase.
cooldown	duration	unset	Cooldown phase.
seed	integer	1	Deterministic generator seed.
key_prefix	string	varc-benchmark:	UTF-8 prefix, at most 1,024 bytes.
record_debug_traffic	boolean	false	Deprecated compatibility field; only false is accepted. Debug is external-client-only.
workload	table	required	preset, weighted, or artifact.
safety	table	defaults	Write and production acknowledgements.
assertions	table	defaults	Final pass/fail gates.
outputs	table	defaults	Optional report files.
distributed	table	unset	Multi-process execution.

Set exactly one of requests or duration. Request count, rate, seeding, phases, and assertions are global in a distributed run; clients are per runner.

Preset workload

[benchmarks.reads.workload]
type = "preset"
preset = "get_only"

preset is one of get_only, set_only, mixed_50_50, read_heavy, write_heavy, realistic_cache, realistic_session, pipeline, high_concurrency, or large_payload. Only get_only is classified as read-only. Presets never imply seeding.

Weighted workload

[benchmarks.session_mix.workload]
type = "weighted"
key_space = 100000
key_distribution = { type = "zipfian", exponent = 0.99 }
value_distribution = { type = "compressible", bytes = 512 }

[[benchmarks.session_mix.workload.operations]]
label = "read-session"
weight = 9
command = "HGET"
args = [
  { type = "key" },
  { type = "literal", text = "payload" },
]

Field	Type	Constraint
type	string	Must be weighted.
key_space	integer	Positive generated-key cardinality.
key_distribution	tagged table	Required key-selection shape.
value_distribution	tagged table	Required value shape.
operations	table array	1–1,000 command templates.

Key distributions are sequential, uniform, gaussian, and zipfian. Zipfian exponent is finite and within (0, 4].

Value distributions are:

value_distribution = { type = "random", bytes = 256 }
value_distribution = { type = "compressible", bytes = 256 }
value_distribution = { type = "fixed", value = { text = "value" } }

Generated and fixed values cannot exceed 1 MiB. Fixed values and literal arguments set exactly one binary-safe encoding:

{ text = "plain UTF-8" }
{ hex = "00ff10" }
{ base64 = "AP8Q" }

Hex requires an even number of digits. Base64 uses the standard alphabet.

Each operation has a 1–128 byte label, positive u32 weight, non-empty command, and ordered args. Total weights cannot exceed u32. Arguments are key, value, sequence, or literal. Commands pass a conservative policy that denies authentication, protocol control, subscription, blocking, scripting, administrative, and other unsafe command classes.

Artifact workload

[benchmarks.captured.workload]
type = "artifact"
path = "captured.varc-workload.jsonl"
speed = 1.0
iterations = 1
exact_data_acknowledged = true
incomplete_trace_acknowledged = true

Field	Default	Constraint
type	required	artifact.
path	required	Versioned .varc-workload.jsonl.
speed	1.0	Exact-trace speed in (0, 100].
iterations	1	Positive repeat count.
exact_data_acknowledged	false	Required for traces retaining original data.
incomplete_trace_acknowledged	false	Required when incomplete reasons exist.

Validation checks schema, order, digest, tagged bytes, command policy, and acknowledgements. Native caps are 100,000 trace commands and 32 MiB of command and argument bytes.

Benchmark safety

[benchmarks.<name>.safety] contains:

Field	Default	Meaning
allow_writes	false	Must be true when the workload may write.
environment	unset	Operator environment label.
acknowledgement	unset	Must exactly equal prod or production environment labels.

Benchmark assertions

[benchmarks.<name>.assertions] accepts non-negative max_error_rate, max_p50_ms, max_p95_ms, max_p99_ms, and integer min_requests. Latency and error-rate values must be finite. Assertions apply to the final local or merged report.

Benchmark outputs

[benchmarks.<name>.outputs] accepts json, jsonl, and junit paths. replace defaults to false. These files do not change the final stdout result.

Distributed settings

Field	Required/default	Constraint
runners	required	2–1024.
run_id	unset	Shared non-secret ID, 1–128 bytes without NUL.
run_id_env	unset	Environment variable containing the run ID.
join_timeout	10m	Positive.
prepare_timeout	10m	Positive.
start_delay	10s	At least 2ms.
report_timeout	10m	Positive.

The run ID resolves from --run-id, populated run_id_env, then run_id. --distributed COUNT overrides runners; --single disables distribution for one invocation.

Scripts

Each [scripts.<name>] points to one JavaScript or TypeScript source file and defines its target and explicitly granted host inputs.

[scripts.inspect]
path = "scripts/inspect.ts"
connection = "local"
database = 0
language = "typescript"
timeout = "5s"
fetch = false

[scripts.inspect.environment]
TENANT = "CI_TENANT"

Field	Type	Required/default	Meaning
path	path	required	Source path relative to the containing varc.toml.
connection	string	connection selection	Named Redis-compatible connection.
database	integer	connection DB or 0	Non-negative; Cluster requires 0.
language	string	inferred from path	javascript or typescript.
timeout	string	5s	Execution deadline from 1ms through 30s.
fetch	boolean	false	Grant bounded outbound HTTP/HTTPS access.
environment	table	{}	Script variable names mapped to process variable names.

Language inference recognizes .js, .mjs, .cjs, .ts, .mts, and .cts. A path with another extension requires language. Source must be UTF-8 and cannot exceed 1 MiB.

Environment mappings use SCRIPT_NAME = "PROCESS_NAME". Both names must be 1–64 characters, start with an uppercase ASCII letter, and contain only uppercase ASCII letters, digits, or underscores. Configuration and script validation check the names but do not read the mapped values. Script execution requires every mapped process variable to exist; empty values remain present.

Invocation flags override a named definition without editing it:

Flag	Effect
--language LANGUAGE	Override or supply the source language.
--database DATABASE	Override the selected logical database.
--timeout DURATION	Override the bounded execution deadline.
--allow-fetch	Grant fetch for this invocation.
--deny-fetch	Remove the named definition’s fetch grant.
--env NAME=SOURCE_ENV	Add or replace one environment mapping; repeatable.

Named execution uses the script’s connection after a global --connection override and before shared defaults. Direct --file and --stdin sources use global target selection. --file, --stdin, and a script name are mutually exclusive; stdin requires --language.

SQL queries

Each [queries.<name>] points to one Redis-aware SQL source file and may select its default target.

[queries.expire_sessions]
path = "queries/expire-sessions.sql"
connection = "local"
database = 0

Field	Type	Required/default	Meaning
path	path	required	SQL path relative to the containing varc.toml.
connection	string	connection selection	Named Redis-compatible connection.
database	integer	connection DB or 0	Non-negative; Cluster requires 0.

The file must contain exactly one UTF-8 SELECT, UPDATE, EXPLAIN SELECT, or EXPLAIN UPDATE statement and cannot exceed 1 MiB. A global --connection overrides the definition’s connection; command --database overrides its database. Direct --file paths resolve from the working directory rather than from varc.toml.

Migrations

Every [migrations.<name>] has its own schema_version = 1. The mode controls which endpoints and bundle fields are legal.

Migration root fields

Field	Required/default	Meaning
schema_version	required	Exactly 1.
mode	required	live_copy, bundle_export, or bundle_import.
source	by mode	Named connection for copy/export.
destination	by mode	Named connection for copy/import.
source_database	connection DB	Non-negative; forbidden on import.
destination_database	connection DB	Non-negative; forbidden on export.
bundle_path	by mode	Required for export/import; forbidden for copy.
overwrite	refuse	Export: refuse or replace_validated_regular_file.
estimated_uncompressed_bytes	unset	Export disk-size estimate.
minimum_free_after_export_bytes	0	Export free-space reserve.
source_labels	[]	Up to 32 printable export labels, 1–128 bytes each.
policy	defaults	Conflict, expiry, verification, and compatibility policy.
scope	all keys	Key-type and matcher filter.
execution	defaults	Throughput and timeout.
safety	defaults	Named risk acknowledgements.
output	defaults	Progress, problems, and checkpoint files.

The same named connection can be source and destination only when effective databases differ. Cluster databases must be 0.

Mode rules:

Mode	Required	Forbidden
live_copy	source, destination	Bundle and export-only fields.
bundle_export	source, bundle_path	Destination, policy, checkpoint, clock-skew acknowledgement.
bundle_import	bundle_path, destination	Source, export-only fields, raw-export acknowledgement.

Migration policy

Live copy and bundle import accept:

Field	Default	Values
conflict	stop	stop, skip, replace.
expiration	keep_expiry_time	keep_expiry_time, restart_captured_ttl.
verification	quick	quick, none.
allow_compatibility_skips	false	Accept classified compatibility skips.

Failed writes and verification failures are incomplete. Compatibility skips remain incomplete unless explicitly accepted.

Migration scope

[migrations.<name>.scope] accepts one key_type and one matcher, combined with AND semantics. Key types are string, list, set, zset, hash, stream, json, time_series, bloom, cuckoo, count_min_sketch, top_k, t_digest, vector_set, and array.

matcher = { kind = "prefix", encoding = "text", value = "tenant:" }
matcher = { kind = "suffix", encoding = "hex", value = "00ff" }
matcher = { kind = "glob", encoding = "base64", value = "dGVuYW50Oio=" }
matcher = { kind = "regex", pattern = "^tenant:\\x00[0-9]+$" }

Binary matchers decode to 1–65,536 bytes and use text, even-length hex, or standard padded/unpadded base64. Regex patterns are limited to 4,096 Unicode scalar values and compile before connecting. Database selection is not scope.

Migration execution and safety

[migrations.<name>.execution] accepts positive max_keys_per_second and a positive timeout no greater than 24 hours; timeout defaults to 24h.

[migrations.<name>.safety] contains clock_skew_acknowledged for live/import and raw_export_acknowledged for export. Both default to false.

Migration output

Field	Default	Meaning
progress	auto	auto, tty, plain, jsonl, or none.
progress_interval	10s	1s through 1h.
progress_file	unset	Versioned progress JSONL.
problems_file	unset	Bounded binary-safe problem JSONL.
checkpoint_file	unset	Bundle import checkpoint JSON.
replace	false	Replace validated regular files; symlinks are refused.

progress_file conflicts with progress = "none". Problem output never contains values or DUMP payloads. Output parent directories must exist.

Validate and inspect

varc config validate
varc config show
varc doctor
varc benchmark validate NAME
varc script validate NAME
varc sql validate NAME

config validate proves strict parsing, names, versions, and migration invariants. benchmark validate additionally adapts the workload and reads its artifact. script validate reads and transpiles source without resolving environment values, licensing, connecting, or enabling network access. sql validate reads and prepares SQL without resolving a connection. Live connection validation happens when a command resolves or opens the selected connection.