From 583a1a143a1d51465a8f10fa3931c8e7236ce062 Mon Sep 17 00:00:00 2001 From: Sam Willis Date: Thu, 8 Aug 2024 13:03:10 +0100 Subject: [PATCH] Address feedback --- docs/benchmarks.md | 4 ++-- docs/docs/about.md | 2 +- docs/docs/api.md | 10 +++++----- docs/docs/filesystems.md | 4 ++-- docs/docs/index.md | 3 ++- docs/docs/multi-tab-worker.md | 2 +- docs/index.md | 4 ++-- 7 files changed, 15 insertions(+), 14 deletions(-) diff --git a/docs/benchmarks.md b/docs/benchmarks.md index 60b2b95e..81be7010 100644 --- a/docs/benchmarks.md +++ b/docs/benchmarks.md @@ -18,11 +18,11 @@ # Benchmarks -There are two sets of micro-benchmarks: one testing [round trip time](#round-trip-time-benchmarks) for both PGlite and wa-sqlite, and [another](#sqlite-benchmark-suite) the other based on the [SQLite speed test](https://sqlite.org/src/file?name=tool/speedtest.tcl&ci=trunk) which was ported for the [wa-sqlite benchmarks](https://rhashimoto.github.io/wa-sqlite/demo/benchmarks.html). +There are two sets of micro-benchmarks: one testing [round trip time](#round-trip-time-benchmarks) for both PGlite and wa-sqlite, and [another one](#sqlite-benchmark-suite) based on the [SQLite speed test](https://sqlite.org/src/file?name=tool/speedtest.tcl&ci=trunk) which was ported for the [wa-sqlite benchmarks](https://rhashimoto.github.io/wa-sqlite/demo/benchmarks.html). We also have a set of [native baseline](#native-baseline) results comparing native SQLite (via the Node better-sqlite3 package) to full Postgres. -Comparing Postgres to SQlite is challenging, as they are quite different databases, particularly when you take into account the complexities of WASM. Therefore, these benchmarks provide a view of performance only as a starting point to investigate the difference between the two, and the improvements we can make going forward. +Comparing Postgres to SQLite is challenging, as they are quite different databases, particularly when you take into account the complexities of WASM. Therefore, these benchmarks provide a view of performance only as a starting point to investigate the difference between the two, and the improvements we can make going forward. Another consideration when analysing the speed, is the performance of the various different VFS implementations providing persistance to both PGlite and wa-sqlite. diff --git a/docs/docs/about.md b/docs/docs/about.md index 19c819f3..74f8a0b1 100644 --- a/docs/docs/about.md +++ b/docs/docs/about.md @@ -16,7 +16,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's being developed by [ElectricSQL](https://electric-sql.com/) for our use case of embedding into applications, either locally or at the edge, allowing users to sync a subset of their Postgres database. +It's being developed by [ElectricSQL](https://electric-sql.com/) for our use case of embedding into applications, either locally or at the edge, allowing users to sync a subset of their server-side Postgres database. However, there are many more use cases for PGlite beyond its use as an embedded application database: diff --git a/docs/docs/api.md b/docs/docs/api.md index 347e29d0..6a79ae61 100644 --- a/docs/docs/api.md +++ b/docs/docs/api.md @@ -88,7 +88,7 @@ Execute a single statement, optionally with parameters. Uses the _extended query_ Postgres wire protocol. -Returns single [result object](#results-objects). +Returns single [result object](#results-t-objects). ##### Example @@ -124,7 +124,7 @@ The `query` and `exec` methods take an optional `options` objects with the follo ``` - `blob: Blob | File`
- Attach a `Blob` or `File` object to the query that can used with a `COPY FROM` command by using the virtual `/dev/blob` device, see [importing and exporting](#importing-and-exporting-with-copy-tofrom). + Attach a `Blob` or `File` object to the query that can used with a `COPY FROM` command by using the virtual `/dev/blob` device, see [importing and exporting](#dev-blob). ### exec @@ -136,7 +136,7 @@ This is useful for applying database migrations, or running multi-statement SQL Uses the _simple query_ Postgres wire protocol. -Returns array of [result objects](#results-objects); one for each statement. +Returns array of [result objects](#results-t-objects); one for each statement. ##### Example @@ -290,8 +290,8 @@ Result objects have the following properties: - `fields: { name: string; dataTypeID: number }[]`
Field name and Postgres data type ID for each field returned. -- `blob: Blob`
- A `Blob` containing the data written to the virtual `/dev/blob/` device by a `COPY TO` command. See [/dev/blob](#devblob). +- `blob?: Blob`
+ A `Blob` containing the data written to the virtual `/dev/blob/` device by a `COPY TO` command. See [/dev/blob](#dev-blob). ## `Row` Objects diff --git a/docs/docs/filesystems.md b/docs/docs/filesystems.md index 9de17745..9c3be146 100644 --- a/docs/docs/filesystems.md +++ b/docs/docs/filesystems.md @@ -76,7 +76,7 @@ To use the IndexedDB FS you can use one of these methods: }) ``` -The IndexedDB filesystem works at the file level, storing whole files as blobs in IndexedDB. Flushing whole files can take a few milliseconds after each query. To aid in building responsive apps we provide a `relaxedDurability` mode that can be [configured when starting](./api.md#options) PGlite. Under this mode, the results of a query are returned immediately, and the flush to IndexedDB is scheduled to occur asynchronously afterwards. Typically, this is immediately after the query returns with no delay. +The IndexedDB filesystem works at the file level, storing whole files (Postgres has a single file per table or index) as blobs in IndexedDB. Flushing whole files can take a few milliseconds after each query. To aid in building responsive apps we provide a `relaxedDurability` mode that can be [configured when starting](./api.md#options) PGlite. Under this mode, the results of a query are returned immediately, and the flush to IndexedDB is scheduled to occur asynchronously afterwards. Typically, this is immediately after the query returns with no delay. ### Platform Support @@ -86,7 +86,7 @@ The IndexedDB filesystem works at the file level, storing whole files as blobs i ## OPFS AHP FS -The OPFS AHP filesystem is built on top of the [Origin Private Filesystem](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system) 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, however we provide a [Multi Tab Worker](./multi-tab-worker.md) to aid in using PGlite from multiple tabs in the browser. +The OPFS AHP filesystem is built on top of the [Origin Private Filesystem](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system) 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](./multi-tab-worker.md) to aid in using PGlite from multiple tabs in the browser. To use the OPFS AHP FS you can use one of these methods: diff --git a/docs/docs/index.md b/docs/docs/index.md index 5b9f3808..f933a8d8 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -100,6 +100,7 @@ console.log(ret.rows)[ { id: 1, task: 'Install PGlite from NPM', + done: false, } ] ``` @@ -133,6 +134,6 @@ const ret = await db.query( - We maintain a [list of ORMs and query builders](./orm-support.md) that support PGlite. -- PGlite supports both Postgres extensions and PGlite Plugins via its [extensions API](./api.md#optionsextensions), and there is a list of [supported extensions](../extensions/). +- PGlite supports both Postgres extensions and PGlite Plugins via its [extensions API](./api.md#options-extensions), and there is a list of [supported extensions](../extensions/). - We have a [page of examples](../examples.md) that you can open to test out PGlite in the browser. diff --git a/docs/docs/multi-tab-worker.md b/docs/docs/multi-tab-worker.md index 6640afd0..f64a9b9e 100644 --- a/docs/docs/multi-tab-worker.md +++ b/docs/docs/multi-tab-worker.md @@ -56,7 +56,7 @@ In addition to having all the standard methods of the [`PGlite` interface](./api - `meta: any`
Any additional metadata you would like to pass to the worker process `init` function. -The `worker()` wrapper takes a single options argument, with a single `init` property. `init` is a function takes any options passed to `PGliteWorker`, excluding extensions, and returns a `PGlite` instance. You can use the options passed to decide how to configure your instance: +The `worker()` wrapper takes a single options argument, with a single `init` property. `init` is a function that takes any options passed to `PGliteWorker`, excluding extensions, and returns a `PGlite` instance. You can use the options passed to decide how to configure your instance: ```js // my-pglite-worker.js diff --git a/docs/index.md b/docs/index.md index 58295855..8d0e8e23 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,7 +5,7 @@ layout: home hero: name: 'PGlite' text: 'Embeddable Postgres' - tagline: 'WASM Postgres with reactivity and sync' + tagline: 'Run a full Postgres database locally in your app with reactivity and server sync' actions: - theme: brand text: Getting Started @@ -22,7 +22,7 @@ hero: features: - title: Lightweight - details: Pure WASM build of Postgres using Emscripten that's under 3MB Gzipped. + details: A complete WASM build of Postgres that's under 3MB Gzipped. - title: Extendable details: Dynamic extension loading mechanism, including support for pgvector and PostGIS. - title: Reactive