wasmer/pglite

PostgreSQL 18.4 for WASIX, packaged for Wasmer with an initialized database. PostgreSQL owns its own socket and speaks the standard wire protocol: there is no native server and no protocol proxy. It runs anywhere Wasmer runs — the CLI, the Wasmer SDKs (JavaScript in the browser, Swift on iOS, Python, Rust), and wasmer.sh.

This repository builds PostgreSQL from pinned sources and produces a slim package: 26.8 MB instead of 76.9 MB.

	wasmer/pglite 0.1.3	this build (0.2.0)
Package size	76.9 MB	26.8 MB
Databases	template0, template1, postgres	template1, postgres
WAL	one 16 MiB segment	one 1 MiB segment
Executables on the filesystem	3 (22.9 MB)	none
to_tsvector('english', …)	fails (stop words missing)	works

Run

wasmer run wasmer/pglite --net
psql "postgresql://postgres@127.0.0.1:5432/postgres?sslmode=disable"

--net grants host networking; a package cannot enable it for itself. With a Wasmer SDK:

const wasmer = new Wasmer();
const database = await wasmer.sandboxes.create({
  packages: ["wasmer/pglite@=0.2.0"],
  network: { mode: "http" },
});
await database.command("pglite").spawn();
await database.ports.wait(5432);

This is a single-backend PostgreSQL: it serves one client connection and exits when that client disconnects. The database lives in the sandbox's in-memory copy-on-write layer, so changes are discarded when the sandbox closes.

Build

Requirements: Ubuntu 24.04+ (ARM64 or x86-64, glibc 2.39+) or Apple Silicon macOS, Python 3.11.8+, GNU Make, a C compiler, Perl, Bison, Flex, curl, patch, zic, and PostgreSQL 18's psql and pg_controldata. On macOS install the command-line developer tools and brew install python@3.13 libpq; set PYTHON=python3.13 and add $(brew --prefix libpq)/bin to PATH. On Ubuntu install postgresql-18 from the PGDG repository as shown in the CI workflow.

./build.sh                     # compile sources, initialize and compact the database, package
source build/toolchain.env     # use the pinned Wasmer CLI
./test.sh                      # native psql against the WASIX server
npm ci
npx playwright install chromium firefox webkit
npm test                       # SDK and browser virtual-network integration tests

build.lock.json pins PostgreSQL 18.4, the Oliphaunt source commit and patch stack, wasixcc 0.4.4, LLVM 21.1.206, the WASIX libc sysroot, Wasmer 7.4.2, and wasm-tools. Every downloaded archive is SHA-256 verified, including cached downloads. Tools stay under build/toolchain; the scripts do not change your global compiler installation or shell profile.

The server, initdb, plpgsql, and dict_snowball are compiled together using -sWASM_EXCEPTIONS=exnref. Each module is validated with legacy exceptions and wide arithmetic disabled. The build does not run a binary conversion pass or download an existing PGlite package. The two local patches provide the direct WASIX socket and the sigsetjmp fix from the SDK's PostgreSQL integration.

build.sh then:

1. Creates a new cluster with the package's own initdb, bootstrapped by the module this package ships, using 1 MiB WAL segments.
2. Drops template0 and runs VACUUM FULL on postgres and template1, then starts the server once more so the relcache init file for postgres is written and shipped (fast startup).
3. Removes the WAL segments the last checkpoint does not need, the free space and visibility maps (PostgreSQL rebuilds them on VACUUM), and the statistics files.
4. Removes initdb-only runtime files (postgres.bki, bootstrap SQL, samples) and all executables. PostgreSQL finds its own path through the command Wasmer exposes at /bin/pglite.
5. Includes PostgreSQL's stop word files, time zones, extension metadata, and licenses.

During step 2 PostgreSQL warns that it could not remove the template0 directory; build.sh removes it afterwards.

Outputs are dist/package/, dist/wasmer-pglite-<version>.webc, its SHA-256 checksum, the build lock, and dist/size.json. CI builds from source, runs the CLI and SDK tests, and uploads these artifacts. It does not publish to a registry automatically. Generated binaries, database files, and toolchains are ignored by Git.

Set JOBS=8 to control compilation parallelism or PYTHON=python3.13 to select Python. Unchanged compilation inputs reuse build/runtime; each packaging run creates a fresh cluster. Delete build/ and dist/ for a completely clean build. The process is reproducible from pinned source inputs; the initialized database is not byte-for-byte deterministic because PostgreSQL generates timestamps and a cluster identifier at initialization.

For debugging the packaging step alone, ./build.sh path/to/base.webc can explicitly repack a local package that contains initdb. This mode does not produce the source-build lock artifact. PGLITE_BUILD_PORT and PGLITE_TEST_PORT override the maintenance and test ports.

The browser suite runs the newly built local WEBC with published @wasmer/sdk@0.18.0 and wasmer/psql@18.4.0. It uses separate database/client sandboxes, verifies local TCP without a WebSocket proxy, and checks SQL errors, PL/pgSQL, transactions, JSONB, Unicode, text search, time zones, COPY, large responses, and database creation. Set WASMER_TEST_BROWSERS=chromium to select a browser, or an empty value to run only the Node.js SDK test.

For iOS, use the SDK's WasmerPostgres example with --pglite-webc /absolute/path/to/dist/wasmer-pglite-0.2.0.webc --test. This runs the package in a hidden WKWebView on the iOS 27 simulator and connects through the Swift PostgresNIO client. The SDK example's build instructions cover preparing its web runtime.

What you give up

• template0. CREATE DATABASE works (it copies template1), but CREATE DATABASE … TEMPLATE template0 does not. That affects creating a database with a different encoding or locale, and pg_restore --create / createdb -T template0.
• Initial free space and visibility maps and statistics. They are rebuilt by VACUUM and ANALYZE; until then the planner uses default estimates for the system catalogs.
• ICU locales and optional compression libraries. The slim source build uses PostgreSQL's built-in Unicode/C locales and ships time zone data, but does not bundle ICU, zlib, or TLS. The direct database socket is intended for a local sandbox connection.

The sigsetjmp fix is applied to the server and the rebuilt PL/pgSQL side module. This fixes the BEGIN … EXCEPTION … END crash in 0.1.3. Nested handlers, rethrows, and subtransaction rollback are part of the regular SQL test suite.

Size

Part	Size
PostgreSQL module	10.94 MB
postgres database	6.50 MB
template1 database	6.37 MB
WAL	1.05 MB
Shared catalogs	0.39 MB
Time zones, plpgsql and dict_snowball side modules, text search data, licenses	1.26 MB

License

The build scripts are MIT licensed (see LICENSE). PostgreSQL, including the files in stopwords/, is distributed under the PostgreSQL License (see stopwords/COPYRIGHT). The package is published as MIT AND Apache-2.0 AND PostgreSQL.