Configuration options

When embedding Electric, the following options are available:

config :electric,
  connection_opts: nil
  # Database
  provided_database_id: "single_stack",
  db_pool_size: 20,
  replication_stream_id: "default",
  replication_slot_temporary?: false,
  # HTTP API
  service_port: 3000,
  allow_shape_deletion?: false,
  cache_max_age: 60,
  cache_stale_age: 300,
  chunk_bytes_threshold: 10485760,
  listen_on_ipv6?: false,
  # Storage
  storage_dir: "./persistent",
  storage: {Electric.ShapeCache.FileStorage, [storage_dir: "./persistent/shapes"]},
  persistent_kv: {Electric.PersistentKV.Filesystem, :new!, [root: "./persistent/state"]},
  # Telemetry
  instance_id: nil,
  telemetry_statsd_host: nil,
  prometheus_port: nil,
  call_home_telemetry?: false,
  telemetry_url: %URI{scheme: "https", userinfo: nil, host: "checkpoint.electric-sql.com", port: 443, path: nil, query: nil, fragment: nil},

Only the connection_opts are required.

Database

• replication_connection_opts - Required

  • :hostname (String.t/0) - Required. Server hostname

  • :port (integer/0) - Required. Server port

  • :database (String.t/0) - Required. Database

  • :username (String.t/0) - Required. Username

  • :password (function of arity 0) - Required. User password. To prevent leaking of the Pg password in logs and stack traces, you must wrap the password with a function. We provide Electric.Utils.obfuscate_password/1 which will return the connection_opts with a wrapped password value.

    config :electric, connection_opts: Electric.Utils.obfuscate_password(connection_opts)

  • :sslmode - Connection SSL configuration. See https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS The default value is :prefer.

  • :ipv6 (boolean/0) - Whether to use IPv6 for database connections The default value is false.

.

• query_connection_opts - Optional separate connection string that can use a pooler for non-replication queries (default: nil)

  • :hostname (String.t/0) - Required. Server hostname

  • :port (integer/0) - Required. Server port

  • :database (String.t/0) - Required. Database

  • :username (String.t/0) - Required. Username

  • :password (function of arity 0) - Required. User password. To prevent leaking of the Pg password in logs and stack traces, you must wrap the password with a function. We provide Electric.Utils.obfuscate_password/1 which will return the connection_opts with a wrapped password value.

    config :electric, connection_opts: Electric.Utils.obfuscate_password(connection_opts)

  • :sslmode - Connection SSL configuration. See https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-SSLMODE-STATEMENTS The default value is :prefer.

  • :ipv6 (boolean/0) - Whether to use IPv6 for database connections The default value is false.

.

• db_pool_size - How many connections Electric opens as a pool for handling shape queries (default: 20)
• replication_stream_id - Suffix for the logical replication publication and slot name (default: "default")

HTTP API

• service_port (integer/0) - Port that the HTTP API is exposed on (default: 3000)
• allow_shape_deletion? (boolean/0) - Whether to allow deletion of Shapes via the HTTP API (default: false)
• cache_max_age (integer/0) - Default max-age for the cache headers of the HTTP API in seconds (default: 60s)
• cache_stale_age (integer/0) - Default stale-age for the cache headers of the HTTP API in seconds (default: 300s)
• chunk_bytes_threshold (integer/0) - Limit the maximum size in bytes of a shape log response, to ensure they are cached by upstream caches. (default: 10485760 (10MiB)).
• listen_on_ipv6? (boolean/0) - Whether the HTTP API should listen on IPv6 as well as IPv4 (default: false)

Storage

• storage_dir (String.t/0) - Path to root folder for storing data on the filesystem (default: "./persistent")
• storage (Electric.ShapeCache.Storage.storage/0) - Where to store shape logs. Must be a 2-tuple of {module(), term()} where module points to an implementation of the Electric.ShapeCache.Storage behaviour. (default: {Electric.ShapeCache.FileStorage, [storage_dir: "./persistent/shapes"]})
• persistent_kv (Electric.PersistentKV.t/0) - A mfa that when called constructs an implementation of the Electric.PersistentKV behaviour, used to store system state (default: {Electric.PersistentKV.Filesystem, :new!, [root: "./persistent/state"]})

Telemetry

• instance_id (binary/0) - A unique identifier for the Electric instance. Set this to enable tracking of instance usage metrics across restarts, otherwise will be randomly generated at boot (default: a randomly generated UUID).
• telemetry_statsd_host (String.t/0) - If set, send telemetry data to the given StatsD reporting endpoint (default: nil)
• prometheus_port (integer/0) - If set, expose a prometheus reporter for telemetry data on the specified port (default: nil)
• call_home_telemetry? (boolean/0) - Allow anonymous usage data about the instance being sent to a central checkpoint service (default: true for production)
• telemetry_url (URI.t/0) - Where to send the usage data (default: %URI{scheme: "https", userinfo: nil, host: "checkpoint.electric-sql.com", port: 443, path: nil, query: nil, fragment: nil})

Deprecated

• provided_database_id (binary/0) - The provided database id is relevant if you had used v0.8 and want to keep the storage instead of having hanging files. We use a provided value as stack id, but nothing else.