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_QUERY_DATABASE_URL
Variable | ELECTRIC_QUERY_DATABASE_URL |
Default | DATABASE_URL |
Description | Postgres connection string. Used to connect to the Postgres database for anything but the replication, will default to the same as The connection string must be in the libpg Connection URI format of The For a secure connection, set the |
Example | ELECTRIC_QUERY_DATABASE_URL=postgresql://user:password@example-pooled.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_SECRET
Variable | ELECTRIC_SECRET required |
Description | Secret for shape requests to the HTTP API. This is required unless |
Example | ELECTRIC_SECRET=1U6ItbhoQb4kGUU5wXBLbxvNf |
ELECTRIC_INSECURE
Variable | ELECTRIC_INSECURE |
Default | false |
Description | When set to |
Example | ELECTRIC_INSECURE=true |
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 in 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_SHAPE_CHUNK_BYTES_THRESHOLD
Variable | ELECTRIC_SHAPE_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_SHAPE_CHUNK_BYTES_THRESHOLD=20971520 |
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
These environment variables allow configuration of metric and trace export for visibility into performance of the Electric instance.
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 |
Logging
ELECTRIC_LOG_LEVEL
Variable | ELECTRIC_LOG_LEVEL optional |
Description | Verbosity of Electric's log output. Available levels, in the order of increasing verbosity:
|
Example | ELECTRIC_LOG_LEVEL=debug |
ELECTRIC_LOG_COLORS
Variable | ELECTRIC_LOG_COLORS optional |
Description | Enable or disable ANSI coloring of Electric's log output. By default, coloring is enabled when Electric's stdout is connected to a terminal. This may be undesirable in certain runtime environments, such as AWS which displays ANSI color codes using escape sequences and may incorrectly split log entries into multiple lines. |
Example | ELECTRIC_LOG_COLORS=false |
ELECTRIC_LOG_OTP_REPORTS
Variable | ELECTRIC_LOG_OTP_REPORTS |
Default | false |
Description | Enable OTP SASL reporting at runtime. |
Example | ELECTRIC_LOG_OTP_REPORTS=true |
Usage reporting
ELECTRIC_USAGE_REPORTING
These environment variables allow configuration of anonymous usage data reporting back to https://electric-sql.com
Variable | ELECTRIC_USAGE_REPORTING |
Default | true |
Description | Configure anonymous usage data about the instance being sent to a central checkpoint service. Collected information is anonymised and doesn't contain any information from the replicated data. You can read more about it in our telemetry docs. |
Example | ELECTRIC_USAGE_REPORTING=true |