Configuration

CipherStash Proxy is available as a container image on Docker Hub. Deploy it locally, as a cloud sidecar, or as a standalone binary. It speaks the PostgreSQL protocol, so your application connects to Proxy exactly the same way it connects to PostgreSQL.

Installing Proxy

The quickest way to run Proxy alongside your application is to add a container to your docker-compose.yml:

services:
  app:
    # Your app container config
  db:
    # Your Postgres container config
  proxy:
    image: cipherstash/proxy:latest
    container_name: proxy
    ports:
      - 6432:6432
      - 9930:9930
    environment:
      - CS_DATABASE__HOST=${CS_DATABASE__HOST}
      - CS_DATABASE__PORT=${CS_DATABASE__PORT}
      - CS_DATABASE__USERNAME=${CS_DATABASE__USERNAME}
      - CS_DATABASE__PASSWORD=${CS_DATABASE__PASSWORD}
      - CS_DATABASE__NAME=${CS_DATABASE__NAME}
      - CS_WORKSPACE_CRN=${CS_WORKSPACE_CRN}
      - CS_CLIENT_ACCESS_KEY=${CS_CLIENT_ACCESS_KEY}
      - CS_DEFAULT_KEYSET_ID=${CS_DEFAULT_KEYSET_ID}
      - CS_CLIENT_ID=${CS_CLIENT_ID}
      - CS_CLIENT_KEY=${CS_CLIENT_KEY}
      - CS_PROMETHEUS__ENABLED=${CS_PROMETHEUS__ENABLED:-true}

For a fully working example, see the docker-compose.yml in the Proxy repository.

Start the container, then connect your PostgreSQL client to Proxy on TCP 6432:

docker compose up

Setting up the database schema

Proxy queries encrypted data through EQL, which must be installed in the target database. Encrypted columns are typed with an EQL domain such as public.eql_v3_text_eq, and that type is what fixes the column's searchable capability. There is no database-side configuration table.

• Install EQL covers the install itself, including the permissions split and Supabase.
• Core concepts covers the variant model and which domain type to choose.
• Indexes covers adding functional indexes over the term extractors.

In development, the Proxy container can install EQL for you on startup:

CS_DATABASE__INSTALL_EQL=true

Check the installed version:

SELECT eql_v3.version();

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-keyset-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

Defaults 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 identifies statements that take longer than expected:

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 lines to find queries that need indexes. A query that is unexpectedly slow is usually missing a functional index over the term extractor, or is passing an untyped operand. See query performance.

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, not in the binary.

Per-target log levels

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

CLI reference

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

Commands

The encrypt command encrypts existing plaintext data in place. Follow the safeguards in Data migration before running it against populated production data.

Arguments and options

Prometheus metrics

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

Reloading configuration

When Proxy receives a SIGHUP, it reloads application-level configuration (database, auth, encrypt, log, prometheus, development) without disrupting active connections.

Network settings require a full restart: server.host, server.port, server.require_tls, server.worker_threads, and any tls configuration.

Supported architectures

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