Sync service configuration
This page documents the config options for self-hosting the Electric sync engine.
Advanced only
You don't need to worry about this if you're using Electric Cloud.
Also, the only required configuration is DATABASE_URL
.
Configuration
The sync engine is an Elixir application developed at packages/sync-service and published as a Docker image at electricsql/electric.
Configuration options can be provided as environment variables, e.g.:
docker run \
-e "DATABASE_URL=postgresql://..." \
-e "ELECTRIC_DB_POOL_SIZE=10" \
-p 3000:3000 \
electricsql/electric
These are passed into the application via config/runtime.exs.
Database
DATABASE_URL
Variable | DATABASE_URL required |
Description | Postgres connection string. Used to connect to the Postgres database. The connection string must be in the libpg Connection URI format of The For a secure connection, set the |
Example | DATABASE_URL=postgresql://user:password@example.com:54321/electric |
ELECTRIC_DATABASE_USE_IPV6
Variable | ELECTRIC_DATABASE_USE_IPV6 |
Default | false |
Description | Set to |
Example | ELECTRIC_DATABASE_USE_IPV6=true |
ELECTRIC_DB_POOL_SIZE
Variable | ELECTRIC_DB_POOL_SIZE |
Default | 20 |
Description | How many connections Electric opens as a pool for handling shape queries. |
Example | ELECTRIC_DB_POOL_SIZE=10 |
ELECTRIC_REPLICATION_STREAM_ID
Variable | ELECTRIC_REPLICATION_STREAM_ID |
Default | default |
Description | Suffix for the logical replication publication and slot name. |
Example | ELECTRIC_REPLICATION_STREAM_ID=my-app |
Electric
ELECTRIC_INSTANCE_ID
Variable | ELECTRIC_INSTANCE_ID |
Default | Electric.Utils.uuid4() |
Description | A unique identifier for the Electric instance. Defaults to a randomly generated UUID. |
Example | ELECTRIC_INSTANCE_ID=some-unique-instance-identifier |
ELECTRIC_SERVICE_NAME
Variable | ELECTRIC_SERVICE_NAME |
Default | electric |
Description | Name of the electric service. Used as a resource identifier and namespace. |
Example | ELECTRIC_SERVICE_NAME=my-electric-service |
ELECTRIC_ENABLE_INTEGRATION_TESTING
Variable | ELECTRIC_ENABLE_INTEGRATION_TESTING |
Default | false |
Description | Expose some unsafe operations that faciliate integration testing. Do not enable this production. |
Example | ELECTRIC_ENABLE_INTEGRATION_TESTING=true |
ELECTRIC_LISTEN_ON_IPV6
Variable | ELECTRIC_LISTEN_ON_IPV6 |
Default | false |
Description | By default, Electric binds to IPv4. Enable this to listen on IPv6 addresses as well. |
Example | ELECTRIC_LISTEN_ON_IPV6=true |
ELECTRIC_LOG_CHUNK_BYTES_THRESHOLD
Variable | ELECTRIC_LOG_CHUNK_BYTES_THRESHOLD |
Default | 10485760 |
Description | Limit the maximum size of a shape log response, to ensure they are cached by upstream caches. Defaults to 10MB (10 * 1024 * 1024). See #1581 for context. |
Example | ELECTRIC_LOG_CHUNK_BYTES_THRESHOLD=20971520 |
ELECTRIC_LOG_OTP_REPORTS
Variable | ELECTRIC_LOG_OTP_REPORTS |
Default | false |
Description | Enable OTP SASL reporting at runtime. |
Example | ELECTRIC_LOG_OTP_REPORTS=true |
ELECTRIC_PORT
Variable | ELECTRIC_PORT |
Default | 3000 |
Description | Port that the HTTP API is exposed on. |
Example | ELECTRIC_PORT=8080 |
Caching
ELECTRIC_CACHE_MAX_AGE
Variable | ELECTRIC_CACHE_MAX_AGE |
Default | 60 |
Description | Default |
Example | ELECTRIC_CACHE_MAX_AGE=5 |
ElECTRIC_CACHE_STALE_AGE
Variable | ELECTRIC_CACHE_STALE_AGE |
Default | 300 |
Description | Default |
Example | ELECTRIC_CACHE_STALE_AGE=5 |
Storage
ELECTRIC_PERSISTENT_STATE
Variable | ELECTRIC_PERSISTENT_STATE |
Default | FILE |
Description | Where to store shape metadata. Defaults to storing on the filesystem. If provided must be one of |
Example | ELECTRIC_PERSISTENT_STATE=MEMORY |
ELECTRIC_STORAGE
Variable | ELECTRIC_STORAGE |
Default | FILE |
Description | Where to store shape logs. Defaults to storing on the filesystem. If provided must be one of |
Example | ELECTRIC_STORAGE=MEMORY |
ELECTRIC_STORAGE_DIR
Variable | ELECTRIC_STORAGE_DIR |
Default | ./persistent |
Description | Path to root folder for storing data on the filesystem. |
Example | ELECTRIC_STORAGE_DIR=/var/example |
Telemetry
ELECTRIC_OTLP_ENDPOINT
Variable | ELECTRIC_OTLP_ENDPOINT optional |
Description | Set an OpenTelemetry endpoint URL to enable telemetry. |
Example | ELECTRIC_OTLP_ENDPOINT=https://example.com |
ELECTRIC_OTEL_DEBUG
Variable | ELECTRIC_OTEL_DEBUG |
Default | false |
Description | Debug tracing by printing spans to stdout, without batching. |
Example | ELECTRIC_OTEL_DEBUG=true |
ELECTRIC_HNY_API_KEY
Variable | ELECTRIC_HNY_API_KEY optional |
Description | Honeycomb.io api key. Specify along with |
Example | ELECTRIC_HNY_API_KEY=your-api-key |
ELECTRIC_HNY_DATASET
Variable | ELECTRIC_HNY_DATASET optional |
Description | Name of your Honeycomb Dataset. |
Example | ELECTRIC_HNY_DATASET=your-dataset-name |
ELECTRIC_PROMETHEUS_PORT
Variable | ELECTRIC_PROMETHEUS_PORT optional |
Description | Expose a prometheus reporter for telemetry data on the specified port. |
Example | ELECTRIC_PROMETHEUS_PORT=9090 |
ELECTRIC_STATSD_HOST
Variable | ELECTRIC_STATSD_HOST optional |
Description | Enable sending telemetry data to a StatsD reporting endpoint. |
Example | ELECTRIC_STATSD_HOST=https://example.com |