PGlite

https://pglite.dev/docs
Admin
PGlite is a WASM-based Postgres build that runs in the browser, Node.js, and Bun without external...
Tokens:24,266
Snippets:329
Trust Score:8.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install PGlite in the browser

Source: https://pglite.dev/docs

Install PGlite using a package manager or a CDN.

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

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

--------------------------------

### Install PGlite in Node/Bun/Deno

Source: https://pglite.dev/docs

Install PGlite using npm, pnpm, yarn, bun, or deno.

```bash
npm install @electric-sql/pglite
```

```bash
pnpm install @electric-sql/pglite
```

```bash
yarn add @electric-sql/pglite
```

```bash
bun install @electric-sql/pglite
```

```bash
deno add npm:@electric-sql/pglite
```

--------------------------------

### Getting started with PGlite

Source: https://pglite.dev/docs/about

Demonstrates how to install, import, and use PGlite to run a simple query in JavaScript.

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

const db = new PGlite()
await db.query("select 'Hello world' as message;")
// -> { rows: [ { message: "Hello world" } ] }
```

--------------------------------

### Set Postgres Start Parameters

Source: https://pglite.dev/docs/api

Example of passing custom start parameters to the Postgres process.

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

const pg = await PGlite.create({
  startParams: [
    ...PGlite.defaultStartParams,
    '-c',
    'application_name=My awesome backend',
  ],
})
```

--------------------------------

### Output of retrieving data

Source: https://pglite.dev/docs

Example output when retrieving a row using .query.

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

--------------------------------

### Local development with `prisma dev`

Source: https://pglite.dev/docs/orm-support

Example of initializing Prisma and starting a local development server with PGlite.

```bash
npx prisma init
npx prisma dev
```

--------------------------------

### Use in-memory Postgres in Node/Bun/Deno

Source: https://pglite.dev/docs

Initialize an in-memory PGlite database instance.

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

const db = new PGlite()
```

--------------------------------

### Knex.js PGlite setup

Source: https://pglite.dev/docs/orm-support

Example of setting up a Knex.js instance with the knex-pglite client.

```javascript
import { knex } from 'knex'
import ClientPgLite from 'knex-pglite'

export const db = knex({
  client: ClientPgLite,
  dialect: 'postgres',
  connection: { connectionString: 'idb://my-database' },
})
```

--------------------------------

### Persist to filesystem in Node/Bun/Deno

Source: https://pglite.dev/docs

Initialize a PGlite database instance that persists to the native filesystem.

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

--------------------------------

### Development Server Integration Examples

Source: https://pglite.dev/docs/pglite-socket

Examples of starting the PGlite development server with different application types and including the DATABASE_URL environment variable.

```bash
# Start your Next.js dev server with PGlite
pglite-server --run "npm run dev" --include-database-url

# Start a Node.js app with PGlite
pglite-server --db=./dev-db --run "node server.js" --include-database-url

# Start multiple services (using a process manager like concurrently)
pglite-server --run "npx concurrently 'npm run dev' 'npm run worker'" --include-database-url
```

--------------------------------

### In-memory Postgres in the browser

Source: https://pglite.dev/docs

Initialize an in-memory PGlite database instance in the browser.

```javascript
const db = new PGlite()
```

--------------------------------

### Unix Socket Support Example

Source: https://pglite.dev/docs/pglite-socket

Example of starting the PGlite server on a Unix socket and the resulting DATABASE_URL.

```bash
# Start server on a Unix socket
pglite-server --path=/tmp/.s.PGSQL.5432 --run "npm run dev" --include-database-url

# The DATABASE_URL will be: postgresql://postgres:postgres@/postgres?host=/tmp
```

--------------------------------

### Persist to IndexedDB in the browser

Source: https://pglite.dev/docs

Initialize a PGlite database instance that persists to IndexedDB.

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

--------------------------------

### Usage

Source: https://pglite.dev/docs/pglite-socket

Example of creating a PGlite instance and starting a socket server.

```typescript
import { PGlite } from '@electric-sql/pglite'
import { PGLiteSocketServer } from '@electric-sql/pglite-socket'

// Create a PGlite instance
const db = await PGlite.create()

// Create and start a socket server
const server = new PGLiteSocketServer({
  db,
  port: 5432,
  host: '127.0.0.1',
})

await server.start()
console.log('Server started on 127.0.0.1:5432')

// Handle graceful shutdown
process.on('SIGINT', async () => {
  await server.stop()
  await db.close()
  console.log('Server stopped and database closed')
  process.exit(0)
})
```

--------------------------------

### Create table and insert data using .exec

Source: https://pglite.dev/docs

Use the .exec method to run raw SQL for creating tables and inserting data.

```javascript
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');
)
```

--------------------------------

### Retrieve data using .query

Source: https://pglite.dev/docs

Use the .query method to retrieve data with SQL.

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

--------------------------------

### Install the sync plugin

Source: https://pglite.dev/docs/sync

Install the `@electric-sql/pglite-sync` package using npm.

```shell
npm install @electric-sql/pglite-sync
```

--------------------------------

### Installation

Source: https://pglite.dev/docs/prepopulatedfs

Install the prepopulatedfs package using npm, yarn, or pnpm.

```bash
npm install @electric-sql/pglite-prepopulatedfs
# or
yarn add @electric-sql/pglite-prepopulatedfs
# or
pnpm add @electric-sql/pglite-prepopulatedfs
```

--------------------------------

### Knex.js PGlite installation

Source: https://pglite.dev/docs/orm-support

Commands to install Knex.js and the knex-pglite library.

```bash
npm i @electric-sql/pglite knex knex-pglite
```

--------------------------------

### Using PGlite in npm scripts

Source: https://pglite.dev/docs/pglite-socket

Example package.json scripts for starting the PGlite server with different configurations.

```json
{
  "scripts": {
    "db:start": "pglite-server --db=./data/mydb --port=5433",
    "db:dev": "pglite-server --db=memory:// --debug=1",
    "dev": "pglite-server --db=./dev-db --run 'npm run start:dev' --include-database-url",
    "dev:clean": "pglite-server --run 'npm run start:dev' --include-database-url"
  }
}
```

--------------------------------

### CLI Usage

Source: https://pglite.dev/docs/pglite-socket

Examples of using the pglite-server CLI to start a PGlite socket server with various options.

```bash
# Install globally
npm install -g @electric-sql/pglite-socket

# Start a server with default settings (in-memory database, port 5432)
pglite-server

# Start a server with custom options
pglite-server --db=/path/to/database --port=5433 --host=0.0.0.0 --debug=1

# Using short options
pglite-server -d /path/to/database -p 5433 -h 0.0.0.0 -v 1

# Show help
pglite-server --help
```

--------------------------------

### Prisma connection string

Source: https://pglite.dev/docs/orm-support

Example connection string for Prisma when using PGlite.

```bash
DATABASE_URL="prisma+postgres://localhost:PORT/?api_key=__API_KEY__"
```

--------------------------------

### Install TypeORM and typeorm-pglite

Source: https://pglite.dev/docs/orm-support

Install the necessary packages for TypeORM integration with PGlite.

```bash
npm i @electric-sql/pglite typeorm-pglite
```

--------------------------------

### Upgrade code example

Source: https://pglite.dev/docs/upgrade

Example code demonstrating how to use pg_dump to create a database dump from the previous version of PGlite and import it into a new instance.

```typescript
// in your upgrade code, you can then use your current PGlite
// version to dump the database:
import { PGlite } from '@electric-sql/pglite' // current version
import { PGlite as PGlite04 } from 'pglite-04' // next version

[...] 

// pg03 is your PGlite instance with version 0.3.x
const currentVersion = await pg03.query<{ version: string }>( 
  'SELECT version();'
)
console.log(currentVersion.rows[0].version)

const dumpDir = await pg03.dumpDataDir('none')
const pgCurr = await PGlite.create({ loadDataDir: dumpDir })
const dumpResult = await pgDump({ pg03: pgCurr })

// pg03 is PGlite instance with version 0.3.x
const pg03 = await PGlite04.create()

pg03.exec(await dumpResult.text())
// adapt the SEARCH_PATH to your needs
await pg03.exec('SET SEARCH_PATH = public;')

const nextVersion = await pg03.query<{ version: string }>(
  'SELECT version();'
)
console.log(nextVersion.rows[0].version)

```

--------------------------------

### Kysely PGlite installation

Source: https://pglite.dev/docs/orm-support

Commands to install Kysely and PGlite for integration.

```bash
npm i @electric-sql/pglite kysely
```

--------------------------------

### Installation

Source: https://pglite.dev/docs/pglite-socket

Install the pglite-socket package using npm, yarn, or pnpm.

```bash
npm install @electric-sql/pglite-socket
# or
yarn add @electric-sql/pglite-socket
# or
pnpm add @electric-sql/pglite-socket
```

--------------------------------

### Install the PGlite REPL component

Source: https://pglite.dev/docs/repl

Install the PGlite REPL component using npm.

```bash
npm install @electric-sql/pglite-repl
```

--------------------------------

### Install ICU support package

Source: https://pglite.dev/docs/localesupport

Commands to install the ICU data package using common package managers.

```bash
npm install @electric-sql/pglite-icu-full
# or
yarn add @electric-sql/pglite-icu-full
# or
pnpm add @electric-sql/pglite-icu-full
```

--------------------------------

### Update data using parameterized queries

Source: https://pglite.dev/docs

Use parameterized queries with the .query method to safely update data.

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

--------------------------------

### Install newer version using bun

Source: https://pglite.dev/docs/upgrade

Install the newer version of PGlite alongside the current version in a project that uses a previous minor PGlite version.

```bash
bun install pglite-04@npm:@electric-sql/pglite@0.4.0
```

--------------------------------

### Prisma Client usage

Source: https://pglite.dev/docs/orm-support

Example of using Prisma Client to create and query users.

```typescript
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

await prisma.user.create({
  data: { email: 'alice@example.com' },
})

const users = await prisma.user.findMany()
console.log(users)
```

--------------------------------

### Vite Worker Import Example

Source: https://pglite.dev/docs/bundler-support

An example of how to import a worker in Vite using the recommended ?worker import method.

```typescript
import PGWorker from './worker.js?worker'

export const pglite = new PGliteWorker(
  new PGWorker({
    type: 'module',
      name: 'pglite-worker',
    }),
    {
      // ...your options here
    }
  ),
)
```

--------------------------------

### Drizzle installation

Source: https://pglite.dev/docs/orm-support

Commands to install Drizzle ORM and related packages for PGlite.

```sh
npm i drizzle-orm @electric-sql/pglite
npm i -D drizzle-kit
```

--------------------------------

### Orange ORM PGlite installation

Source: https://pglite.dev/docs/orm-support

Command to install the Orange ORM library for PGlite integration.

```bash
npm i @electric-sql/pglite orange-orm
```

--------------------------------

### PGLiteSocketHandler Example

Source: https://pglite.dev/docs/pglite-socket

Example of creating a PGlite instance, a socket handler, and a server that uses the handler.

```typescript
import { PGlite } from '@electric-sql/pglite'
import { PGLiteSocketHandler } from '@electric-sql/pglite-socket'
import { createServer, Socket } from 'net'

// Create a PGlite instance
const db = await PGlite.create()

// Create a handler
const handler = new PGLiteSocketHandler({
  db,
  closeOnDetach: true,
  inspect: false,
})

// Create a server that uses the handler
const server = createServer(async (socket: Socket) => {
  try {
    await handler.attach(socket)
    console.log('Client connected')
  } catch (err) {
    console.error('Error attaching socket', err)
    socket.end()
  }
})

server.listen(5432, '127.0.0.1')
```

--------------------------------

### Usage with Vitest

Source: https://pglite.dev/docs/prepopulatedfs

Example of using prepopulated FS in a Vitest test suite for faster test startup times.

```typescript
import { describe, it, expect, beforeEach } from 'vitest'
import { PGlite } from '@electric-sql/pglite'
import { dataDir } from '@electric-sql/pglite-prepopulatedfs'

describe('query and exec with different data sizes', () => {
  let pg: PGlite

  beforeEach(async () => {
    pg = await PGlite.create({
      loadDataDir: await dataDir(),
    })

    await pg.exec(`
        // setup default data
      `)
  })

  describe('test no. 1', () => {
    ...
  })

  describe('test no. 2', () => {
    ...
  })

  // many more tests here
})
```

--------------------------------

### Install newer version using npm

Source: https://pglite.dev/docs/upgrade

Install the newer version of PGlite alongside the current version in a project that uses a previous minor PGlite version.

```bash
npm install pglite-04@npm:@electric-sql/pglite@0.4.0
```

--------------------------------

### Configure Custom Parsers

Source: https://pglite.dev/docs/api

Example of mapping Postgres data type IDs to custom parser functions using the parsers option.

```typescript
import { PGlite, types } from '@electric-sql/pglite'

const pg = await PGlite.create({
  parsers: {
    [types.TEXT]: (value) => value.toUpperCase(),
  },
})
```

--------------------------------

### Install newer version using pnpm

Source: https://pglite.dev/docs/upgrade

Install the newer version of PGlite alongside the current version in a project that uses a previous minor PGlite version.

```bash
pnpm install pglite-04@npm:@electric-sql/pglite@0.4.0
```

--------------------------------

### Kysely PGlite integration

Source: https://pglite.dev/docs/orm-support

Example of creating a Kysely instance with the PGliteDialect.

```typescript
import { PGlite } from '@electric-sql/pglite'
import { Kysely, PGliteDialect } from 'kysely'

// See https://kysely.dev/docs/generating-types
interface Database {
  person: {
    id: string
  }
}

const db = new Kysely<Database>({
  dialect: new PGliteDialect({
    pglite: new PGlite(),
  }),
})

const people = await db.selectFrom('person').selectAll().execute()
```

--------------------------------

### Install newer version using yarn

Source: https://pglite.dev/docs/upgrade

Install the newer version of PGlite alongside the current version in a project that uses a previous minor PGlite version.

```bash
yarn add pglite-04@npm:@electric-sql/pglite@0.4.0
```

--------------------------------

### Connecting to the server using psql

Source: https://pglite.dev/docs/pglite-socket

Examples of connecting to the PGlite server using the psql client via TCP and Unix sockets.

```bash
# TCP connection
PGSSLMODE=disable psql -h localhost -p 5432 -d postgres

# Unix socket connection (if using --path)
PGSSLMODE=disable psql -h /tmp -d postgres
```

--------------------------------

### Configure Custom Serializers

Source: https://pglite.dev/docs/api

Example of mapping Postgres data type IDs to custom serializer functions using the serializers option.

```typescript
import { PGlite, types } from '@electric-sql/pglite'

const pg = await PGlite.create({
  serializers: {
    [types.NUMERIC]: (value) => value.toString(),
  },
})
```

--------------------------------

### Configure TypeORM with PGliteDriver

Source: https://pglite.dev/docs/orm-support

Example of configuring a TypeORM DataSource to use the PGliteDriver.

```javascript
import { PGliteDriver, getPGliteInstance } from 'typeorm-pglite'
import { DataSource } from 'typeorm'

const PGliteDataSource = new DataSource({
  type: 'postgres',
  driver: new PGliteDriver().driver,
})

// You can access the internal PGlite instance using getPGliteInstance function
const pgliteDb = await getPGliteInstance()
```

--------------------------------

### Kysely PGlite lazy instantiation

Source: https://pglite.dev/docs/orm-support

Example of lazy instantiation of PGlite within KyselyDialect.

```typescript
new PGliteDialect({
  pglite: () => new PGlite('./path/to/pgdata'),
})
```

--------------------------------

### In-memory FS - Default

Source: https://pglite.dev/docs/filesystems

The in-memory FS is the default when starting PGlite, and it is available on all platforms. All files are kept in memory and there is no persistence, other than calling `pg.dumpDataDir()` and then using the `loadDataDir` option at start. To use the in-memory FS you can use one of these methods: Don't provide a `dataDir` option.

```typescript
const pg = new PGlite()
```

--------------------------------

### Use Live Query Hook

Source: https://pglite.dev/docs/framework-hooks/react

Reactively re-renders components based on live query results. Includes the hook interface definition and a usage example.

```typescript
function useLiveQuery<T = { [key: string]: unknown }>(
  query: string,
  params: unknown[] | undefined | null,
): Results<T>
```

```typescript
import { useLiveQuery } from '@electric-sql/pglite-react'

const MyComponent = () => {
  const maxNumber = 100
  const items = useLiveQuery(`
    SELECT *
    FROM my_table
    WHERE number <= $1
    ORDER BY number;
  `, [maxNumber])

  return (
    <>
      {
        items.map((item) =>
          <MyItem item={item} />
        )
      }
    </>
  )
}
```

--------------------------------

### esbuild Workaround: Manual WASM and Data Loading

Source: https://pglite.dev/docs/bundler-support

This example shows how to manually provide PGlite's WASM modules and data bundle when using esbuild, as automatic resolution is not supported.

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

const [pgliteWasmModule, initdbWasmModule, fsBundle] = await Promise.all([
  WebAssembly.compileStreaming(fetch('/pglite.wasm')),
  WebAssembly.compileStreaming(fetch('/initdb.wasm')),
  fetch('/pglite.data').then((response) => response.blob()),
])

const db = await PGlite.create({
  pgliteWasmModule,
  initdbWasmModule,
  fsBundle,
})
```

--------------------------------

### Example Prompt for Wish List App

Source: https://pglite.dev/docs/pglite-socket

A prompt to generate a simple wish list app using TypeScript, React, Vite, Express, and PGlite with its socket server.

```plaintext
Please make a simple wish list app, it should have a single screen for adding items. There should be a single input for adding the text for the item. Keep it simple and minimal.
Show error messages inline in the UI, where the list is, when the backend fails to connect to the database.
Use TypeScript, React, and Vite for the front end app.
The server side should use TypeScript, tsx and Express with a Postgres database using the postgres.js lib and it's `sql` template literal syntax.
Please use concurrently to run both vite and the backend at the same time.
I want to use PGlite and its socket server for development - match these versions:
    "@electric-sql/pglite": "^0.3.2",
    "@electric-sql/pglite-socket": "^0.0.7",
Do something like this to run it:
    "dev": "USE_PGLITE=true npx pglite-server -u /tmp/.s.PGSQL.5432 -r \"npm run dev:both\"",
    "dev:both": "concurrently \"npm run dev:frontend\" \"npm run dev:backend\"",
    "dev:frontend": "vite",
    "dev:backend": "tsx watch server/index.ts",
and the postgres.js config should look something like this:
export const sql = process.env.USE_PGLITE
  ? postgres ({
    host: '/tmp/',
    username: 'postgres',
    password: 'postgres',
    database: 'postgres',
    max: 1,
    connect_timeout: 0,
  })
  : postgres(connectionString, {
    ssl: process.env.NODE_ENV === 'production',
  });
```

--------------------------------

### Drizzle PGlite integration

Source: https://pglite.dev/docs/orm-support

Example of integrating Drizzle ORM with a PGlite instance.

```typescript
import { PGlite } from '@electric-sql/pglite';
import { drizzle } from 'drizzle-orm/pglite';

const client = new PGlite();
const db = drizzle(client);

await db.select().from(...);
```

--------------------------------

### Using the REPL Web Component with Vue.js

Source: https://pglite.dev/docs/repl

Example of how to use the PGlite REPL web component within a Vue.js application.

```vue
<script setup>
import { PGlite } from '@electric-sql/pglite'
import '@electric-sql/pglite-repl/webcomponent'

const pg = new PGlite()
</script>
<template>
  <pglite-repl :pg="pg" />
</template>
```

--------------------------------

### .transaction<T>(callback: (tx: Transaction) => Promise<T>)

Source: https://pglite.dev/docs/api

Starts an interactive transaction. The transaction commits if the callback promise resolves and rolls back if it is rejected.

```APIDOC
## .transaction<T>(callback: (tx: Transaction) => Promise<T>)

### Description
Starts an interactive transaction. It is passed a Transaction object which can be used to perform operations within the transaction.

### Parameters
- **callback** (function) - Required - A function that receives a Transaction object and returns a Promise.
```

--------------------------------

### Connecting to the server using Node.js clients

Source: https://pglite.dev/docs/pglite-socket

Examples of connecting to the PGlite server using Node.js clients like node-postgres and postgres.js, including using the DATABASE_URL environment variable.

```javascript
// Using node-postgres
import pg from 'pg'
const client = new pg.Client({
  host: 'localhost',
  port: 5432,
  database: 'postgres',
})
await client.connect()

// Using postgres.js
import postgres from 'postgres'
const sql = postgres({
  host: 'localhost',
  port: 5432,
  database: 'postgres',
})

// Using environment variable (when using --include-database-url)
const sql = postgres(process.env.DATABASE_URL)
```

--------------------------------

### Use Live Incremental Query Hook

Source: https://pglite.dev/docs/framework-hooks/react

Provides reactive re-rendering using efficient diffing for query results. Includes the hook interface definition and a usage example.

```typescript
function useLiveIncrementalQuery<T = { [key: string]: unknown }>(
  query: string,
  params: unknown[] | undefined | null,
  key: string,
): Results<T>
```

```typescript
import { useLiveIncrementalQuery } from '@electric-sql/pglite-react'

const MyComponent = () => {
  const maxNumber = 100
  const items = useLiveIncrementalQuery(`
    SELECT *
    FROM my_table
    WHERE number <= $1
    ORDER BY number;
  `, [maxNumber], 'id')

  return (
    <>
      {
        items.map((item) =>
          <MyItem item={item} />
        )
      }
    </>
  )
}
```

--------------------------------

### live.changes() usage

Source: https://pglite.dev/docs/live-queries

Example of how to use the live.changes() function to get real-time changes from a query.

```typescript
const ret = pg.live.changes(
  'SELECT * FROM test ORDER BY rand;',
  [],
  'id',
  (res) => {
    // res is a change result object
  },
)
```

--------------------------------

### PGlite.create

Source: https://pglite.dev/docs/api

Initializes a new PGlite instance with optional configuration for PostgreSQL parameters and extensions.

```APIDOC
## PGlite.create

### Description
Creates a new PGlite instance. Allows configuration of PostgreSQL parameters via `postgresqlconf` and loading of extensions via the `extensions` object.

### Parameters
- **initDbStartParams** (string[]) - Optional - Array of initialization parameters for the Postgres process.
- **postgresqlconf** (string[] | string) - Optional - Configuration parameters for the PostgreSQL process.
- **extensions** (object) - Optional - A map of namespaces to extension objects for loading WASM builds or client plugins.
```

--------------------------------

### Initialize PGlite with the sync plugin

Source: https://pglite.dev/docs/sync

Initialize a PGlite instance and add the electric sync extension. Also creates a local 'todo' table.

```typescript
import { electricSync } from '@electric-sql/pglite-sync'

const pg = await PGlite.create({
  extensions: {
    electric: electricSync(),
  },
})

await pg.exec $(
  'CREATE TABLE IF NOT EXISTS todo (\n    id SERIAL PRIMARY KEY,\n    task TEXT,\n    done BOOLEAN\n  );'
)
```

--------------------------------

### Initialize PGliteProvider

Source: https://pglite.dev/docs/framework-hooks/react

Wraps the application or component tree with a PGlite database instance to provide context to child components.

```typescript
import { PGlite } from "@electric-sql/pglite"
import { live } from "@electric-sql/pglite/live"
import { PGliteProvider } from "@electric-sql/pglite-react"

const db = await PGlite.create({
  extensions: { live }
})

const App = () => {
  // ...

  return (
    <PGliteProvider db={db}>
      // ...
    </PGliteProvider>
  )
}
```

--------------------------------

### new PGlite(dataDir, options)

Source: https://pglite.dev/docs/api

Standard constructor for creating a new PGlite instance.

```APIDOC
## new PGlite(dataDir, options)

### Description
Instantiates a new PGlite object. Note that this does not automatically await the database initialization.

### Parameters
- **dataDir** (string) - Optional - Path to the directory for storing the Postgres database.
- **options** (PGliteOptions) - Optional - Configuration object for the PGlite instance.
```

--------------------------------

### providePGlite

Source: https://pglite.dev/docs/framework-hooks/vue

Initiates a PGlite database instance and provides it to child components using the Vue provide/inject pattern.

```APIDOC
## providePGlite(db: PGlite)

### Description
Provides a PGlite database instance to the component tree, making it accessible via `injectPGlite` and reactive hooks.

### Parameters
- **db** (PGlite) - Required - The PGlite database instance to provide.
```

--------------------------------

### PGlite.create(dataDir, options)

Source: https://pglite.dev/docs/api

Creates a new PGlite instance asynchronously. This is the preferred method as it ensures the database is fully initialized and supports TypeScript extension namespaces.

```APIDOC
## PGlite.create(dataDir, options)

### Description
Creates a new PGlite instance. Returns a promise that resolves to the initialized PGlite instance.

### Parameters
- **dataDir** (string) - Optional - Path to the directory for storing the Postgres database (e.g., file://, idb://, memory://).
- **options** (PGliteOptions) - Optional - Configuration object for the PGlite instance.

### Options
- **dataDir** (string) - The directory in which to store the database.
- **debug** (1-5) - Postgres debug level.
- **relaxedDurability** (boolean) - If true, does not wait for flushes to storage after each query.
- **fs** (Filesystem) - Custom filesystem instance.
- **loadDataDir** (Blob | File) - Tarball of a PGlite datadir to load on start.
- **extensions** (Extensions) - Object containing extensions to load.
- **username** (string) - Database connection username.
- **database** (string) - Database name to connect to.
- **initialMemory** (number) - Initial memory allocation in bytes.
- **pgliteWasmModule** (WebAssembly.Module) - Precompiled WASM module.
- **initdbWasmModule** (WebAssembly.Module) - Precompiled initdb WASM module.
- **fsBundle** (Blob | File) - Filesystem bundle.
- **parsers** (ParserOptions) - Mapping of Postgres data type IDs to parser functions.
- **serializers** (SerializerOptions) - Mapping of Postgres data type IDs to serializer functions.
- **startParams** (string[]) - Parameters passed to the Postgres process.
- **initDbStartParams** (string[]) - Parameters passed to the initdb process.
```

--------------------------------

### Use template query helpers

Source: https://pglite.dev/docs/api

Utilize identifier, raw, sql, and query helpers to build complex, parameterized SQL queries safely.

```typescript
import { identifier, raw, sql, query } from '@electric-sql/pglite/template'

await pg.sql`SELECT * FROM ${identifier`test`} WHERE name = ${'test'}`
// equivalent of pg.query('SELECT * FROM "test" WHERE name = $1', ['test'])

const filterStmt = (filterVar?: string) =>
  filterVar ? sql`WHERE name = ${filterVar}` : raw`WHERE 1=1`

await pg.sql`SELECT * FROM test ${filterStmt('test')}`
// equivalent of pg.query('SELECT * FROM "test" WHERE name = $1', ['test'])
await pg.sql`SELECT * FROM test ${filterStmt(null)}`
// equivalent of pg.query('SELECT * FROM "test" WHERE 1=1, [])

query`SELECT * FROM ${identifier`test`} WHERE name = ${'test'}`
// { query: 'SELECT * FROM "test" WHERE name = $1', params: ['test'] }
```

--------------------------------

### Initialize PGlite with custom parameters

Source: https://pglite.dev/docs/api

Configures a PGlite instance with specific PostgreSQL initialization parameters.

```typescript
const pg = await PGlite.create({
  initDbStartParams: ['--locale-provider=icu', '--icu-locale=de'],
})
```

--------------------------------

### Import PGlite

Source: https://pglite.dev/docs/api

The main constructor import required for initializing PGlite.

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

--------------------------------

### Load PGlite extensions

Source: https://pglite.dev/docs/api

Registers PGlite client plugins and Postgres extensions during instance creation.

```typescript
import { PGlite } from '@electric-sql/pglite'
import { live } from '@electric-sql/pglite/live'
import { vector } from '@electric-sql/pglite-pgvector'

const pg = await PGlite.create({
  extensions: {
    live, // Live query extension, is a PGlite client plugin
    vector, // Postgres pgvector extension
  },
})

// The `live` namespace is added by the use of the
// `live` key in the `extensions` object.
pg.live.query('...')
```

--------------------------------

### describeQuery

Source: https://pglite.dev/docs/api

Get type information about a query's parameters and result fields without executing it.

```APIDOC
## describeQuery(query: string, options?: QueryOptions): Promise<DescribeQueryResult>

### Description
Get type information about a query's parameters and result fields without executing it. Returns an object containing queryParams and resultFields.
```

--------------------------------

### Initialize PGlite in a Web Worker

Source: https://pglite.dev/docs/multi-tab-worker

Create a worker file that uses the worker wrapper to initialize and expose a PGlite instance.

```javascript
// my-pglite-worker.js
import { PGlite } from '@electric-sql/pglite'
import { worker } from '@electric-sql/pglite/worker'

worker({
  async init() {
    // Create and return a PGlite instance
    return new PGlite()
  },
})
```

--------------------------------

### Define ICU locale filters

Source: https://pglite.dev/docs/localesupport

Example configuration for filtering ICU data to include only specific locales.

```json
{
  "localeFilter": {
    "filterType": "locale",
    "includelist": ["en_US"]
  }
}
```

--------------------------------

### .listen(channel: string, callback: (payload: string) => void)

Source: https://pglite.dev/docs/api

Subscribes to a pg_notify channel.

```APIDOC
## .listen(channel: string, callback: (payload: string) => void)

### Description
Subscribe to a pg_notify channel. The callback will receive the payload from the notification.

### Parameters
- **channel** (string) - Required - The name of the channel to listen to.
- **callback** (function) - Required - Function to execute when a notification is received.

### Returns
- **Promise<(() => Promise<void>)>** - Returns an unsubscribe function.
```

--------------------------------

### Build ICU from source

Source: https://pglite.dev/docs/localesupport

Commands to configure and compile ICU with custom filter settings.

```bash
$ ICU_DATA_FILTER_FILE=<full_path_to_your_filters.json> ./icu/source/configure --with-data-packaging=files --disable-shared --enable-static --disable-tests --disable-samples --disable-extras --disable-icuio --disable-layoutex --prefix=<your_install_dir>

$ make -j && make install
```

--------------------------------

### Prisma schema definition

Source: https://pglite.dev/docs/orm-support

Example Prisma schema definition for a User model.

```prisma
model User {
  id    Int    @id @default(autoincrement())
  email String @unique
  name  String?
}
```

--------------------------------

### Initialize PGlite with ICU resources

Source: https://pglite.dev/docs/localesupport

Configure a PGlite instance by providing the ICU data directory.

```typescript
import { PGlite } from '@electric-sql/pglite'
import { icuDataDir } from '@electric-sql/pglite-icu-full'

// Create a PGlite instance with the icu resources
const pg = await PGlite.create({
  icuDataDir: await icuDataDir(),
})

// just an example, query the available collations
const collations = await pg.exec('select * from pg_collation')
```

--------------------------------

### Usage with PGlite

Source: https://pglite.dev/docs/prepopulatedfs

Create a PGlite instance with the prepopulated FS by loading the data directory.

```typescript
import { PGlite } from '@electric-sql/pglite'
import { dataDir } from '@electric-sql/pglite-prepopulatedfs'

// Create a PGlite instance with the prepopulated FS
const pg = await PGlite.create({
  loadDataDir: await dataDir(),
})
```

--------------------------------

### Initialize worker with Postgres extensions

Source: https://pglite.dev/docs/multi-tab-worker

Load Postgres extensions directly within the worker's init function.

```javascript
// my-pglite-worker.js
import { PGlite } from '@electric-sql/pglite'
import { worker } from '@electric-sql/pglite/worker'
import { vector } from '@electric-sql/pglite-pgvector'

worker({
  async init() {
    return new PGlite({
      extensions: {
        vector,
      },
    })
  },
})
```

--------------------------------

### OPFS AHP FS - Set dataDir

Source: https://pglite.dev/docs/filesystems

The OPFS AHP filesystem is built on top of the Origin Private Filesystem in the browser and uses an "access handle pool". It is only available when PGlite is run in a Web Worker, this could be any worker you configure. We provide a Multi Tab Worker to aid in using PGlite from multiple tabs in the browser. To use the OPFS AHP FS you can use one of these methods: Set the `dataDir` to a directory within the origins OPFS.

```typescript
const pg = new PGlite('opfs-ahp://path/to/datadir/')
```

--------------------------------

### PGliteProvider

Source: https://pglite.dev/docs/framework-hooks/react

The PGliteProvider component initiates a PGlite database instance and provides it to all child components via React context.

```APIDOC
## PGliteProvider

### Description
Wraps child components to provide access to a PGlite database instance.

### Props
- **db** (PGlite) - Required - The PGlite database instance to be provided.
```

--------------------------------

### Orange ORM PGlite usage

Source: https://pglite.dev/docs/orm-support

Example of using Orange ORM with PGlite to create and query tasks.

```javascript
import orange from 'orange-orm'
const db = map.pglite('idb://my-db')

await db.query (
  create table if not exists task (
    id uuid primary key default gen_random_uuid(),
    title text,
    done boolean
  )
)

const map = orange.map((x) => ({ 
  task: x.table('task').map(({ column }) => ({
    id: column('id').uuid().primary(),
    title: column('title').string(),
    done: column('done').boolean(),
  }))
}))

await db.task.insert({ title: 'Write docs', done: false })

const tasks = await db.task.getAll({
  where: (x) => x.done.eq(false),
})
console.log(JSON.stringify(tasks))
```

--------------------------------

### Include the REPL component in a React page

Source: https://pglite.dev/docs/repl

Example of how to include and use the PGlite REPL component in a React application.

```tsx
import { PGlite } from '@electric-sql/pglite'
import { Repl } from '@electric-sql/pglite-repl'

function MyComponent() {
  const pg = new PGlite()

  return (
    <>
      <Repl pg={pg} />
    </>
  )
}
```

--------------------------------

### Prisma database push

Source: https://pglite.dev/docs/orm-support

Command to push Prisma schema changes to the database.

```bash
npx prisma db push
```

--------------------------------

### Provide PGlite instance in Vue

Source: https://pglite.dev/docs/framework-hooks/vue

Initiates a PGlite database instance and provides it to child components using the Vue provide/inject pattern.

```vue
<script lang="ts" setup>
import { PGlite } from '@electric-sql/pglite'
import { providePGlite } from '@electric-sql/pglite-vue'

const db = new PGlite()
providePGlite(db)
</script>
// ...
```

--------------------------------

### Download ICU source and data

Source: https://pglite.dev/docs/localesupport

Commands to fetch the required libicu source and data files for building custom locale sets.

```bash
$ wget https://github.com/unicode-org/icu/releases/download/release-76-1/icu4c-76_1-src.tgz
$ wget https://github.com/unicode-org/icu/releases/download/release-78.3/icu4c-78.3-data.zip
```

--------------------------------

### Access Database with usePGlite

Source: https://pglite.dev/docs/framework-hooks/react

Retrieves the PGlite instance provided by the nearest PGliteProvider context.

```typescript
import { usePGlite } from "@electric-sql/pglite-react"

const MyComponent = () => {
  const db = usePGlite()

  const insertItem = () => {
    db.query("INSERT INTO my_table (name, number) VALUES ('Arthur', 42);")
  }

  return (
    <>
      <button onClick={insertItem}
    </>
  )
}
```

--------------------------------

### IndexedDB FS - Set dataDir

Source: https://pglite.dev/docs/filesystems

The IndexedDB FS persists the database to IndexedDB in the browser. It's a layer over the in-memory filesystem, loading all files for the database into memory on start, and flushing them to IndexedDB after each query if they have changed. To use the IndexedDB FS you can use one of these methods: Set the `dataDir` with a `idb://` prefix, the database will be stored in an IndexedDB named with the path provided.

```typescript
const pg = new PGlite('idb://my-database')
```

--------------------------------

### usePGlite

Source: https://pglite.dev/docs/framework-hooks/react

A hook to retrieve the PGlite database instance provided by the nearest PGliteProvider.

```APIDOC
## usePGlite()

### Description
Retrieves the PGlite instance from the React context.

### Returns
- **db** (PGlite) - The database instance.
```

--------------------------------

### useLiveQuery.sql

Source: https://pglite.dev/docs/framework-hooks/react

A tagged template literal version of useLiveQuery for constructing SQL queries.

```APIDOC
## useLiveQuery.sql`query`

### Description
Allows constructing SQL queries using template literals for the live query hook.
```

--------------------------------

### OPFS AHP FS - Import and pass explicitly

Source: https://pglite.dev/docs/filesystems

To use the OPFS AHP FS you can use one of these methods: Import and pass the FS explicitly

```typescript
import { OpfsAhpFS } from '@electric-sql/pglite/opfs-ahp'
const pg = new PGlite({
  fs: new OpfsAhpFS('./path/to/datadir/'),
})
```

--------------------------------

### Next.js Configuration: Transpile Packages

Source: https://pglite.dev/docs/bundler-support

This configuration snippet shows how to add `@electric-sql/pglite` to the `transpilePackages` array in `next.config.js` for Next.js projects.

```javascript
const nextConfig = {
  swcMinify: false,
  transpilePackages: [
    '@electric-sql/pglite-react', // Optional
    '@electric-sql/pglite',
  ],
}

export default nextConfig
```

--------------------------------

### Package ICU data for PGlite

Source: https://pglite.dev/docs/localesupport

Create a compressed archive of the generated ICU data files.

```bash
$ cd <your_install_dir>/share/icu/76.1/ && tar cvfz icu_76.tgz icudt76l/
```

--------------------------------

### execProtocol

Source: https://pglite.dev/docs/api

Execute a Postgres wire protocol message.

```APIDOC
## execProtocol(message: Uint8Array, options?: ExecProtocolOptions): Promise<Array<[BackendMessage, Uint8Array]>>

### Description
Execute a Postgres wire protocol message, returning an array of tuples, one for each wire protocol result message.
```

--------------------------------

### .exec(query: string, options?: QueryOptions)

Source: https://pglite.dev/docs/api

Executes one or more SQL statements using the simple query Postgres wire protocol. This method does not support parameters and is ideal for migrations or multi-statement scripts.

```APIDOC
## .exec(query: string, options?: QueryOptions)

### Description
Execute one or more statements. Note that parameters are not supported. This is useful for applying database migrations, or running multi-statement SQL that doesn't use parameters.

### Parameters
- **query** (string) - Required - The SQL query string to execute.
- **options** (QueryOptions) - Optional - Configuration options for the query.

### Returns
- **Promise<Array<Results>>** - An array of result objects, one for each statement.
```

--------------------------------

### Configure PGlite worker with metadata

Source: https://pglite.dev/docs/multi-tab-worker

Use the worker wrapper to initialize a PGlite instance with custom metadata passed from the main thread.

```javascript
// my-pglite-worker.js
import { PGlite } from '@electric-sql/pglite'
import { worker } from '@electric-sql/pglite/worker'

worker({
  async init(options) {
    const meta = options.meta
    // Do something with additional metadata.
    // or even run your own code in the leader along side the PGlite
    return new PGlite({
      dataDir: options.dataDir,
    })
  },
})

// my-app.js
import { PGliteWorker } from '@electric-sql/pglite/worker'

const pg = new PGliteWorker(
  new Worker(new URL('./my-pglite-worker.js', import.meta.url), {
    type: 'module',
  }),
  {
    dataDir: 'idb://my-db',
    meta: {
      // additional metadata passed to `init`
    },
  },
)
```

--------------------------------

### Node FS - Set dataDir

Source: https://pglite.dev/docs/filesystems

The Node FS uses the Node.js file system API to implement a VFS for PGLite. It is available in both Node and Bun. To use the Node FS you can use one of these methods: Set the `dataDir` to a directory on your filesystem.

```typescript
const pg = new PGlite('./path/to/datadir/')
```

--------------------------------

### Running npm scripts

Source: https://pglite.dev/docs/pglite-socket

Commands to run the npm scripts defined for PGlite server.

```bash
npm run dev          # Start with persistent database
npm run dev:clean    # Start with in-memory database
```

--------------------------------

### Adding the live extension

Source: https://pglite.dev/docs/live-queries

To use the extension, it needs to be added to the PGlite instance when creating it.

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

const pg = await PGlite.create({
  extensions: {
    live,
  },
})
```

--------------------------------

### IndexedDB FS - Import and pass explicitly

Source: https://pglite.dev/docs/filesystems

To use the IndexedDB FS you can use one of these methods: Import and pass the FS explicitly

```typescript
import { IdbFs } from '@electric-sql/pglite'
const pg = new PGlite({
  fs: new IdbFs('my-database'),
})
```

--------------------------------

### Node FS - Import and pass explicitly

Source: https://pglite.dev/docs/filesystems

To use the Node FS you can use one of these methods: Import and pass the FS explicitly

```typescript
import { NodeFS } from '@electric-sql/pglite'
const pg = new PGlite({
  fs: new NodeFS('./path/to/datadir/'),
})
```

--------------------------------

### useLiveQuery

Source: https://pglite.dev/docs/framework-hooks/react

A hook that executes a SQL query and re-renders the component whenever the query results change.

```APIDOC
## useLiveQuery<T>(query, params)

### Description
Wraps the .live.query() API to provide reactive query results.

### Parameters
- **query** (string) - Required - The SQL query string.
- **params** (unknown[] | undefined | null) - Optional - Parameters for the query.

### Returns
- **Results<T>** - The reactive query results.
```

--------------------------------

### useLiveQuery

Source: https://pglite.dev/docs/framework-hooks/vue

A reactive hook that wraps the .live.query() API to receive updates to query results.

```APIDOC
## useLiveQuery<T>(query, params?)

### Description
Reactively receives updates to the results of a live query.

### Parameters
- **query** (string | WatchSource<string>) - Required - The SQL query string.
- **params** (QueryParams | WatchSource<QueryParams> | WatchSource<unknown>[]) - Optional - Parameters for the query.
```

--------------------------------

### copyToFS

Source: https://pglite.dev/docs/api

Copies data to a file at a specified path in the virtual filesystem.

```APIDOC
## .copyToFS(filePath: string, data: Uint8Array, mode?: number)

### Description
Copies the provided `data` to a file at `filePath` in the virtual filesystem and sets the optional `mode` of the file.

### Example
```typescript
await pg.copyToFS(
  '/tmp/test.txt',
  new TextEncoder().encode('PGlite says hi!'),
  0o0644,
)
```
```
Tokens:
Raw