Update readme (#167)

samwillis · web-flow · commit 0892666d97f0 · 2024-08-12T09:30:10.000+01:00
diff --git a/README.md b/README.md
@@ -33,7 +33,7 @@
 
 ![PGlite](https://raw.githubusercontent.com/electric-sql/pglite/main/screenshot.png)
 
-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 2.6mb gzipped.
+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 3mb gzipped and has support for many Postgres extensions, including [pgvector](https://github.com/pgvector/pgvector).
 
 ```javascript
 import { PGlite } from "@electric-sql/pglite";
@@ -47,23 +47,7 @@ It can be used as an ephemeral in-memory database, or with persistence either to
 
 Unlike previous "Postgres in the browser" projects, PGlite does not use a Linux virtual machine - it is simply Postgres in WASM.
 
-It is being developed at [ElectricSQL](http://electric-sql.com) in collaboration with [Neon](http://neon.tech). We will continue to build on this experiment with the aim of creating a fully capable lightweight WASM Postgres with support for extensions such as pgvector.
-
-## Whats new in V0.1
-
-Version 0.1 (up from 0.0.2) includes significant changes to the Postgres build - it's about 1/3 smaller at 2.6mb gzipped, and up to 2-3 times faster. We have also found a way to statically compile Postgres extensions into the build - the first of these is pl/pgsql with more coming soon.
-
-Key changes in this release are:
-
-- Support for [parameterised queries](#querytquery-string-params-any-options-queryoptions-promiseresultst) #39
-- An interactive [transaction API](#transactiontcallback-tx-transaction--promiset) #39
-- pl/pgsql support #48
-- Additional [query options](#queryoptions) #51
-- Run PGlite in a [Web Workers](#web-workers) #49
-- Fix for running on Windows #54
-- Fix for missing `pg_catalog` and `information_schema` tables and view #41
-
-We have also [published some benchmarks](https://github.com/electric-sql/pglite/blob/main/packages/benchmark/README.md) in comparison to a WASM SQLite build, and both native Postgres and SQLite. While PGlite is currently a little slower than WASM SQLite we have plans for further optimisations, including OPFS support and removing some the the Emscripten options that can add overhead.
+For full documentation and user guides see [pglite.dev](https://pglite.dev).
 
 ## Browser
 
@@ -116,201 +100,6 @@ or to persist to the filesystem:
 const db = new PGlite("./path/to/pgdata");
 ```
 
-## Deno
-
-To use the in-memory Postgres, create a file `server.ts`:
-
-```typescript
-import { PGlite } from "npm:@electric-sql/pglite";
-
-Deno.serve(async (_request: Request) => {
-  const db = new PGlite();
-  const query = await db.query("select 'Hello world' as message;");
-
-  return new Response(JSON.stringify(query));
-});
-```
-
-Then run the file with `deno run --allow-net --allow-read server.ts`.
-
-## API Reference  
-
-### Main Constructor:
-
-#### `new PGlite(dataDir: string, options: PGliteOptions)`
-
-A new pglite instance is created using the `new PGlite()` constructor.
-
-##### `dataDir`
-
-Path to the directory to store the Postgres database. You can provide a url scheme for various storage backends:
-
-- `file://` or unprefixed: File system storage, available in Node and Bun.
-- `idb://`: IndexedDB storage, available in the browser.
-- `memory://`: In-memory ephemeral storage, available in all platforms.
-
-##### `options`:
-
-- `debug`: 1-5 - the Postgres debug level. Logs are sent to the console.
-- `relaxedDurability`: boolean - under relaxed durability mode PGlite will not wait for flushes to storage to complete when using the indexedDB file system.
-
-### Methods:
-
-#### `.query<T>(query: string, params?: any[], options?: QueryOptions): Promise<Results<T>>`
-
-Execute a single statement, optionally with parameters.
-
-Uses the *extended query* Postgres wire protocol.
-
-Returns single [result object](#results-objects).
-
-##### Example:
-
-```ts
-await pg.query(
-  'INSERT INTO test (name) VALUES ($1);',
-  [ 'test' ]
-);
-// { affectedRows: 1 },
-```
-
-##### QueryOptions:
-
-The `query` and `exec` methods take an optional `options` objects with the following parameters:
-
-- `rowMode: "object" | "array"`
-  The returned row object type, either an object of `fieldName: value` mappings or an array of positional values. Defaults to `"object"`.
-- `parsers: ParserOptions`
-  An object of type  `{[[pgType: number]: (value: string) => any;]}` mapping Postgres data type id to parser function.
-  For convenance the `pglite` package exports a const for most common Postgres types:
-
-  ```ts
-  import { types } from "@electric-sql/pglite";
-  await pg.query(`
-    SELECT * FROM test WHERE name = $1;
-  `, ["test"], {
-    rowMode: "array",
-    parsers: {
-      [types.TEXT]: (value) => value.toUpperCase(),
-    }
-  });
-  ```
-
-#### `.exec(query: string, options?: QueryOptions): Promise<Array<Results>>`
-
-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.
-
-Uses the *simple query* Postgres wire protocol.
-
-Returns array of [result objects](#results-objects), one for each statement.
-
-##### Example:
-
-```ts
-await pg.exec(`
-  CREATE TABLE IF NOT EXISTS test (
-    id SERIAL PRIMARY KEY,
-    name TEXT
-  );
-  INSERT INTO test (name) VALUES ('test');
-  SELECT * FROM test;
-`);
-// [
-//   { affectedRows: 0 },
-//   { affectedRows: 1 },
-//   {
-//     rows: [
-//       { id: 1, name: 'test' }
-//     ]
-//     affectedRows: 0,
-//     fields: [
-//       { name: 'id', dataTypeID: '23' },
-//       { name: 'name', dataTypeID: '25' },
-//     ]
-//   }
-// ]
-```
-
-#### `.transaction<T>(callback: (tx: Transaction) => Promise<T>)`
-
-To start an interactive transaction pass a callback to the transaction method. It is passed a `Transaction` object which can be used to perform operations within the transaction.
-
-##### `Transaction` objects:
-
-- `tx.query<T>(query: string, params?: any[], options?: QueryOptions): Promise<Results<T>>`
-  The same as the main [`.query` method](#querytquery-string-params-any-promiseresultst).
-- `tx.exec(query: string, options?: QueryOptions): Promise<Array<Results>>`
-  The same as the main [`.exec` method](#execquery-string-promisearrayresults).
-- `tx.rollback()`
-  Rollback and close the current transaction.
-
-##### Example:
-
-```ts
-await pg.transaction(async (tx) => {
-  await tx.query(
-    'INSERT INTO test (name) VALUES ('$1');',
-    [ 'test' ]
-  );
-  return await ts.query('SELECT * FROM test;');
-});
-```
-
-#### `.close(): Promise<void>`
-
-Close the database, ensuring it is shut down cleanly.
-
-### Properties:
-
-- `.ready` *boolean (read only)*: Whether the database is ready to accept queries.
-- `.closed` *boolean (read only)*: Whether the database is closed and no longer accepting queries.
-- `.waitReady` *Promise<void>*: Promise that resolves when the database is ready to use. Note that queries will wait for this if called before the database has fully initialised, and so it's not necessary to wait for it explicitly.
-
-### Results<T> Objects:
-
-Result objects have the following properties:
-
-- `rows: Row<T>[]` - The rows retuned by the query
-- `affectedRows?: number` - Count of the rows affected by the query. Note this is *not* the count of rows returned, it is the number or rows in the database changed by the query.
--  `fields: { name: string; dataTypeID: number }[]` - Field name and Postgres data type ID for each field returned.
-
-
-### Row<T> Objects:
-
-Rows objects are a key / value mapping for each row returned by the query.
-
-The `.query<T>()` method can take a TypeScript type describing the expected shape of the returned rows. *(Note: this is not validated at run time, the result only cast to the provided type)*
-
-### Web Workers:
-
-It's likely that you will want to run PGlite in a Web Worker so that it doesn't block the main thread. To aid in this we provide a `PGliteWorker` with the same API as the core `PGlite` but it runs Postgres in a dedicated Web Worker. To use, import from the `/worker` export:
-
-```js
-import { PGliteWorker } from "@electric-sql/pglite/worker";
-
-const pg = new PGliteWorker('idb://my-database');
-await pg.exec(`
-  CREATE TABLE IF NOT EXISTS test (
-    id SERIAL PRIMARY KEY,
-    name TEXT
-  );
-`);
-```
-
-*Work in progress: We plan to expand this API to allow sharing of the worker PGlite across browser tabs.*
-
-## Extensions
-
-PGlite supports the pl/pgsql procedural language extension, this is included and enabled by default.
-
-In future we plan to support additional extensions, see the [roadmap](#roadmap).
-
-## ORM support.
-
-- Drizzle ORM supports PGlite, see [their docs here](https://orm.drizzle.team/docs/get-started-postgresql#pglite).
-
 ## How it works
 
 PostgreSQL typically operates using a process forking model; whenever a client initiates a connection, a new process is forked to manage that connection. However, programs compiled with Emscripten - a C to WebAssembly (WASM) compiler - cannot fork new processes, and operates strictly in a single-process mode. As a result, PostgreSQL cannot be directly compiled to WASM for conventional operation.
@@ -321,48 +110,6 @@ Fortunately, PostgreSQL includes a "single user mode" primarily intended for com
 
 - PGlite is single user/connection.
 
-## Roadmap
-
-PGlite is *Alpha* and under active development, the current roadmap is:
-
-- CI builds [#19](https://github.com/electric-sql/pglite/issues/19)
-- Support Postgres extensions, starting with:
-  - pgvector [#18](https://github.com/electric-sql/pglite/issues/18)
-  - PostGIS [#11](https://github.com/electric-sql/pglite/issues/11)
-- OPFS support in browser [#9](https://github.com/electric-sql/pglite/issues/9)
-- Muti-tab support in browser [#32](https://github.com/electric-sql/pglite/issues/32)
-- Syncing via [ElectricSQL](https://electric-sql.com) with a Postgres server [electric/#1058](https://github.com/electric-sql/electric/pull/1058) 
-
-## Repository Structure
-
-The PGlite project is split into two parts:
-
-- `/packages/pglite`
-  The TypeScript package for PGlite
-- `/postgres` _(git submodule)_
-  A fork of Postgres with changes to enable compiling to WASM:
-  [/electric-sql/postgres-wasm](https://github.com/electric-sql/postgres-wasm)
-
-Please use the [issues](https://github.com/electric-sql/pglite/issues/) in this main repository for filing issues related to either part of PGlite. Changes that affect both the TypeScript package and the Postgres source should be filed as two pull requests - one for each repository, and they should reference each other.
-
-## Building
-
-There are a couple of prerequisites:
-
-- the Postgres build toolchain - https://www.postgresql.org/download/
-- emscripten version 3.1.56 - https://emscripten.org/docs/getting_started/downloads.html
-
-To build, checkout the repo, then:
-
-```
-git submodule update --init
-cd ./pglite/packages/pglite
-emsdk install 3.1.56
-emsdk activate 3.1.56
-pnpm install
-pnpm build
-```
-
 ## Acknowledgments
 
 PGlite builds on the work of [Stas Kelvich](https://github.com/kelvich) of [Neon](https://neon.tech) in this [Postgres fork](https://github.com/electric-sql/postgres-wasm).
diff --git a/packages/pglite-react/README.md b/packages/pglite-react/README.md
@@ -0,0 +1,16 @@
+# PGlite React.js Hooks
+
+This package implements React hooks for [PGLite](https://pglite.dev/) on top of the [live query plugin](https://pglite.dev/docs/live-queries). Full documentation is available at [pglite.dev/docs/framework-hooks](https://pglite.dev/docs/framework-hooks#react).
+
+To install:
+
+```sh
+npm install @electric-sql/pglite-react
+```
+
+The hooks this package provides are:
+
+- [PGliteProvider](https://pglite.dev/docs/framework-hooks#pgliteprovider): A Provider component to pass a PGlite instance to all child components for use with the other hooks.
+- [usePGlite](https://pglite.dev/docs/framework-hooks#usepglite): Retrieve the provided PGlite instance.
+- [useLiveQuery](https://pglite.dev/docs/framework-hooks#uselivequery): Reactively re-render your component whenever the results of a live query change
+- [useLiveIncrementalQuery](https://pglite.dev/docs/framework-hooks#useliveincrementalquery): Reactively re-render your component whenever the results of a live query change by offloading the diff to PGlite
diff --git a/packages/pglite-sync/README.md b/packages/pglite-sync/README.md
@@ -0,0 +1,39 @@
+# PGlite ElectricSQL Sync Plugin
+
+A [sync plugin](https://pglite.dev/docs/sync) for [PGlite](https://pglite.dev/) using [ElectricSQL](https://electric-sql.com/). Full documentation is available at [pglite.dev/docs/sync](https://pglite.dev/docs/sync).
+
+To install:
+
+```sh
+npm install @electric-sql/pglite-sync
+```
+
+Then add it to you PGlite instance and create any local tables needed:
+
+```ts
+import { electricSync } from '@electric-sql/pglite-sync'
+
+const pg = await PGlite.create({
+  extensions: {
+    electric: electricSync(),
+  },
+})
+
+await pg.exec(`
+  CREATE TABLE IF NOT EXISTS todo (
+    id SERIAL PRIMARY KEY,
+    task TEXT,
+    done BOOLEAN
+  );
+`)
+```
+
+You can then use the syncShapeToTable method to sync a table from Electric:
+
+```ts
+const shape = await pg.electric.syncShapeToTable({
+  url: 'http://localhost:3000/v1/shape/todo',
+  table: 'todo',
+  primaryKey: ['id'],
+})
+```
diff --git a/packages/pglite/README.md b/packages/pglite/README.md
