Skip to content

Commit

Permalink
Mention pglite
Browse files Browse the repository at this point in the history
  • Loading branch information
N2D4 committed Apr 2, 2024
1 parent ffa00f2 commit 6de833d
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 2 deletions.
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,13 @@ mock.destroy();

`pgmock` fully supports browser environments. While webapps can't listen to TCP ports, you can still use `PostgresMock.createSocket` and the `node-postgres` configuration. However, if your bundler statically analyzes imports, the default configuration may throw an error because of missing Node.js modules. Check `examples/web-demo/next.config.mjs` for an example on how to configure Webpack for bundling.

If your primary use case is to run a database in the browser (and only the browser), you might want to consider [pglite](https://github.com/electric-sql/pglite) instead. It is more performant and lightweight (with a limited feature set). `pgmock` is designed for full compatibility with production PostgreSQL environments, as you would want in a testing environment.

## How does it work?

There are two approaches to run Postgres in WebAssembly; by [forking it to support WASM natively](https://github.com/electric-sql/postgres-wasm) or by [emulating the Postgres server in an x86 emulator](https://supabase.com/blog/postgres-wasm). The former is more performant and uses considerably less memory, but only supports single-user mode (no connections), and cannot use any extensions.

To prevent discrepancies between testing and production, and because performance is not usually a concern in tests, `pgmock` currently uses the latter approach. In the mid-term future, once native Postgres WASM forks mature, we plan to switch to that approach. We don't expect there to be many breaking changes besides the APIs inside `PostgresMock.subtle`.
To prevent discrepancies between testing and production, and because performance is not usually a concern in tests, `pgmock` currently uses the latter approach. In the mid-term future, once native Postgres WASM forks mature, we plan to switch to that. We don't expect there to be many breaking changes besides the APIs inside `PostgresMock.subtle`.

`pgmock` differs from previous Postgres-in-the-browser projects by providing full feature-compatibility entirely inside the JavaScript runtime, without depending on a network proxy for communication. We did this by simulating a network stack in JavaScript that behaves like a real network, that can simulate TCP connections even on platforms that do not allow raw socket access.

Expand Down
8 changes: 7 additions & 1 deletion examples/web-demo/src/app/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,13 @@ export default function Home() {
color: "grey",
fontSize: "0.8em",
}}>
It is designed for use in unit and E2E testing, but can run standalone in-memory in a browser. For more information, check the repository linked above.
It is designed for use in unit and E2E testing, but can run standalone in-memory in a browser. For more information, check the <Link href="https://github.com/stackframe-projects/pgmock" target="_blank" rel="noopener noreferrer">pgmock repository</Link>.
</p>
<p style={{
color: "grey",
fontSize: "0.8em",
}}>
If your primary use case is to run a database in the browser (and only the browser), you might want to consider <Link href="https://github.com/electric-sql/pglite" target="_blank" rel="noopener noreferrer">pglite</Link> instead. It is more performant and lightweight (with a limited feature set). pgmock is designed for full compatibility with production PostgreSQL environments, as you would want in a testing environment.
</p>
<h2>node-postgres Queries</h2>
<div>
Expand Down

0 comments on commit 6de833d

Please sign in to comment.