Reference

Configuration loading order

Proxy accepts configuration from a TOML file, environment variables, or both.

1. If cipherstash-proxy.toml exists in the current working directory, Proxy reads it first.
2. Proxy then reads any environment variables that are set.
3. When both are present, environment variables override values from the TOML file.

Config options

[server]

[database]

[tls]

Configure TLS for client-to-proxy connections. Provide either file paths or inline PEM strings.

[auth]

[encrypt]

[log]

[prometheus]

Full TOML example

[server]
host = "0.0.0.0"
port = "6432"
require_tls = "false"
shutdown_timeout = "2000"
worker_threads = "4"
thread_stack_size = "2097152"
cipher_cache_size = "64"
cipher_cache_ttl_seconds = "3600"

[database]
host = "0.0.0.0"
port = "5432"
name = "database"
username = "username"
password = "password"
connection_timeout = "300000"
with_tls_verification = "false"
config_reload_interval = "60"
schema_reload_interval = "60"

[tls]
certificate_path = "./server.crt"
private_key_path = "./server.key"

[auth]
workspace_crn = "cipherstash-workspace-crn"
client_access_key = "cipherstash-client-access-key"

[encrypt]
default_keyset_id = "cipherstash-dataset-id"
client_id = "cipherstash-client-id"
client_key = "cipherstash-client-key"

[log]
level = "info"
format = "pretty"
output = "stdout"
ansi_enabled = "true"
slow_statements = "false"
slow_statement_min_duration_ms = "2000"
slow_db_response_min_duration_ms = "100"

[prometheus]
enabled = "false"
port = "9930"

Development settings

Default settings are tuned for production. When running Proxy locally, override these for a better development experience. None of these settings are appropriate for production.

Enable colored, human-readable logs:

CS_LOG__FORMAT="pretty"
CS_LOG__ANSI_ENABLED="true"

Reduce reload intervals when iterating on your schema:

CS_DATABASE__CONFIG_RELOAD_INTERVAL="10"
CS_DATABASE__SCHEMA_RELOAD_INTERVAL="10"

Slow query logging

Slow query logging helps you identify statements that take longer than expected. Enable it with:

CS_LOG__SLOW_STATEMENTS="true"

By default, any statement taking longer than 2000 ms is flagged. Tune the thresholds to match your latency expectations:

CS_LOG__SLOW_STATEMENT_MIN_DURATION_MS="500"   # statement total time
CS_LOG__SLOW_DB_RESPONSE_MIN_DURATION_MS="200" # database round-trip only

When a slow statement is detected, Proxy emits a structured log line at the SLOW_STATEMENTS target. With format = "pretty", it looks like:

WARN  slow_statement  duration_ms=620  query="SELECT * FROM users WHERE ..."

Use these log lines to identify queries that need indexes or to spot unexpectedly slow EQL operations. To isolate slow-statement output in production, set CS_LOG__SLOW_STATEMENTS_LEVEL=warn while keeping the global level at error.

Docker-specific options

These environment variables are only available in the Docker container image and are not present in the binary.

Per-target log levels

Override the log level for specific internal components using the pattern CS_LOG__{TARGET}_LEVEL. These environment variables accept the same values as CS_LOG__LEVEL.

CLI reference

cipherstash-proxy [OPTIONS] [DBNAME] [COMMAND]

Commands

Arguments and options

Prometheus metrics

Enable the Prometheus exporter by setting CS_PROMETHEUS__ENABLED=true. Metrics are exposed on port 9930 by default.

Supported architectures

CipherStash Proxy is available as a Docker container image for linux/arm64 architectures.