zero-cache Config

zero-cache is configured either via CLI flag or environment variable. There is no separate zero.config file.

Upstream DB

The "upstream" authoritative Postgres database. In the future, we will support other types of upstream databases besides Postgres.

flag: --upstream-db
env: ZERO_UPSTREAM_DB
required: true

Upstream Max Connections

The maximum number of connections to open to the upstream database for committing mutations. This is divided evenly among sync workers. In addition, zero-cache uses one connection for the replication stream.

Note: The number must allow for at least one connection per sync worker, or zero-cache will fail to start. See --numSyncWorkers.

flag: --upstream-max-conns
env: ZERO_UPSTREAM_MAX_CONNS
default: 20

CVR DB

A separate Postgres database used to store CVRs (Client View Records). CVRs keep track of which clients have which data, enabling zero-cache to send the correct diff on reconnect. This can be the same database as the upstream DB but is typically a separate "database" within the same Postgres cluster.

flag: --cvr-db
env: ZERO_CVR_DB
required: true

CVR Max Connections

The maximum number of connections to open to the CVR database. This is divided evenly among sync workers.

Note: The number must allow for at least one connection per sync worker, or zero-cache will fail to start. See --numSyncWorkers.

flag: --cvr-max-conns
env: ZERO_CVR_MAX_CONNS
default: 30

Change DB

Another Postgres database used to store a replication log.

flag: --change-db
env: ZERO_CHANGE_DB
required: true

Change Max Connections

The maximum number of connections to open to the change database. This is used by the change-streamer for catching up zero-cache replication subscriptions.

flag: --change-max-conns
env: ZERO_CHANGE_MAX_CONNS
default: 1

Replica File

File path to the SQLite replica that zero-cache maintains. This can be lost, but if it is, zero-cache will have to re-replicate the next time it starts up.

flag: --replica-file
env: ZERO_REPLICA_FILE
required: true

Schema File

File path to the JSON schema file that defines the database structure and access control rules.

flag: --schema-file
env: ZERO_SCHEMA_FILE
default: "zero-schema.json"

Schema JSON

The JSON schema as a string, containing the same database structure and access control rules as would be in the schema file.

flag: --schema-json
env: ZERO_SCHEMA_JSON
optional: true

Log Level

Sets the logging level for the application.

flag: --log-level
env: ZERO_LOG_LEVEL
default: "info"
values: debug, info, warn, error

Log Format

Sets the log output format.

flag: --log-format
env: ZERO_LOG_FORMAT
default: "text"
values: text, json

Log Trace Collector

The URL of the trace collector to which to send trace data. Traces are sent over HTTP.

flag: --log-trace-collector
env: ZERO_LOG_TRACE_COLLECTOR
optional: true

Shard ID

Unique identifier for the zero-cache shard.

flag: --shard-id
env: ZERO_SHARD_ID
default: "0"

Shard Publications

Postgres PUBLICATIONs that define the partition of the upstream database replicated to the shard.

flag: --shard-publications
env: ZERO_SHARD_PUBLICATIONS
default: []

Port

The main port for client connections. Internally, zero-cache will also listen on the two ports after this one.

flag: --port
env: ZERO_PORT
default: 4848

Change Streamer Port

The port on which the change-streamer runs. Defaults to --port + 1 if unspecified.

flag: --change-streamer-port
env: ZERO_CHANGE_STREAMER_PORT
optional: true

Heartbeat Monitor Port

The port on which the heartbeat monitor listens for health checks. Defaults to --port + 2 if unspecified.

flag: --heartbeat-monitor-port
env: ZERO_HEARTBEAT_MONITOR_PORT
optional: true

JWT Secret

JWT secret for verifying authentication tokens.

flag: --jwt-secret
env: ZERO_JWT_SECRET
optional: true

Task ID

Globally unique identifier for the zero-cache instance.

flag: --task-id
env: ZERO_TASK_ID
optional: true

Per User Mutation Limit Max

The maximum mutations per user within the specified window.

flag: --per-user-mutation-limit-max
env: ZERO_PER_USER_MUTATION_LIMIT_MAX
optional: true

Per User Mutation Limit Window (ms)

The sliding window over which the mutation limit is enforced.

flag: --per-user-mutation-limit-window-ms
env: ZERO_PER_USER_MUTATION_LIMIT_WINDOW_MS
default: 60000

Number of Sync Workers

The number of processes to use for view syncing. Leave unset to use the maximum available parallelism.

flag: --num-sync-workers
env: ZERO_NUM_SYNC_WORKERS
optional: true

Change Streamer URI

URI of the change-streamer. Defaults to zero-cache's own replication-manager when unset.

flag: --change-streamer-uri
env: ZERO_CHANGE_STREAMER_URI
optional: true

Auto Reset

Automatically wipes and resyncs the replica when replication halts.

flag: --auto-reset
env: ZERO_AUTO_RESET
optional: true

Litestream

Indicates that a Litestream replicate process is backing up the replica file.

flag: --litestream
env: ZERO_LITESTREAM
optional: true

Storage DB Temp Dir

Temporary directory for IVM operator storage. Leave unset to use os.tmpdir().

flag: --storage-db-tmp-dir
env: ZERO_STORAGE_DB_TMP_DIR
optional: true

Tenants JSON

JSON encoding of per-tenant configs for running the server in multi-tenant mode:

Copy{                                                                                       
  /**                                                                                   
  * Requests to the main application port are dispatched to the first tenant           
  * with a matching host and path. If both host and path are specified,                
  * both must match for the request to be dispatched to that tenant.                   
  *                                                                                    
  * Requests can also be sent directly to the ZERO_PORT specified                      
  * in a tenant's env overrides. In this case, no host or path                         
  * matching is necessary.                                                             
  */                                                                                   
  tenants: {                                                                            
    id: string;     // value of the "tid" context key in debug logs                    
    host?: string;  // case-insensitive full Host: header match                        
    path?: string;  // first path component, with or without leading slash             
                                                                                        
    /**                                                                                
      * Options are inherited from the main application (e.g. args and ENV) by default, 
      * and are overridden by values in the tenant's env object.                        
      */                                                                                
    env: {                                                                             
      ZERO_REPLICA_DB_FILE: string                                                     
      ZERO_UPSTREAM_DB: string                                                         
      ...                                                                              
    };                                                                                 
  }[];                                                                                  
}                                                                                       

flag: --tenants-json
env: ZERO_TENANTS_JSON
optional: true