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

shell

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_URLrequired

Description

Postgres connection string. Used to connect to the Postgres database.

The connection string must be in the libpg Connection URI format of postgresql://[userspec@][hostspec][/dbname][?sslmode=<sslmode>].

The userspec section of the connection string specifies the database user that Electric connects to Postgres as. They must have the REPLICATION role.

For a secure connection, set the sslmode query parameter to require.

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 `DATABASE_URL` if not provided. The connection string must be in the libpg Connection URI format of `postgresql://[userspec@][hostspec][/dbname][?sslmode=<sslmode>]`. The `userspec` section of the connection string specifies the database user that Electric connects to Postgres as. This can point to a connection pooler and does not need a `REPLICATION` role as it does not handle the replication. For a secure connection, set the `sslmode` query parameter to `require`.
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 `true` to prioritise connecting to the database over IPv6. Electric will fall back to an IPv4 DNS lookup if the IPv6 lookup fails.
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 `ELECTRIC_INSECURE` is set to `true`. By default, the Electric API is public and authorises all shape requests against this secret. More details are available in the security guide.
Example	`ELECTRIC_SECRET=1U6ItbhoQb4kGUU5wXBLbxvNf`

ELECTRIC_INSECURE

Variable	`ELECTRIC_INSECURE`
Default	`false`
Description	When set to `true`, runs Electric in insecure mode and does not require an `ELECTRIC_SECRET`. Use with caution. API requests are unprotected and may risk exposing your database. Good for development environments. If used in production, make sure to lock down access to Electric.
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 `max-age` for the cache headers of the HTTP API.
Example	`ELECTRIC_CACHE_MAX_AGE=5`

ELECTRIC_CACHE_STALE_AGE

Variable	`ELECTRIC_CACHE_STALE_AGE`
Default	`300`
Description	Default `stale-age` for the cache headers of the HTTP API.
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 `MEMORY` or `FILE`.
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 `MEMORY` or `FILE`.
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 `HNY_DATASET` to export traces directly to Honeycomb, without the need to run an OpenTelemetry Collector.
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_LEVELoptional

Description

Verbosity of Electric's log output.

Available levels, in the order of increasing verbosity:

error
warning
info
debug

Example ELECTRIC_LOG_LEVEL=debug

ELECTRIC_LOG_COLORS

Variable ELECTRIC_LOG_COLORSoptional

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`

Sync service configuration ​

Configuration ​

Database ​

DATABASE_URL ​

ELECTRIC_QUERY_DATABASE_URL ​

ELECTRIC_DATABASE_USE_IPV6 ​

ELECTRIC_DB_POOL_SIZE ​

ELECTRIC_REPLICATION_STREAM_ID ​

Electric ​

ELECTRIC_SECRET ​

ELECTRIC_INSECURE ​

ELECTRIC_INSTANCE_ID ​

ELECTRIC_SERVICE_NAME ​

ELECTRIC_ENABLE_INTEGRATION_TESTING ​

ELECTRIC_LISTEN_ON_IPV6 ​

ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD ​

ELECTRIC_PORT ​

Caching ​

ELECTRIC_CACHE_MAX_AGE ​

ELECTRIC_CACHE_STALE_AGE ​

Storage ​

ELECTRIC_PERSISTENT_STATE ​

ELECTRIC_STORAGE ​

ELECTRIC_STORAGE_DIR ​

Telemetry ​

ELECTRIC_OTLP_ENDPOINT ​

ELECTRIC_OTEL_DEBUG ​

ELECTRIC_HNY_API_KEY ​

ELECTRIC_HNY_DATASET ​

ELECTRIC_PROMETHEUS_PORT ​

ELECTRIC_STATSD_HOST ​

Logging ​

ELECTRIC_LOG_LEVEL ​

ELECTRIC_LOG_COLORS ​

ELECTRIC_LOG_OTP_REPORTS ​

Usage reporting ​

ELECTRIC_USAGE_REPORTING ​

Sync service configuration

Configuration

Database

DATABASE_URL

ELECTRIC_QUERY_DATABASE_URL

ELECTRIC_DATABASE_USE_IPV6

ELECTRIC_DB_POOL_SIZE

ELECTRIC_REPLICATION_STREAM_ID

Electric

ELECTRIC_SECRET

ELECTRIC_INSECURE

ELECTRIC_INSTANCE_ID

ELECTRIC_SERVICE_NAME

ELECTRIC_ENABLE_INTEGRATION_TESTING

ELECTRIC_LISTEN_ON_IPV6

ELECTRIC_SHAPE_CHUNK_BYTES_THRESHOLD

ELECTRIC_PORT

Caching

ELECTRIC_CACHE_MAX_AGE

ELECTRIC_CACHE_STALE_AGE

Storage

ELECTRIC_PERSISTENT_STATE

ELECTRIC_STORAGE

ELECTRIC_STORAGE_DIR

Telemetry

ELECTRIC_OTLP_ENDPOINT

ELECTRIC_OTEL_DEBUG

ELECTRIC_HNY_API_KEY

ELECTRIC_HNY_DATASET

ELECTRIC_PROMETHEUS_PORT

ELECTRIC_STATSD_HOST

Logging

ELECTRIC_LOG_LEVEL

ELECTRIC_LOG_COLORS

ELECTRIC_LOG_OTP_REPORTS

Usage reporting

ELECTRIC_USAGE_REPORTING