Skip to main content

CLI Commands

The Electric client library comes with a CLI providing a number of helpful commands for building Electric apps:

  • generate - The type-safe client generator; this command builds the client library for your applications to use.
  • proxy-tunnel - A tool to enable you to connect to the Electric migrations proxy when it's deployed behind a restrictive firewall, or with a hosting provider that only allows incoming HTTP connections.
  • start - Start an Electric sync service for development, along with an optional PostgreSQL
  • stop - Stop the development Electric sync service, and any optional PostgreSQL
  • status - Show status of the development Electric sync service docker containers
  • psql - Connect with psql to the Migration proxy
  • show-config - Show the current configuration
  • with-config - Run a sub command with config arguments substituted
  • help - Display help for a command

These commands are all executed in the form npx electric-sql [command-name] from within a project where you have installed the client library.

All commands accept both arguments and environment variables for configuration, and the CLI uses dotenv-flow to load environment variables from .env files. When a command line argument is provided, it takes precedence over the environment variable. See the full list of environment variables.

Commands​

generate​

To interface with your database from within a JavaScript or TypeScript application you need an Electric client (see Usage -> Data access -> Client for context). To generate an Electric client, make sure that your database and the Electric sync service are up and running. Then, from within the root folder of your application run:

npx electric-sql generate

This will download all migrations from the database, bundle them with your application, and generate the Electric client. Note that you can use an optional --watch flag to automatically re-generate the client on every database migration.

Options​

The generate command accepts a number of arguments:

npx electric-sql generate [options]

All arguments are optional. The principal ones are described below:

Argument or Env varValueDescription
--service
-s
ELECTRIC_SERVICE		<url>Provides the url to connect to the Electric sync service.
Defaults to http://localhost:5133.
--proxy
-p
ELECTRIC_PROXY		<url>Provides the url to connect to Electric's database proxy.
Defaults to postgresql://postgres:proxy_password@localhost:65432/your_db_name, where your_db_name is the name provided through ELECTRIC_DATABASE_NAME.
--client-path
-o
ELECTRIC_CLIENT_PATH		<path>Specifies the output location for the generated client.
Defaults to ./src/generated/client
--watch
-w		<pollingInterval>Run the generator in watch mode. Accepts an optional polling interval (in milliseconds) which defines how often to poll Electric for database migrations.
The default polling interval is 1000ms.
--with-migrations<command>Specify a command to run migrations against an ephemeral postgres in order to create a client. See details below
--module-resolution<command>The module resolution used for the project. The generated client will be compatible with this resolution scheme, see notes below.
--debug<boolean>Optional flag to enable debug mode. When enabled, the temporary migration files used to generate the client will be retained for inspection.

For a full list of arguments run npx electric-sql help generate or see the environment variables below.

Local-only-first mode​

Normally, when you develop or deploy apps with Electric, you want to run the backend services (Postgres and Electric) in order to sync data. As a result, it's natural that the generate command expects you to be running the backend services during your build step.

However, it's also quite common in development or with an early version of an app, not to need data sync enabled yet. Either because you're just working on the interface or because your app starts off local-only and you plan to enable sync later. This makes the overhead of running (and potentially deploying) the backend services quite high, given that you're running them just to support the generate command in your build step.

As a result, we provide a special --with-migrations mode for the generate command that allows you to generate the type safe client just from your migrations, without having to run the backend services yourself. Specifically what the --with-migrations option does is it tells the generate command to spin up a temporary Postgres and Electric itself, apply your migrations from scratch, generate the type safe client and then tear Electric and Postgres down. All of which happens automatically in the background for you.

We call this approach "local-only-first", in the sense that it allows you to develop local-only and then progressively enable sync later on, as and when you want to.

The --with-migrations command that takes the same argument form as the with-config command. With this you can run:

npx electric-sql generate --with-migrations "npx pg-migrations apply --database {{ELECTRIC_PROXY}} --directory ./db/migrations"

In essence this is the equivalent of:

npx electric-sql start
npx electric-sql with-config "npx pg-migrations apply --database {{ELECTRIC_PROXY}} --directory ./db/migrations"
npx electric-sql generate
npx electric-sql stop --remove

As you can see from the steps above, the backend is started, your migrations are applied, the type-safe client is generated and then everything is torn down and cleaned up for you. Allowing you to develop local-only-first and then run the backend services only when you actually want to enable sync.

proxy-tunnel​

Some hosting providers only allow HTTP connections, which poses a challenge for deploying Electric to their platforms since it uses a separate port for connections to the migrations proxy. In order to enable connecting to run migrations and use the generate command in these setups, you can enable a special "Proxy Tunnel" that tunnels the Postgres Proxy TCP connection over a Websocket to the Electric sync service. This is enabled on the sync service by setting the environment variable PG_PROXY_PORT=http.

The npx electric-sql proxy-tunnel command is provided to forward TCP traffic from your local machine to the Electric Postgres Proxy when it has tunneling enabled. It binds to a local port, allowing you to use the generator command, perform migrations, and connect with psql.

To connect to the service, and create a local proxy tunnel:

npx electric-sql proxy-tunnel --service http://my.electric.host:5133 --local-port 65431

Then to run migrations, if you are using @databases/pg-migrations as we do in our starter template, you can run this in another shell:

npx pg-migrations apply --database postgres://postgres:proxy_password@localhost:65431 --directory ./db/migrations

To then use the generate command to create your client:

npx electric-sql generate --service http://my.electric.host:5133 --proxy postgresql://postgres:proxy_password@localhost:65431/electric

Options​

The proxy-tunnel command accepts a number of arguments:

npx electric-sql proxy-tunnel [--service <url>] [--local-port <port>]

All arguments are optional and are described below:

Argument or Env varValueDescription
--service
ELECTRIC_SERVICE		<url>Provides the url to connect to the Electric sync service. If not provided it uses the url set in the ELECTRIC_URL environment variable. If that variable is not set, it resorts to the default url which is http://localhost:5133.
--local-port<port>The local port to bind to; this will be forwarded to the Electric sync service, and defaults to 65432.

start​

Starts an Electric sync service (using Docker) for development, along with an optional Postgres database.

By default it will launch a sync service that is compatible with the client version you have installed.

All environment variables for configuring the Electric sync service, when prefixed with ELECTRIC_, are passed through to the sync service started with the start command.

To start an Electric sync service, along with Postgres, fully configured for development run:

npx electric-sql start --with-postgres

Options​

The start command accepts a number of arguments:

npx electric-sql start [options]

All arguments are optional. The principal ones are described below:

Argument or Env varValueDescription
--with-postgresStart a Postgres database along with Electric.
--detachRun in the background instead of printing logs to the console.
--database-url
-db
ELECTRIC_DATABASE_URL		<url>PostgreSQL connection URL for the database you want Electric to connect to. Mutually exclusive with --with-postgres.
--http-port
ELECTRIC_HTTP_PORT		<port>The local port to run the sync service on. Defaults to 5133
--pg-proxy-port
ELECTRIC_PG_PROXY_PORT		<port>The local port to bind the Postgres Proxy port to. Defaults to 65432
--image
ELECTRIC_IMAGE		<image>The Docker image to use for Electric.
--postgresql-image
ELECTRIC_POSTGRESQL_IMAGE		<image>The Docker image to use for the PostgreSQL database.

For a full list of arguments run npx electric-sql help start or see the environment variables below.

stop​

Stop the development Electric sync service that was started with the start command, and any optional PostgreSQL.

npx electric-sql stop [--remove]

Options​

The stop command accepts a single argument:

ArgumentDescription
--removeRemove the Docker containers and volumes previously created by start.

status​

Show status of the Electric sync service docker containers that were started with the start command.

npx electric-sql status

psql​

Start an interactive PSQL session with the Postgres that was started with the start --with-postgres command, connecting via the Electric Migrations proxy.

This uses the psql installed in the Postgres container started with start --with-postgres command, and only supports connecting to that Postgres.

npx electric-sql psql [--proxy <url>]

Options​

Argument or Env varValueDescription
--proxy
-p
ELECTRIC_PROXY		<url>URL of the Electric service's PostgreSQL proxy.

For a full list of arguments run npx electric-sql help psql or see the environment variables below.

show-config​

Print out the full configuration that the CLI is using based on any env variable, or .env files.

npx electric-sql show-config

with-config​

This command allows you to run a subcommand substituting arguments configured with Electric environment variables. It also makes all Electric configuration environment variables available to the subcommand.

One of the main use cases for this command is running migrations against your Migration proxy using the configuration specified locally.

It takes a single string argument, which is the command to run in string form, and substitutes configuration values inside double braces:

npx electric-sql with-config "run-migration --db {{ELECTRIC_PROXY}}"

Many of our examples use the @databases/pg-migrations tool for migrations, and we run the migrations with:

npx electric-sql with-config "npx pg-migrations apply --database {{ELECTRIC_PROXY}} --directory ./db/migrations"

We have this configured as a "script" in our package.json for each example:

// package.json
{
  //...
  "scripts": {
    "db:migrate": "npx electric-sql with-config 'npx pg-migrations apply --database {{ELECTRIC_PROXY}} --directory ./db/migrations'",
    // ...
  }
}

help​

Display the help for a command.

npx electric-sql help <command>

Environment Variables​

In addition to those specified below, all standard Electric sync service environment variables are available for setting prefixed with ELECTRIC_. These are then passed though to the sync service started with the start command. See a full list of environment variables here.

ELECTRIC_CLIENT_PATH​

VariableELECTRIC_CLIENT_PATH
Default./src/generated/client
DescriptionPath to the directory where the generated client code will be written.

Used by the generate command.

ExampleELECTRIC_CLIENT_PATH=./src/electricClient

ELECTRIC_CONTAINER_NAME​

VariableELECTRIC_CONTAINER_NAME
Defaultelectric
DescriptionThis sets the name of the Docker containers when using the start command.

It defaults to the name in your packages.json and falls back to electric otherwise.

Used by the start command.

ExampleELECTRIC_CONTAINER_NAME=nodenext

ELECTRIC_DATABASE_HOST​

VariableELECTRIC_DATABASE_HOST
Defaultlocalhost
DescriptionHostname of the database server.

Used by the start command.

ExampleELECTRIC_DATABASE_HOST=electric.myhost.com

ELECTRIC_DATABASE_NAME​

VariableELECTRIC_DATABASE_NAME
Defaultelectric
DescriptionName of the database to connect to.

Used by the start and psql commands.

Defaults to the project name (i.e. "name": "my-project-name") specified in your package.json file, falls back to electric.

ExampleELECTRIC_DATABASE_NAME=db_password

ELECTRIC_DATABASE_PASSWORD​

VariableELECTRIC_DATABASE_PASSWORD
Defaultdb_password
DescriptionPassword to connect to the database with.

Used by the start command.

ExampleELECTRIC_DATABASE_PASSWORD=db_password

ELECTRIC_DATABASE_PORT​

VariableELECTRIC_DATABASE_PORT
Default5432
DescriptionPort number of the database server.

Used by the start command.

ExampleELECTRIC_DATABASE_PORT=5433

ELECTRIC_DATABASE_URL​

VariableELECTRIC_DATABASE_URL
Defaultpostgresql://{ELECTRIC_DATABASE_USER}:{ELECTRIC_DATABASE_PASSWORD}@{ELECTRIC_DATABASE_HOST}:{ELECTRIC_DATABASE_PORT}/{ELECTRIC_DATABASE_NAME}
DescriptionPostgreSQL connection URL for the database.

Used by the start command.

With all defaults, it evaluates to: postgresql://postgres:db_password@localhost:5432/electric-sql

ExampleELECTRIC_DATABASE_URL=postgresql://postgres:db_password@electric.myhost.com:5432/electric-sql

ELECTRIC_DATABASE_USER​

VariableELECTRIC_DATABASE_USER
Defaultpostgres
DescriptionUsername to connect to the database with.

Used by the start command.

ExampleELECTRIC_DATABASE_USER=my_db_user

ELECTRIC_HTTP_PORT​

VariableELECTRIC_HTTP_PORT
Default5133
DescriptionPort for HTTP connections.

Used by the start command along with connecting to the sync service from your project client.

ExampleELECTRIC_HTTP_PORT=5144

ELECTRIC_IMAGE​

VariableELECTRIC_IMAGE
Defaultelectricsql/electric:{version-tag}
DescriptionThe Docker image to use for Electric.

Used by the start command.

Defaults to the matching minor version for the installed Electric client, so if you are using electric-sql@0.8.2 the docker image tagged electricsql/electric:0.8 (the latest in the 0.8.n range) will be used.

ExampleELECTRIC_IMAGE=electricsql/electric:0.8

ELECTRIC_MODULE_RESOLUTION​

VariableELECTRIC_MODULE_RESOLUTION
Defaultnode
DescriptionThe module resolution used for the project. The generated client will be compatible with this resolution scheme. If you are using `nodenext` as your `tsconfig.json` `moduleResolution` then settings this to `nodenext` also will ensure that the generated client is compatible with your TypeScript configuration.

Used by the generate command.

ExampleELECTRIC_MODULE_RESOLUTION=nodenext

ELECTRIC_PG_PROXY_PASSWORD​

VariableELECTRIC_PG_PROXY_PASSWORD
Defaultproxy_password
DescriptionPassword to use when connecting to the Postgres proxy via psql or any other Postgres client.

Used by the start and psql commands.

ExampleELECTRIC_PG_PROXY_PASSWORD=my_password

ELECTRIC_PG_PROXY_PORT​

VariableELECTRIC_PG_PROXY_PORT
Default65432
DescriptionPort number for connections to the Postgres migration proxy.

Used by the start and psql commands.

ExampleELECTRIC_PG_PROXY_PORT=65433

ELECTRIC_POSTGRESQL_IMAGE​

VariableELECTRIC_PG_PROXY_PASSWORD
Defaultpostgres:14-alpine
DescriptionThe Docker image to use for the PostgreSQL database.

Used by the start command.

ExampleELECTRIC_PG_PROXY_PASSWORD=postgres:16

ELECTRIC_PROXY​

VariableELECTRIC_PROXY
Defaultpostgresql://postgres:{ELECTRIC_PG_PROXY_PASSWORD}@{ELECTRIC_SERVICE_HOST}:{ELECTRIC_PG_PROXY_PORT}/{ELECTRIC_DATABASE_NAME}
DescriptionURL of the Electric service's PostgreSQL proxy.

Used by the generate and psql commands.

With all defaults, it evaluates to: postgresql://postgres:proxy_password@localhost:65432/electric

ExampleELECTRIC_PROXY=postgresql://postgres:proxy_password@electric.mydomain.com:65432/electric

ELECTRIC_SERVICE​

VariableELECTRIC_SERVICE
Defaulthttp://{ELECTRIC_SERVICE_HOST}:{ELECTRIC_HTTP_PORT}
DescriptionURL of the Electric service.

Used by the generate command.

With all defaults, it evaluates to http://localhost:5133

ExampleELECTRIC_SERVICE=https://electric.mydomain.com

This ELECTRIC_SERVICE variable is perfect for configuring the Electric client in your project. 

import { schema } from './generated/client'

const conn = await ElectricDatabase.init(scopedDbName)
const electric = await electrify(conn, schema, {
  url: import.meta.env.ELECTRIC_SERVICE
  // ...
})

ELECTRIC_SERVICE_HOST​

VariableELECTRIC_SERVICE_HOST
Defaultlocalhost
DescriptionHostname the Electric service is running on.

Used by the generate and psql commands.

ExampleELECTRIC_SERVICE_HOST=electric.mydomain.com

ELECTRIC_WITH_POSTGRES​

VariableELECTRIC_WITH_POSTGRES
Defaulttrue
DescriptionStart a PostgreSQL database along with Electric.

Used by the start command.

ExampleELECTRIC_WITH_POSTGRES=false