The ElectricSQL CLI is the command line interface utility for the ElectricSQL service. It's developed in Elixir using Optimus and Bakeware and is published under the Apache 2.0 License at github.com/electric-sql/cli.
You need Elixir then run:
mix deps.get
Run tests using:
mix test
You can run the command locally using:
mix dev
Arguments are passed directly to the CLI, e.g.:
# equivalent to `electric auth whoami`
mix dev auth whoami
Alternatively, you can build the executable:
./build.sh
And run it:
./electric
./release.sh
This creates a binary at ./dist/electric
and needs to be run on the OS you are targetting.
See also https://github.com/bake-bake-bake/bakeware#static-compiling-openssl-into-erlang-distribution
The following examples assume that you have the ./dist/electric
binary on your path.
electric --help
The optional --verbose
flag can be added to any command to output some useful
information about what the client is doing.
Prefixing a command or sub command with help
will print detailed usage information. For example:
electric help auth whoami
Login using:
electric auth login EMAIL [--password PASSWORD]
Where your EMAIL
is the email address associated with your ElectricSQL account. You will be prompted to enter your password if not provided.
electric init APP [--env ENV] [--migrations-dir MIGRATIONS_DIR] [--output-dir OUTPUT_DIR]
Creates a new folder for migrations in your current directory called 'migrations' and adds a new migration folder to it with a name automatically derived from the current time in UTC and the title init
e.g. 20221116162204816_init
. Inside this folder will be a file called migration.sql
. You should write your initial SQLite DDL SQL into this file.
The APP
and optinally ENV
you give should be copied from the sync service connection details provided by the ElectricSQL console. You specify here once, and the CLI stores in an electric.json
file so you don't have to keep re-typing it.
Note that you can also sync down migrations from an existing app using:
electric init APP --sync-down
You can update your config using electric config update
. See the options with:
electric config update --help
The migrations
command lets you create new migrations, build electrified javascript distributions of the migrations to use in your project, and sync your migrations to our cloud service.
electric migrations new NAME
This adds a new migration to the migrations
folder with a name automatically derived from the current time in UTC and the given NAME
, which should be a short human readable description of the new migration.
electric migrations build [--env ENV] [--postgres] [--satellite]
Builds a bundled javascript file at .electric/:app/:env/index.js
that can be imported into your local application using the @config
or @app/:env
symlinks, e.g.:
import config from '.electric/@config'
See the configuration guide for more details.
The optional flag --postgres
will also build a postgres.sql
file in each migrations' folder with the PostgreSQL formatted migrations. This is useful for applying migrations manually to Postgres.
The optional flag --satellite
will also build a satellite.sql
file in each migrations' folder that's designed to be applied to SQLite. This is primarily useful for testing and advanced debugging.
electric sync [--env ENV]
Synchronises changes you have made to migration SQL files in your local migrations
folder up to the backend servers, and builds a new javascript file at .electric/:app/:env/index.js
that matches the newly synchronised set of migrations. The metadata in this file will have a "build": "server"
to indicate that it was built directly from the named backend environment.
By default this will sync to the default
environment for your app. If you want to use a different one give its name with --env ENV
.
If the app environment on our servers already has a migration with the same name but different sha256 then this synchronisation will fail because a migration cannot be modified once it has been applied.
If this happens you have two options, either:
electric migrations revert NAME
; orelectric reset
(warning: causes data loss)See below for information on both commands. Note also that if a migration has a name that is lower in sort order than one already applied on the server this will also error.
electric migrations list [--env ENV]
Will show a list of all the migrations and their status in every env in the app.
electric migrations revert NAME [--env ENV]
This will copy the named migration from the ElectricSQL server to replace the local one. By default this will use the default
environment, if you want to use a different one you can specify it with --env ENV
.
If you're having problems with your local migrations, you can force revert:
electric migrations revert NAME --force
And you can revert all of the local migrations to match the migrations that have been applied on the server. This is like a force reset of the local migrations folder:
electric migrations revert --all
Remeber to electric build
after resetting before importing into your local app.
WARNING: Use
reset
with extreme care (and usually only in development) as it explicitly causes data loss.
If you get stuck and need to reset the migrations that have been applied on the server, you can wipe and re-provision your environment using:
electric reset [--env ENV]
This is like a force reset of the server migrations. Remember to electric sync
to upload your local migrations to the new server environment before restarting replication.
See the Community Guidelines including the Guide to Contributing and Contributor License Agreement.
We have an open community Discord. If you’re interested in the project, please come and say hello and let us know if you have any questions or need any help or support getting things running.