Configure

Each ElectricSQL application is required to configure the app (and optionally the env and replication service to connect to) and the bundled migrations that define the database schema.

Overview

When electrifying your driver, you must pass in a globally unique app slug and statically imported, bundled migrations data. These must be passed in as a config object to the electrify function call that electrifies your database driver. For example:

import { data } from '../migrations'

const config = {
  app: '<YOUR APP SLUG>',
  migrations: data.migrations
}

SQLite.openDatabase('example.db')
  .then((db) => electrify(db, true, config))

Options

app

ElectricSQL replicates data to and from a geo-distributed database service. This database is identified by a globally unique slug (app).

To use ElectricSQL, you first sign up for an account and then create an application. At the end of the provisioning flow, you will be presented with your app slug and PSQL credentials. Copy these and store them somewhere safe (like a password manager).

env

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

// Connect to the default environment:
const config = {
  app: '<YOUR APP SLUG>'
}

// Is equivalent to:
const config = {
  app: '<YOUR APP SLUG>',
  env: 'default'
}

// Or explicitly connect to a named environment:
const config = {
  app: '<YOUR APP SLUG>',
  env: 'staging'
}

migrations

In order to work, ElectricSQL takes over the process of applying migrations to evolve your SQL database schema. See the migrations guide for more information.

Once you’ve initialised a migrations folder using the electric CLI, you bundle your migrations into an importable JavaScript module. By convention this is output as an index.js file in ./migrations/. You can specify an alternative path using the --dir option.

electric migrations build --bundle

You then include the resulting bundled module using a static import and then pass the imported migrations data to the electrify function call alongside your app, as per:

import { data } from '../migrations'

const config = {
  migrations: data.migrations
  // ...
}

This static import mechanism makes the path to the migrations explicit and ensures that the migration data is bundled into your app when using a bundler like Esbuild, Vite or Webpack.

See the ElectrifyOptions interface in the Typescript client source code.

replication

By default, the ElectricSQL client connects to the ElectricSQL managed replication sevrice. If you’re running the backend yourself, for example in local development, you can configure the service to connect to using the replication object. This has two properties, address and host.

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

const config = {
  replication: {
    address: 'localhost',
    port: 5133
  },
  // ... other configuration options ...
}

Next step