Getting started with PGlite

PGlite can be used in both Node/Bun or the browser, and with any JavaScript framework.

Install and start in Node/Bun

Install into your project:

npm

npm install @electric-sql/pglite

pnpm

pnpm install @electric-sql/pglite

yarn

yarn add @electric-sql/pglite

bun

bun install @electric-sql/pglite

To use the in-memory Postgres:

import { PGlite } from '@electric-sql/pglite'

const db = new PGlite()

or to persist to the native filesystem:

const db = new PGlite('./path/to/pgdata')

Install and start in the browser

It can be installed and imported using your usual package manager:

import { PGlite } from '@electric-sql/pglite'

or using a CDN such as JSDeliver:

import { PGlite } from 'https://cdn.jsdelivr.net/npm/@electric-sql/pglite/dist/index.js'

Then for an in-memory Postgres:

const db = new PGlite()

or to persist the database to IndexedDB:

const db = new PGlite('idb://my-pgdata')

Making a query

There are two methods for querying the database, .query and .exec. The former supports parameters, while the latter supports multiple statements.

First, let's create a table and insert some test data using the .exec method:

await db.exec(`
  CREATE TABLE IF NOT EXISTS todo (
    id SERIAL PRIMARY KEY,
    task TEXT,
    done BOOLEAN DEFAULT false
  );
  INSERT INTO todo (task, done) VALUES ('Install PGlite from NPM', true);
  INSERT INTO todo (task, done) VALUES ('Load PGlite', true);
  INSERT INTO todo (task, done) VALUES ('Create a table', true);
  INSERT INTO todo (task, done) VALUES ('Insert some data', true);
  INSERT INTO todo (task) VALUES ('Update a task');
`)

The .exec method is perfect for migrations and batch inserts with raw SQL.

Now, let's retrieve an item using .query method:

const ret = await db.query(`
  SELECT * from todo WHERE id = 1;
`)
console.log(ret.rows)

Output:

;[
  {
    id: 1,
    task: 'Install PGlite from NPM',
    done: false,
  },
]

Using parametrised queries

When working with user supplied values, it's always best to use parametrised queries; these are supported on the .query method.

We can use this to update a task:

const ret = await db.query(
  'UPDATE todo SET task = $2, done = $3 WHERE id = $1',
  [5, 'Update a task using parametrised queries', true],
)

What next?

• To learn more about querying and transactions along with the other methods and options available, you can read the main PGlite API documentation.

• There is also a live-query extension that enables reactive queries to update a UI when the underlying database changes.

• PGlite has a number of built-in virtual file systems to provide persistance for your database.

• There are framework hooks to make working with PGlite within React and Vue much easier with less boilerplate.

• For help configuring PGlite with your bundler, see the bundler support page.

• As PGlite only has a single exclusive connection to the database, we provide a multi-tab worker to enable sharing a PGlite instance between multiple browser tabs.

• There is a REPL component that can be easily embedded into a web-app to aid in debugging and development, or as part of a database application itself.

• We maintain a list of ORMs and query builders that support PGlite.

• PGlite supports both Postgres extensions and PGlite Plugins via its extensions API, and there is a list of supported extensions.

• We have a page of examples that you can open to test out PGlite in the browser.