CipherStash Proxy configurations


CipherStash Proxy is configured using a configuration file or environment variables.

The comnfiguration file uses the TOML format. The default path of the file is ./cipherstash-proxy.toml in the same directory as the executable. If using Docker, the file is mounted into the Docker container at /etc/cipherstash-proxy/cipherstash-proxy.toml.

Environment variables will overide the configuration values specified in the file.

Configuration options

This file contains the following settings.

SettingDescriptionDefaultEnvironment Variables
hostIP address the proxy listens on0.0.0.0CS_HOST
portPort number the proxy listens on6432CS_PORT
usernameUsername for proxy authenticationNone (Required)CS_USERNAME
passwordPassword for proxy authenticationNone (Required)CS_PASSWORD
workspace_idIdentifier for the workspace using the proxyNone (Required)CS_WORKSPACE_ID
client_access_keyAccess key for clients to authenticate with the proxyNone (Required)CS_CLIENT_ACCESS_KEY
encryption.modeEncryption mode; can be encrypted or passthroughpassthroughCS_ENCRYPTION__MODE
encryption.client_idClient ID for encryption, *required if mode is encryptedNone (*Required)CS_ENCRYPTION__CLIENT_ID
encryption.client_keyClient key for encryption, *required if mode is encryptedNone (*Required)CS_ENCRYPTION__CLIENT_KEY
audit.modeAudit mode; can be audit or passthroughpassthroughCS_AUDIT__MODE
audit.primary_key_injectionEnable/Disable primary key injectiontrueCS_AUDIT__PRIMARY_KEY_INJECTION
audit.max_primary_key_per_aggregateMax record count for aggregate keys10CS_AUDIT__MAX_PRIMARY_KEY_PER_AGGREGAE
prometheus_metricsEnable/Disable Prometheus metricsfalseCS_PROMETHEUS_METRICS
prometheus_portPort for Prometheus metrics9930CS_PROMETHEUS_PORT
use_dedicated_connectionEnable/Disable dedicated connections (for testing )falseCS_USE_DEDICATED_CONNECTION
pool_modeMode of connection pooling, Session or TransactionTransactionCS_POOL_MODE
pool_sizeMaximum number of connections in the pool20CS_POOL_SIZE
min_pool_sizeMinimum number of connections in the poolpool_size / 4 or 1CS_MIN_POOL_SIZE
log_ingest_endpointUpstream logging endpoint to send logs toNone (Optional)CS_LOG_INGEST_ENDPOINT
query_loggingEnable query loggingfalseCS_QUERY_LOGGING
unsafe_loggingEnable logging of sensitive informationfalseCS_UNSAFE_LOGGING
database.nameName of the upstream database being proxiedNone (Required)CS_DATABASE__NAME
database.hostIP address of the upstream database127.0.0.1CS_DATABASE__HOST
database.portPort number of the upstream5432CS_DATABASE__PORT
database.usernameUsername for the upstream database connectionNone (Required)CS_DATABASE__USERNAME
database.passwordPassword for the upstream database connectionNone (Optional)CS_DATABASE__PASSWORD


The addtional _ in the CS_ENCRYPTION_ and CS_DATABASE_ environment variables is intentional and is used to separate the nested configuration options.

CipherStash Credentials

Your workspace_id helps isolate projects and environments. The proxy requirews a client_access_key for the workspace in order to connect and authenticate.

For details on setting up credentials, see Getting started with CipherStash Proxy.

The encryption.client_id and encryption.client_key are only required if running the proxy with CipherStash Encrypt. See Getting started with CipherStash Encrypt.


The max_primary_key_per_aggregate setting is used to specify the maximum record count of an aggregate query for injecting primary keys.

Aggregate queries may reveal information about the underlying data, paticularly in cases where a small number of records are used in the calculation. If an aggregate query returns a number of records less than the max_primary_key_per_aggregate value, primary keys will be injected into the query.

The injection uses the array_agg PostgreSQL function. The performance impact on the database is neglible as the primary key is by definition indexed, and the referenced tables are already present in the SQL statement.

Example configuration file

1username = "proxy-user"
2password = "proxy-password"
4workspace_id = "12345678-1234-1234-1234-123456789012"
5client_access_key = "12345678-1234-1234-1234-123456789012"
8name = "stash"
9username = "postgres"
10password = "password"

Note - username and password appear twice. The proxy defines a username and password as the credentials that applications will use to connect to the proxy. The database credentials are required so the proxy can connect to the downstream database.

The url to connect to the proxy with this configuration is:


Extended Configuration

CipherStash Proxy is based on the excellent pgcat.

The --config-extended command line option enables the Proxy to be run using the full pgcat configuration. All of the pgcat features are available, with support for sharding, load balancing, failover and mirroring.

Running with extended configuration:

1cipherstash-proxy --config-extended pgcat.toml

Software Updates

Automated vs Manual Updates

CipherStash will publish regular updates to the CipherStash Proxy and will follow a standard release schedule. Customers can choose to update automatically or manually based on their operational requirements. It's recommended to stay up-to-date with the latest releases to benefit from new features and security patches.

The docker registry will be updated with the latest version of the CipherStash Proxy. Customers can pull the latest image and redeploy the container to update to the latest version.

Maintenance Effort

Routine updates require minimal effort from your team. Major updates may require review and testing to ensure compatibility with existing systems.

Log Configuration

All CipherStash Proxy containers log to both stderr and stdout. These logs can be configured to be stored locally on the server or can be integrated with existing log management tools using standard logging protocols. You have the flexibility to choose based on compliance and operational preferences.

Hardware Prerequisites

Instance Sizing

The CipherStash Proxy can run on a variety of hardware configurations, depending on the expected load and redundancy requirements. Performance benchmarks and traffic analysis should guide the decision-making process. The Proxy is designed to be lightweight and efficient, so it can run on modest hardware configurations.

Suggested minimum requirements

  • CPU: 0.5 vCPUs
  • Memory: 0.5 GB

Networking Prerequisites

Required Ports

By default, the CipherStash Proxy listens on port 6432, which is configurable. Ensure this port is open in your firewall settings to allow communication from your client applications to the CipherStah Proxy.

Routing Modifications

Ensure that routing configurations allow for uninterrupted communication between the Proxy and the PostgreSQL databases it manages. You may need to adjust routing rules to accommodate the Proxy's network requirements to communicate with the upstream databases.

Identity Prerequisites

Credential Requirements

Standard PostgreSQL credentials are used for authentication. Ensure that these credentials are securely managed and rotated regularly.

Optional Credentials

SSL/TLS certificates can be optionally configured for enhanced security during data transmission.

Monitoring/Ops Processes

Known Failure Scenarios

Common failure scenarios include network interruptions, misconfigured firewall rules, or authentication failures.

Monitoring Guidelines

Monitor connection counts, response times, and error rates to detect anomalies that may indicate operational issues. The CipherStash Proxy exposes Prometheus metrics that can be used for monitoring and alerting. Configure alerts based on these metrics to proactively address potential issues.

Shared Responsibilities

CipherStash is responsible for maintaining the software's integrity and providing updates. Customers are responsible for monitoring their instances and managing the containers securely.


Log Access

Logs are accessible within the Docker container and can be streamed to a centralized logging solution as configured.

Configuration Options

Logs verbosity can be adjusted via the configuration file. Customers can choose to log only essential information or enable detailed logging for troubleshooting purposes. Referer to the configuration file options above for available logging options.


Updating the Proxy

To update the Proxy, pull the latest Docker image from the repository and restart the container with the new image. CipherStash is committed to providing regular updates and security patches to ensure the Proxy's reliability and security and will ensure backward compatibility with existing configurations.

Notification of New Versions

Subscribe to release notifications via the console dashboard to stay informed about new versions.

Deployment of Upgrades

Deploy upgrades by redeploying the Docker container with the latest image. Ensure minimal downtime by testing in a staging environment before production deployment.

System Health Checks

Error Monitoring

Regularly check the health of the Proxy by monitoring logs for error messages and by checking the Docker container’s status. Set up alerts for critical errors to ensure timely resolution. Monitor the Prometheus metrics for performance and resource utilization.