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 options are DATABASE_URL
and ELECTRIC_SECRET
.
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_DATABASE_CA_CERTIFICATE_FILE
Variable | ELECTRIC_DATABASE_CA_CERTIFICATE_FILE optional |
Description | The path on local disk to a file containing trusted certificate(s) that Electric will use to verify the database server identity. Trusted certificates are those that have been signed by trusted certificate authorities (CA); they are also known as root certificates. Every operating system and most web browsers include a bundle of well-known root certificates (aka CA store). You can instruct Electric to use the default bundle provided by your OS by specifying an absolute path to it. This page from Neon lists the typical locations for different operating systems. Some managed Postgres providers such as Supabase and DigitalOcean use a self-signed root certificate that won't be found in OS-specific CA stores. If you're using one of those, download the trusted certificate from the provider's website and put it somewhere on your local disk where Electric can access it. Certificate verification and Electric doesn't support Note, however, that setting |
Example | ELECTRIC_DATABASE_CA_CERTIFICATE_FILE=/root/.postgresql/root.crt |
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_TCP_SEND_TIMEOUT
Variable | ELECTRIC_TCP_SEND_TIMEOUT |
Default | 30s |
Description | Timeout for sending a response chunk back to the client. Defaults to 30 seconds. Slow response processing on the client or bandwidth restristrictions can cause TCP backpressure leading to the error message:
This environment variable increases this timeout. |
Example | ELECTRIC_TCP_SEND_TIMEOUT=60s |
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 |