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