Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

electric-sql

Package Overview
Dependencies
Maintainers
2
Versions
239
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

electric-sql

ElectricSQL TypeScript client for developing local-first SQL apps. Supports JavaScript based mobile, web and edge applications.

  • 0.3.10
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
167
increased by28.46%
Maintainers
2
Weekly downloads
 
Created
Source
ElectricSQL logo

GitHub npm Tests

ElectricSQL Typescript Client

ElectricSQL is a local-first SQL system. It provides active-active cloud sync for embedded SQLite databases and a reactive programming model to bind components to live database queries.

The ElectricSQL Typescript Client is the main ElectricSQL client library for developing node, web and JavaScript-based mobile applications. It's designed to work with any SQLite driver or bindings, with convienience functions to integrate with the most popular ones, including the primary drivers for Cordova, Expo, React Native, SQL.js (with absurd-sql), Node.js (via better-sqlite3), TypeORM and Prisma.

Install

Using yarn:

yarn add electric-sql

Or using npm:

npm install --save electric-sql

Usage

The general principle is that you instantiate and use your SQLite driver as normal and call electrify when opening a new database connection. For example using react-native-sqlite-storage:

import { electrify } from 'electric-sql/react-native'

// Import your SQLite driver.
import SQLite from 'react-native-sqlite-storage'
SQLite.enablePromise(true)

// Open a database connection and electrify it.
SQLite.openDatabase('example.db')
  .then(db => electrify(db, { app: "my-app", env: "prod", token: "token", migrations: [] }))
  .then(db => { // Use as normal, e.g.:
    db.transaction(tx => tx.executeSql('SELECT 1'))
  })

Browser

Electric uses SQL.js in the browser with absurd-sql for persistence. This runs in a web worker (which we also use to keep background replication off the main thread). As a result, the electrified db client provides an asynchronous version of a subset of the SQL.js driver interface.

First create a worker.js file that imports and starts an ElectricWorker process:

// worker.js
import { ElectricWorker } from 'electric-sql/browser'

ElectricWorker.start(self)

Then, in your main application:

import { initElectricSqlJs } from 'electric-sql/browser'

// Start the background worker.
const url = new URL('./worker.js', import.meta.url)
const worker = new Worker(url, {type: "module"})

// Electrify the SQL.js / absurd-sql machinery and then open
// a persistent, named database.
initElectricSqlJs(worker, {locateFile: file => `/${file}`})
  .then(SQL => SQL.openDatabase('example.db', { app: "my-app", env: "prod", token: "token", migrations: [] }))
  .then(db => db.exec('SELECT 1'))

This gives you persistent, local-first SQL with active-active replication in your web browser 🤯. Use the db client as normal, with the proviso that the methods are now async (they return promises rather than direct values).

Note that the path to the worker.js must be relative and the worker.js file must survive any build / bundling process. This is handled automatically by most bundlers, including Esbuild (as of #2508), Rollup and Webpack.

See the usage documentation for:

Reactivity

Once electrified, you can bind database queries to your reactive components, so they automatically re-query and (if necessary) re-render when the underlying data changes.

For example, again using React Native as an example, configure an electrified database provider at the root of your component hierarchy:

// App.js
import React, { useEffect, useState } from 'react'

import { ElectricProvider } from 'electric-sql/react'

export default const App = () => {
  const [db, setDb] = useState(null)

  useEffect(() => {
    SQLite.openDatabase('example.db')
      .then(db => electrify(db, { app: "my-app", env: "prod", token: "token" }))
      .then(db => setDb(db))
  }, [])

  if (!db) { 
    return null
  }

  return (
    <ElectricProvider db={ db }>
      {/* ... your component hierarchy here */}
    </ElectricProvider>
  )
}

You can then bind query results to your reactive component using the useElectricQuery hook:

// MyComponent.js
import React from 'react'
import { Pressable, Text, View } from 'react-native'

import { useElectric, useElectricQuery } from 'electric-sql/react'

export const MyComponent = () => {
  // Query `results` are kept in sync automatically.
  const { results } = useElectricQuery('SELECT value FROM items')

  // Writes are made using standard SQL.
  const [ sql ] = useElectric()
  const addItem = () => sql.execute('INSERT INTO items VALUES(?)', [`${Date.now()}`])

  return (
    <View>
      {results.map((item, index) => (
        <Text key={index}>
          Item: {item.value}
        </Text>
      ))}

      <Pressable onPress={addItem}>
        <Text>Add</Text>
      </Pressable>
    </View>
  )
}

See the frameworks guide for more information.

Issues

Please raise any bugs, issues and feature requests on GitHub Issues.

Contributing

See the Community Guidelines including the Guide to Contributing and Contributor License Agreement.

Support

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.

Keywords

FAQs

Package last updated on 02 Jan 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc