or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

database-operations.mdextensions.mdfilesystem-storage.mdindex.mdlive-queries.mdsql-templates.mdvector-operations.mdworker-support.md
tile.json

tessl/npm-electric-sql--pglite

PGlite is a WASM Postgres build packaged into a TypeScript client library that enables you to run Postgres in the browser, Node.js and Bun, with no need to install any other dependencies.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@electric-sql/pglite@0.3.x

To install, run

npx @tessl/cli install tessl/npm-electric-sql--pglite@0.3.0

index.mddocs/

PGlite

PGlite is a WASM Postgres build packaged into a TypeScript client library that enables you to run Postgres in the browser, Node.js and Bun, with no need to install any other dependencies. It is only 3.7mb gzipped and provides a complete PostgreSQL database implementation with both ephemeral in-memory database capabilities and persistent storage options.

Package Information

  • Package Name: @electric-sql/pglite
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @electric-sql/pglite

Core Imports

import { PGlite } from "@electric-sql/pglite";

For CommonJS:

const { PGlite } = require("@electric-sql/pglite");

Additional exports:

import { 
  MemoryFS, 
  IdbFs, 
  uuid, 
  formatQuery, 
  types, 
  parse,
  messages,
  protocol,
  Mutex
} from "@electric-sql/pglite";
  • MemoryFS, IdbFs - Filesystem implementations
  • uuid, formatQuery - Utility functions
  • types, parse - Type system and parsing utilities
  • messages, protocol - PostgreSQL wire protocol utilities from @electric-sql/pg-protocol
  • Mutex - Concurrency control from async-mutex

Basic Usage

import { PGlite } from "@electric-sql/pglite";

// Create an in-memory database
const db = new PGlite();

await db.waitReady;

// Create a table and insert data
await db.exec(`
  CREATE TABLE IF NOT EXISTS todo (
    id SERIAL PRIMARY KEY,
    task TEXT,
    done BOOLEAN DEFAULT false
  );
`);

// Insert data
await db.query("INSERT INTO todo (task, done) VALUES ($1, $2)", [
  "Learn PGlite",
  false,
]);

// Query data
const results = await db.query("SELECT * FROM todo WHERE done = $1", [false]);
console.log(results.rows);

// Close the database
await db.close();

Architecture

PGlite is built around several key components:

  • Core Database: PGlite class providing the main database interface with full PostgreSQL compatibility
  • Filesystem Layer: Multiple filesystem implementations (MemoryFS, IdbFs, NodeFS, OpfsAhpFS) for different storage backends
  • Extension System: Pluggable architecture supporting PostgreSQL extensions like pgvector, live queries, and contrib modules
  • Template System: SQL template literals with safe parameter interpolation and query composition
  • Worker Support: Multi-tab shared database access through worker threads
  • Type System: Complete PostgreSQL type mapping with customizable parsers and serializers

Capabilities

Core Database Operations

Main database class providing PostgreSQL query execution, transaction management, and database lifecycle operations.

class PGlite {
  constructor(dataDir?: string, options?: PGliteOptions);
  constructor(options?: PGliteOptions);
  
  readonly waitReady: Promise<void>;
  readonly ready: boolean;
  readonly closed: boolean;
  readonly dataDir?: string;
  
  query<T>(query: string, params?: any[], options?: QueryOptions): Promise<Results<T>>;
  sql<T>(strings: TemplateStringsArray, ...params: any[]): Promise<Results<T>>;
  exec(query: string, options?: QueryOptions): Promise<Array<Results>>;
  transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T>;
  close(): Promise<void>;
}

interface Results<T = Record<string, any>> {
  rows: Row<T>[];
  affectedRows?: number;
  fields: { name: string; dataTypeID: number }[];
  blob?: Blob;
}

Database Operations

Filesystem Storage

Multiple filesystem implementations for different environments and persistence requirements.

class MemoryFS implements Filesystem {
  constructor();
}

class IdbFs implements Filesystem {
  constructor(dataDir: string);
}

interface Filesystem {
  readonly fsType: FsType;
  syncToFs(mod: any): Promise<void>;
  dumpTar(mod: any, compression?: DumpTarCompressionOptions): Promise<File | Blob>;
}

Filesystem Storage

SQL Template System

Safe SQL query composition with template literals and parameter interpolation.

function sql(strings: TemplateStringsArray, ...values: any[]): TemplateContainer;
function query(strings: TemplateStringsArray, ...values: any[]): TemplatedQuery;
function identifier(strings: TemplateStringsArray, ...values: any[]): TemplatePart;
function raw(strings: TemplateStringsArray, ...values: any[]): TemplatePart;

SQL Templates

Live Query System

Real-time query results with automatic updates when underlying data changes.

interface LiveNamespace {
  query<T>(query: string, params?: any[], key?: string): Promise<LiveQuery<T>>;
  incrementalQuery<T>(query: string, params?: any[], key?: string): Promise<LiveQuery<T>>;
  changes<T>(query: string, params?: any[], key?: string): Promise<LiveChanges<T>>;
}

interface LiveQuery<T> {
  initialResults: Results<T>;
  refresh(): Promise<Results<T>>;
  unsubscribe(): Promise<void>;
}

Live Queries

Worker Support

Multi-tab shared database access through dedicated or shared worker threads.

class PGliteWorker extends BasePGlite {
  constructor(worker: Worker, options?: PGliteWorkerOptions);
}

function worker(options?: WorkerOptions): void;

Worker Support

Extension System

Pluggable architecture for adding PostgreSQL extensions and custom functionality.

interface Extension<T = any> {
  name: string;
  setup: ExtensionSetup<T>;
}

type ExtensionSetup<TNamespace = any> = (
  pg: PGliteInterface,
  emscriptenOpts: any,
  clientOnly?: boolean
) => Promise<ExtensionSetupResult<TNamespace>>;

Extensions

Vector Operations

PostgreSQL pgvector extension for vector similarity search and operations.

const vector: Extension;

Vector Operations

Types

interface PGliteOptions<TExtensions = Record<string, Extension>> {
  dataDir?: string;
  username?: string;
  database?: string;
  fs?: Filesystem;
  debug?: DebugLevel;
  relaxedDurability?: boolean;
  extensions?: TExtensions;
  loadDataDir?: Blob | File;
  initialMemory?: number;
  wasmModule?: WebAssembly.Module;
  fsBundle?: Blob | File;
  parsers?: ParserOptions;
  serializers?: SerializerOptions;
  defaultDataTransferContainer?: DataTransferContainer;
}

interface QueryOptions {
  rowMode?: 'array' | 'object';
  parsers?: ParserOptions;
  serializers?: SerializerOptions;
  blob?: Blob | File;
  onNotice?: (notice: NoticeMessage) => void;
  paramTypes?: number[];
}

type DebugLevel = 0 | 1 | 2 | 3 | 4 | 5;
type Row<T> = T extends Record<string, any> ? T : Record<string, any>;
type DataTransferContainer = 'cma' | 'file';