Configuration

Configure your ElectricSQL application using the CLI tool and import the resulting configuration into your application code.

Workflow

The basic workflow is to:

  • electric init your application folder
  • electric build your config and migrations
  • import your built .electric/@config
  • pass to electrify(db, config)

Init

First initialise your application. If you haven’t already, make sure the CLI tool is installed. For example using Homebrew, or see the install guide for more options:

brew install electric-sql/tap/electric

Login on the command line:

electric auth login EMAIL

Note that if you’re running your own backend you can avoid logging in using the electric init APP --no-verify flag.

Make sure you’re in the root folder of your application and run (replacing APP with the app identifier from your sync service connection details):

electric init APP [--env ENV] [--migrations-dir PATH]

This creates an electric.json config file and initialises a migrations folder and an .electric output folder. The config file is shared by your application and the electric CLI tool. The migrations folder is the source folder where you write your migrations. The output folder is where the CLI tool builds your migrations and importable config files:

# config file -- edit the contents manually or
# via the `electric config` CLI command.
electric.json

# migrations source folder -- create new migrations
# using `electric migrations new` and then manually
# edit the generated `migration.sql` files here.
migrations/

# output folder -- DON'T edit the contents but DO
# import the build config and migrations into you
# application code from this folder, for example
# `import config from '.electric/@config'`
.electric/

Build

Build your config and migrations:

electric build [--env ENV]

This writes an importable Javascript module to .electric/:app/:env in your output folder.

Import

Import the built config into your application code. Either using the .electric/@config or .electric/@app/:env shortcuts, or using an explicit path:

// import the config for the `app` and `defaultEnv`
// configured in your `electric.json`
import config from '.electric/@config'

// or to override the env
import config from '.electric/@app/production'

// or using an explicit path
import config from '.electric/tarragon-envy-1234/staging'

We recommend using the .electric/@config shortcut as a starting point. If you need more control over which configuration is imported in your build process, you can use environment variables in combination with path aliases.

So for example, say you have two env vars set:

export ELECTRIC_APP="tarragon-envy-1234"
export ELECTRIC_ENV="staging"

Setup path aliases using process.env in your build config (in this example we’re using esbuild-plugin-alias-path syntax but there are equivalents for every build system):

const { ELECTRIC_APP, ELECTRIC_ENV } = process.env

aliasPath({
  alias: {
    '@electric/config': `.electric/${ELECTRIC_APP}/${ELECTRIC_ENV}`
  }
})

You can then import the built config using your preferred alias:

import config from '@electric/config'

Use

Pass the imported config to your electrify function when electrifying your database connection. See the driver docs for precise instructions but basically:

electrify(db, config)

Update

If you need to update your configuration you can either manually edit the electric.json config file. Or manage it using the electric config command.

For example to change app:

electric config update --app APP

Or to add a new env:

electric config add_env ENV [--set-as-default]

Always make sure to re-build your config after changing it:

electric build [--env ENV]

Options

app and env

ElectricSQL replicates data to and from a sync service. This service is identified by a globally unique app identifier and optional env. Copy these from the connection details shown in your ElectricSQL cloud console.

Every app is created with a default environment. If you don’t specify an env, this is the default that ElectricSQL will connect to. You can create additional services for different environments (staging, prod, test, etc.) and then connect to them by specifying the env name.

migrations

In order to work, ElectricSQL takes over the process of applying migrations to manage your database’s DDL schema. See the migrations guide for more information.

replication

By default, the ElectricSQL client connects to an ElectricSQL cloud sync service. If you’re running the backend yourself, you can configure the service to connect your local service.

For example, to connect to the local service on the default port with SSL disabled:

electric config update \
    --replication-disable-ssl \
    --replication-host localhost \
    --replication-port 5133

This adds a replication section to the environment in your electric.json config:

{
  // ...
  "environments": {
    "default": {
      "replication": {
        "host": "localhost",
        "port": 5133,
        "ssl": false
      }
    }
  }
}

See electric init --help, electric config --help and the config module in the Typescript client for more details.

Next step