.env.example

# The sync server (`cargo run --release --bin server`) reads these. A `.env`
# in the working directory is read first; variables already set win.

# Where to listen, and the path prefix the sync client connects under
# (the client's `server` option ends in this prefix).
STREAMGRES_ADDR=0.0.0.0:4848
STREAMGRES_BASE_PATH=/sync

# The database: the user needs replication rights and read access to every
# published table.
STREAMGRES_PG_DSN=postgresql://postgres:postgres@localhost:5432/xyne_dev_db
# Writable primary for schema, publication and DDL trigger setup at startup.
STREAMGRES_MASTER_PG_DSN=postgresql://postgres:postgres@localhost:5432/xyne_dev_db
# Optional read endpoint. Keep the direct DSN above for the change feed and
# snapshot minting. Change this host/port to PgBouncer to pool SQL reads; it
# must route to the same PostgreSQL database. Defaults to the direct DSN.
STREAMGRES_READ_PG_DSN=postgresql://postgres:postgres@localhost:5432/xyne_dev_db
# Schemas whose tables the catalog carries; default: public and <app>_<shard>.
# STREAMGRES_SCHEMAS=public,streamgres_0
# The publication the change feed streams. Startup creates it for every
# STREAMGRES_SCHEMAS schema if absent and validates it if present.
# The replication slot is not configured: each server process creates its
# own using the existing compatible naming scheme.
STREAMGRES_PUBLICATION=streamgres_sync_pub
# Startup creates or validates the DDL triggers; their names and WAL message
# prefix come from STREAMGRES_APP_ID and STREAMGRES_SHARD.
# How often a fresh exported snapshot (a temporary slot) is minted for reads.
STREAMGRES_SNAPSHOT_ROTATION_MS=1000
# Drop ended processes' inactive permanent feed slots after this age. 0
# disables cleanup (the default). Enabling it needs PostgreSQL 17+, which
# exposes the inactive_since timestamp required to clean safely.
STREAMGRES_SLOT_CLEANUP_AGE_MS=0
# How many storage reads may hold a Postgres connection at once; the rest queue.
STREAMGRES_READ_CONNECTIONS=16
# Maximum Streamgres-to-database/PgBouncer client connections kept idle for reuse.
# Set to 0 to close each read connection after use.
STREAMGRES_READ_IDLE_CONNECTIONS=16
# How long one storage read may take (its connection opening included, the
# wait for a free connection not). PostgreSQL cancels the statement at that
# point and the server stops waiting; the query that needed the read is
# refused by name instead of being read again. 0 sets no limit.
STREAMGRES_READ_TIMEOUT_MS=10000
# TCP keepalive on every connection to the database: after this long without
# a byte either way the kernel probes the peer, so a NAT or a load balancer
# between does not drop the connection as idle. The temporary slot behind each
# read snapshot lives on an otherwise silent connection, and the snapshot dies
# with it. 0 turns the probing off.
STREAMGRES_PG_KEEPALIVE_IDLE_MS=30000
# After an unanswered probe, how long until the next one.
STREAMGRES_PG_KEEPALIVE_INTERVAL_MS=10000
# How many unanswered probes in a row before the kernel gives the connection up.
STREAMGRES_PG_KEEPALIVE_RETRIES=3
# The most rows the server reads into memory at once, one number for the
# planner and the storage: the planner reads whole no side of a join past it
# (an INNER edge is driven from the side that fits, the query is refused when
# neither does), and a storage read returning more is refused and the queries
# depending on it are told so (a query without a LIMIT over a large table
# would otherwise be buffered whole). The older names XYNE_SYNC_JOIN_LIMIT and
# XYNE_SYNC_READ_ROW_LIMIT are still read.
STREAMGRES_ROW_LIMIT=100000
# How many threads run the storage reads (their SQL, connections and row
# decoding); the planner's counts and connect-time reads run there too.
STREAMGRES_READ_THREADS=2
# How many threads keep the client groups' views and build their pokes; each
# owns the groups that hash to it. One is enough for a few thousand groups;
# more spreads the fan-out over more cores.
STREAMGRES_GROUP_THREADS=1
# Which side of an INNER edge drives it when reading the node whole and
# having its subs drive it would hold the same rows (the plan holding fewer
# wins otherwise: the subs drive when they cut the node down by more than
# they cost, so the leaves of an access rule drive the page they narrow, and
# a row fetched by id drives the rule outwards): parent (the node's own rows;
# the child is then read narrowed to the node's join values) or child (the
# subquery, as whereExists is translated).
STREAMGRES_JOIN_PREFERRED_SIDE=parent
# How long a join plan is remembered for its query tree before the tree is
# sized again, and how many plans are remembered at most (least recently
# used out).
STREAMGRES_PLAN_TTL_MS=600000
STREAMGRES_PLAN_CACHE=10000
# How long the planner's estimates (each EXPLAIN by its text, each join
# column's statistics) are remembered, and how many at most; a table's are
# also dropped when its reltuples/relpages change. 0 keeps none.
STREAMGRES_ESTIMATE_TTL_MS=86400000
STREAMGRES_ESTIMATE_CACHE=300000
# How long the application server's transform of a query (its AST) is kept
# per identity, so a shape asked for again does not pay the round trip, and
# how many are kept at most; 0 keeps none. A minute is the default: a deploy
# that changes a query's shape reaches clients within one. The reference
# server keeps its own for five seconds, which on the rig made a hydration
# about 8 ms slower at the median (twice the calls to the backend, each
# slower).
STREAMGRES_TRANSFORM_TTL_MS=60000
STREAMGRES_TRANSFORM_CACHE=20000
# A warm start: the query shapes asked for are kept in this file (written
# every minute and on shutdown) and planned again, for at most
# WARM_START_MS, before the next process reports ready; unset to keep none.
# STREAMGRES_PLAN_FILE=/var/lib/streamgres/plans.json
STREAMGRES_WARM_START_MS=20000
# Tables to mirror in memory instead of reading from Postgres (optional).
# STREAMGRES_MEMORY_TABLES=

# The application server: query names to ASTs, and mutations.
STREAMGRES_QUERY_URL=http://localhost:3001/api/sync/query
STREAMGRES_MUTATE_URL=http://localhost:3001/api/sync/push
STREAMGRES_FORWARD_COOKIES=true
# How long one call to the application server (a transform, a push) may take
# before it is given up; a call that timed out is not made again. 0 sets no
# limit.
STREAMGRES_BACKEND_TIMEOUT_MS=30000
# The application id and shard: together they name the schema the
# application server records mutations in (<app>_<shard>.clients).
STREAMGRES_APP_ID=streamgres
STREAMGRES_SHARD=0

# The connection protocol. A `pong` answers every `ping`; when nothing has
# gone downstream for PONG_INTERVAL a `pong` goes out anyway; a WebSocket ping
# frame goes out every PING_INTERVAL; a connection silent for CLIENT_TIMEOUT
# is closed; a client group's subscriptions and its record of the rows it
# was sent outlive its last connection by GROUP_TTL (the default is a
# minute; an hour here), so a client back within it is caught up with what
# changed instead of downloading everything again: while no connection of
# the group is open its changes wait, coalesced, and its version stands
# still, so the cookie the client left with still fits. A client that
# returns behind its group (its socket died unnoticed while the server
# went on sending, or another tab kept the group moving) is sent the pokes
# it missed from the group's log: every poke sent is kept, the oldest
# dropped once they pass GROUP_LOG_BYTES per group (0 keeps none, and such
# a client starts over). All of
# it lives in memory: a restart of the server still starts every client
# afresh.
STREAMGRES_PONG_INTERVAL_MS=3000
STREAMGRES_PING_INTERVAL_MS=30000
STREAMGRES_CLIENT_TIMEOUT_MS=45000
STREAMGRES_GROUP_TTL_MS=3600000
STREAMGRES_GROUP_LOG_BYTES=262144
STREAMGRES_MAX_MESSAGE_BYTES=16777216

# Whether /stats and /metrics are served on the public port. False by
# default: the endpoints carry no auth, and /stats?reset=1 zeroes the
# histograms any client can reach. Enable only where the port is trusted,
# or push metrics over OTLP instead.
# STREAMGRES_ENABLE_ADMIN_ENDPOINTS=true
STREAMGRES_BYTES_PER_PART=768000

# error, warn, info or debug; text or json lines. Lines are written by a
# thread of their own from a bounded queue, so logging never waits.
STREAMGRES_LOG=info
STREAMGRES_LOG_FORMAT=text
# Prefix used by all exported metric names. The default preserves existing
# dashboards; set to `streamgres` to emit `streamgres_*` series.
STREAMGRES_METRICS_PREFIX=xyne_sync
# A query hydrating slower than this, or a push slower than this, is logged
# at warn with its name and timings.
STREAMGRES_SLOW_QUERY_MS=1000
# How often the metrics thread samples the process (resident set, CPU per
# thread, the caches); the summary log line goes out every sixth sample
# and /metrics serves everything in Prometheus format. 0 turns it off.
STREAMGRES_METRICS_INTERVAL_MS=10000

# The push to an OpenTelemetry collector, configured by the standard
# OTEL_* variables (docs/observability.md section 5 has them
# all). Unset, nothing is pushed; /metrics and the log on stderr are always
# there. This is the block the sandbox gives the reference server: metrics every five
# seconds over OTLP/HTTP as JSON, logs left to stderr, no traces.
# OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
# OTEL_EXPORTER_OTLP_PROTOCOL=http/json
# OTEL_METRICS_EXPORTER=otlp
# OTEL_LOGS_EXPORTER=none
# OTEL_TRACES_EXPORTER=none
# OTEL_METRIC_EXPORT_INTERVAL=5000
# OTEL_SERVICE_NAME=streamgres

# Continuous CPU and heap profiles pushed to Pyroscope
# (docs/observability.md section 8). Unset, nothing is installed. The rate is samples per second
# of CPU time; user and password are Grafana Cloud's basic authentication.
# STREAMGRES_PYROSCOPE_URL=http://localhost:4040
# STREAMGRES_PYROSCOPE_APPLICATION=streamgres
# STREAMGRES_PYROSCOPE_SAMPLE_RATE=100
# STREAMGRES_PYROSCOPE_USER=
# STREAMGRES_PYROSCOPE_PASSWORD=
# STREAMGRES_PYROSCOPE_TENANT=
# STREAMGRES_PYROSCOPE_HEAP=true
# STREAMGRES_PYROSCOPE_TAGS=env=sandbox