zero-cache Config

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

You can also see all available flags by running zero-cache --help.

Required Flags

Upstream DB

The "upstream" authoritative postgres database. In the future we will support other types of upstream besides PG.

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

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 next time it starts up.

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

Auth

One of Auth JWK, Auth JWK URL, or Auth Secret must be specified. See Authentication for more details.

Optional Flags

Push URL

The URL of the API server to which zero-cache will push mutations. Required if you use custom mutators.

flag: --push-url
env: ZERO_PUSH_URL
required: false

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

Note that this number must allow for at least one connection per sync worker, or zero-cache will fail to start. See num-sync-workers.

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

CVR DB

The Postgres database used to store CVRs. CVRs (client view records) keep track of the data synced to clients in order to determine the diff to send on reconnect. If unspecified, the upstream-db will be used.

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

CVR Max Connections

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

Note that this number must allow for at least one connection per sync worker, or zero-cache will fail to start. See num-sync-workers.

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

Change DB

The Postgres database used to store recent replication log entries, in order to sync multiple view-syncers without requiring multiple replication slots on the upstream database. If unspecified, the upstream-db will be used.

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

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: 5

Replica Vacuum Interval Hours

Performs a VACUUM at server startup if the specified number of hours has elapsed since the last VACUUM (or initial-sync). The VACUUM operation is heavyweight and requires double the size of the db in disk space. If unspecified, VACUUM operations are not performed.

flag: --replica-vacuum-interval-hours
env: ZERO_REPLICA_VACUUM_INTERVAL_HOURS
required: false

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

Use text for developer-friendly console logging and json for consumption by structured-logging services.

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. Port defaults to 4318 for most collectors.

flag: --log-trace-collector
env: ZERO_LOG_TRACE_COLLECTOR
required: false

Log Slow Row Threshold

The number of ms a row must take to fetch from table-source before it is considered slow.

flag: --log-slow-row-threshold
env: ZERO_LOG_SLOW_ROW_THRESHOLD
default: 2

Log Slow Hydrate Threshold

The number of milliseconds a query hydration must take to print a slow warning.

flag: --log-slow-hydrate-threshold
env: ZERO_LOG_SLOW_HYDRATE_THRESHOLD
default: 100

Log IVM Sampling

How often to collect IVM metrics. 1 out of N requests will be sampled where N is this value.

flag: --log-ivm-sampling
env: ZERO_LOG_IVM_SAMPLING
default: 5000

Target Client Row Count

A soft limit on the number of rows Zero will keep on the client. 20k is a good default value for most applications, and we do not recommend exceeding 100k. See Client Capacity Management for more details.

flag: --target-client-row-count
env: ZERO_TARGET_CLIENT_ROW_COUNT
default: 20000

App ID

Unique identifier for the app.

Multiple zero-cache apps can run on a single upstream database, each of which is isolated from the others, with its own permissions, sharding (future feature), and change/cvr databases.

The metadata of an app is stored in an upstream schema with the same name, e.g. zero, and the metadata for each app shard, e.g. client and mutation ids, is stored in the {app-id}_{#} schema. (Currently there is only a single "0" shard, but this will change with sharding).

The CVR and Change data are managed in schemas named {app-id}_{shard-num}/cvr and {app-id}_{shard-num}/cdc, respectively, allowing multiple apps and shards to share the same database instance (e.g. a Postgres "cluster") for CVR and Change management.

Due to constraints on replication slot names, an App ID may only consist of lower-case letters, numbers, and the underscore character.

Note that this option is used by both zero-cache and zero-deploy-permissions.

flag: --app-id
env: ZERO_APP_ID
default: zero

App Publications

Postgres PUBLICATIONs that define the tables and columns to replicate. Publication names may not begin with an underscore, as zero reserves that prefix for internal use.

If unspecified, zero-cache will create and use an internal publication that publishes all tables in the public schema, i.e.:

CREATE PUBLICATION _{app-id}_public_0 FOR TABLES IN SCHEMA public;

Note that once an app has begun syncing data, this list of publications cannot be changed, and zero-cache will refuse to start if a specified value differs from what was originally synced. To use a different set of publications, a new app should be created.

flag: --app-publications
env: ZERO_APP_PUBLICATIONS
default: []

Auth JWK

A public key in JWK format used to verify JWTs. Only one of jwk, jwksUrl and secret may be set.

flag: --auth-jwk
env: ZERO_AUTH_JWK
required: false

Auth JWK URL

A URL that returns a JWK set used to verify JWTs. Only one of jwk, jwksUrl and secret may be set.

flag: --auth-jwks-url
env: ZERO_AUTH_JWKS_URL
required: false

Auth Secret

A symmetric key used to verify JWTs. Only one of jwk, jwksUrl and secret may be set.

flag: --auth-secret
env: ZERO_AUTH_SECRET
required: false

Port

The port for sync connections.

flag: --port
env: ZERO_PORT
default: 4848

Change Streamer Port

The port on which the change-streamer runs. This is an internal protocol between the replication-manager and zero-cache, which runs in the same process in local development. If unspecified, defaults to --port + 1.

flag: --change-streamer-port
env: ZERO_CHANGE_STREAMER_PORT
required: false

Task ID

Globally unique identifier for the zero-cache instance. Setting this to a platform specific task identifier can be useful for debugging. If unspecified, zero-cache will attempt to extract the TaskARN if run from within an AWS ECS container, and otherwise use a random string.

flag: --task-id
env: ZERO_TASK_ID
required: false

Per User Mutation Limit Max

The maximum mutations per user within the specified windowMs.

flag: --per-user-mutation-limit-max
env: ZERO_PER_USER_MUTATION_LIMIT_MAX
required: false

Per User Mutation Limit Window (ms)

The sliding window over which the perUserMutationLimitMax 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 this unset to use the maximum available parallelism. If set to 0, the server runs without sync workers, which is the configuration for running the replication-manager.

flag: --num-sync-workers
env: ZERO_NUM_SYNC_WORKERS
required: false

Change Streamer URI

When unset, the zero-cache runs its own replication-manager (i.e. change-streamer). In production, this should be set to the replication-manager URI, which runs a change-streamer on port 4849.

flag: --change-streamer-uri
env: ZERO_CHANGE_STREAMER_URI
required: false

Auto Reset

Automatically wipe and resync the replica when replication is halted. This situation can occur for configurations in which the upstream database provider prohibits event trigger creation, preventing the zero-cache from being able to correctly replicate schema changes. For such configurations, an upstream schema change will instead result in halting replication with an error indicating that the replica needs to be reset. When auto-reset is enabled, zero-cache will respond to such situations by shutting down, and when restarted, resetting the replica and all synced clients. This is a heavy-weight operation and can result in user-visible slowness or downtime if compute resources are scarce.

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

Query Hydration Stats

Track and log the number of rows considered by each query in the system. This is useful for debugging and performance tuning.

flag: --query-hydration-stats
env: ZERO_QUERY_HYDRATION_STATS
required: false

Litestream Executable

Path to the litestream executable. This option has no effect if litestream-backup-url is unspecified.

flag: --litestream-executable
env: ZERO_LITESTREAM_EXECUTABLE
required: false

Litestream Config Path

Path to the litestream yaml config file. zero-cache will run this with its environment variables, which can be referenced in the file via ${ENV} substitution, for example:

ZERO_REPLICA_FILE for the db Path
ZERO_LITESTREAM_BACKUP_LOCATION for the db replica url
ZERO_LITESTREAM_LOG_LEVEL for the log Level
ZERO_LOG_FORMAT for the log type

flag: --litestream-config-path
env: ZERO_LITESTREAM_CONFIG_PATH
default: ./src/services/litestream/config.yml

Litestream Log Level

flag: --litestream-log-level
env: ZERO_LITESTREAM_LOG_LEVEL
default: warn values: debug, info, warn, error

Litestream Backup URL

The location of the litestream backup, usually an s3:// URL. If set, the litestream-executable must also be specified.

flag: --litestream-backup-url
env: ZERO_LITESTREAM_BACKUP_URL
required: false

Litestream Checkpoint Threshold MB

The size of the WAL file at which to perform an SQlite checkpoint to apply the writes in the WAL to the main database file. Each checkpoint creates a new WAL segment file that will be backed up by litestream. Smaller thresholds may improve read performance, at the expense of creating more files to download when restoring the replica from the backup.

flag: --litestream-checkpoint-threshold-mb
env: ZERO_LITESTREAM_CHECKPOINT_THRESHOLD_MB
default: 40

Litestream Incremental Backup Interval Minutes

The interval between incremental backups of the replica. Shorter intervals reduce the amount of change history that needs to be replayed when catching up a new view-syncer, at the expense of increasing the number of files needed to download for the initial litestream restore.

flag: --litestream-incremental-backup-interval-minutes
env: ZERO_LITESTREAM_INCREMENTAL_BACKUP_INTERVAL_MINUTES
default: 15

Litestream Snapshot Backup Interval Hours

The interval between snapshot backups of the replica. Snapshot backups make a full copy of the database to a new litestream generation. This improves restore time at the expense of bandwidth. Applications with a large database and low write rate can increase this interval to reduce network usage for backups (litestream defaults to 24 hours).

flag: --litestream-snapshot-backup-interval-hours
env: ZERO_LITESTREAM_SNAPSHOT_BACKUP_INTERVAL_HOURS
default: 12

{
  /**
  * 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
      ZERO_CVR_DB: string
      ZERO_CHANGE_DB: string
      ...
    };
  }[];
}

flag: --tenants-json
env: ZERO_TENANTS_JSON
required: false

PreviousDeployment

NextReact

zero-cache Config

On this page