@di-framework/pglite-component 6.0.15 → 6.0.17

package/README.md

@@ -1,6 +1,6 @@
 # di-framework:pglite — embedded PostgreSQL over WIT
 
-The provider bundles the PGlite PostgreSQL 17.5 engine into a WebAssembly
+The provider bundles a PostgreSQL 17.11 engine, built for WASI, into a WebAssembly
 component. SQL calls cross WIT and WebAssembly memory. There is no TCP listener,
 network client, native sidecar, or separate database service.
 
@@ -59,6 +59,24 @@ is cached under `target/engine`. Containers are build tools only; deployment
 runs the resulting `.wasm` directly. For a remote Podman daemon, set the task's
 `DOCKER_CONTEXT=podman`.
 
+### Engine source
+
+The engine is upstream PostgreSQL `REL_17_11` with ElectricSQL's PGlite WASI
+changes replayed onto it. Electric maintains no WASI branch past 17.5 (its newer
+branches are Emscripten-only), so the 17.5 WASI changes are carried as
+[`engine/patches/postgresql-17.11-wasi.patch`](engine/patches/README.md)
+(PostgreSQL License). `scripts/build-engine.ts` fetches the tag pinned in
+`scripts/tool-versions.env` (`POSTGRES_SOURCE_TAG`), refuses it unless it
+resolves to `POSTGRES_SOURCE_COMMIT`, and applies that patch and then the
+[wasipg](https://github.com/moznion/wasipg) recipe's sjlj patches, checking each
+before applying it. `scripts/patch-engine-source.ts` adds the di-framework
+changes described in `engine/NOTICE`.
+
+`make check-engine-patch` runs all of those steps without the container build,
+in about 30 seconds. Run it first after bumping the PostgreSQL release: a patch
+that no longer applies fails with its name, the base, and git's output. Then
+follow [engine/patches/README.md](engine/patches/README.md).
+
 The build embeds the support filesystem, adapts the engine's WASI Preview 1
 imports to Preview 2, and composes the engine with the Rust database provider.
 It fails if the final artifact imports sockets or leaves the engine unresolved.
@@ -98,13 +116,21 @@ and persistence across separate runtime processes. It also exits a runtime
 with an open transaction and verifies that committed rows survive and the
 uncommitted row is absent after restart. No scripted database server is used.
 
+`make smoke` also checks upgrades from the previous release. It downloads the
+published `@di-framework/pglite-component` tarball pinned as
+`PGLITE_UPGRADE_FROM_*` in `scripts/tool-versions.env` (6.0.15, PostgreSQL
+17.5) and checks its sha256. Its provider writes a data directory with a table,
+pgcrypto and PGP ciphertext. The new build must then open that directory,
+report 17.11, read the rows, decrypt the old ciphertext, run pgcrypto on new
+values, and write to it.
+
 ## Publishing to GHCR
 
 The pglite component is published to GitHub Container Registry (GHCR) as an OCI wasm component. [The workflow](https://github.com/di-framework/platform/actions/workflows/pglite-component-publish.yml) runs by itself on each push to `main` that changes one of its input paths (`on.push.paths`). `workflow_dispatch` stays available for reruns and always builds.
 
 The workflow has four jobs:
 - `check-source` (`packages: read`) hashes the committed input files (`scripts/source-check.ts`). On a push it skips the build when `ghcr.io/di-framework/pglite-component:src-<hash>` already exists, so commits that do not change the component publish nothing.
-- `build` (no write token) runs the same targets as `ci.yml`: `make tools-rust`, `make unit smoke` (which runs `make build`, composing the provider with the engine via `wac plug`), then the publisher crates' clippy and tests.
+- `build` (no write token) runs the same targets as `ci.yml`: `make tools-rust`, `make unit smoke` (which runs `make build`, composing the provider with two instances of the engine via `wac compose`), then the publisher crates' clippy and tests.
 - `publish` (`packages: write`) downloads the tested `dist/` and runs `pglite-component-publisher`. It never rebuilds or modifies `dist/`. It checks `SHA256SUMS`, requires the export `di-framework:pglite/database@0.2.0` and rejects any import that is not `wasi:*`, then pushes the layer, config and manifest with `oras` under `ghcr.io/di-framework/pglite-component:<commit sha>` only, pulls it back with `wash` by the manifest digest to compare bytes, and only then points the version tag (`0.2.0`, the WIT package version) at that same manifest with `oras tag` and asserts both tags resolve to one digest. A failed check leaves the version tag where it was. The manifest and config carry a fixed `created` time (the publish step clears `SOURCE_DATE_EPOCH`, so `1970-01-01T00:00:00Z`), so publishing an unchanged `di-framework-pglite.wasm` gives the same digest and the pin job has nothing to pin. The `build` job passes the tested wasm sha256 to `publish`, which verifies it before pushing. It also tags the manifest `src-<hash>`.
 - `pin` (`contents: write`, `pull-requests: write`) opens or updates the PR `bot/pin-pglite-component`, "chore: pin pglite-component to <digest>", which rewrites the digests in this README with `scripts/pin-artifact.ts`. GitHub does not run workflows on a PR that `GITHUB_TOKEN` opened, so a maintainer has to start its checks (close and reopen it) before merging. It also runs when a push's source is already published (a revert to an older source, or a pin PR closed unmerged), so `main`'s pin follows the current source; it opens no PR when `main` already has the digest. On that path the `realign` job (`packages: write`) points the moving version tag back at that source's digest with `scripts/retag.sh`, which leaves a tag that is already there alone. Every tag move is behind the same source guard, so a stale run never retags.
 
@@ -113,7 +139,7 @@ Tags are movable. `0.2.0` always points to the latest `main` publish for WIT pac
 ### Artifact location
 
 The digest is in **Details** > **Record component digest** > **Step summary**, and in the `pglite-publish-report` artifact (`publish-report.json`).
-Published digest: `ghcr.io/di-framework/pglite-component@sha256:42a5a38f61abb621643c8175fd4c9a8652778eb90edc458eb355625733fa4c33`
+Published digest: `ghcr.io/di-framework/pglite-component@sha256:9d5b7c96aa4ad13c1c4de8d0285cf731b9926a47e0a7c680237708d26b439da3`
 
 **Note:** The GHCR package must be made public by an org admin after the first publish. Until then, only members with access to di-framework/platform can pull it.
 
@@ -151,7 +177,7 @@ wasmtime run --dir ./data::/data path/to/app.composed.wasm
 To use the published OCI component from GHCR instead (pin by digest for reproducibility):
 
 ```sh
-export PGLITE_REF='ghcr.io/di-framework/pglite-component@sha256:42a5a38f61abb621643c8175fd4c9a8652778eb90edc458eb355625733fa4c33'
+export PGLITE_REF='ghcr.io/di-framework/pglite-component@sha256:9d5b7c96aa4ad13c1c4de8d0285cf731b9926a47e0a7c680237708d26b439da3'
 wash oci pull "${PGLITE_REF}" pglite.wasm
 wac plug --plug pglite.wasm path/to/app.wasm -o path/to/app.composed.wasm
 mkdir -p ./data
@@ -170,8 +196,8 @@ savepoints, `rows-affected`, `close`, and `server-version`. PostgreSQL parameter
 use `$1`, `$2`, etc. Text parameters are sent with OID 0 (unknown type), allowing
 PostgreSQL to infer the type from context; comparisons against `uuid`, `timestamptz`,
 and `jsonb` columns work correctly (see Typed values). `server-version()` reports the bundled engine without
-opening a database. Only the `template1` database is currently supported;
-other `open-options.database` values are rejected. Requests must fit the engine's
+opening a database (see [Application database](#application-database) for
+`open-options.database`). Requests must fit the engine's
 input buffer; each serialized result is limited to 64 MiB and stays in memory.
 Larger results return a PostgreSQL program-limit error. Signal-based statement
 timeouts are unavailable in this WASI engine: nonzero `statement-timeout-ms`
@@ -185,6 +211,23 @@ and migrations run on embedded PostgreSQL. Compose your component with this
 provider (see above). The adapter is portable: it uses only
 `node:async_hooks`, which the framework's component toolchain shims.
 
+**Toolchain requirement for `int8` parameters past 2^53.** An exact `bigint`
+parameter beyond ±(2^53-1) needs componentize-qjs `0.4.4-di.5` or later, which
+`@di-framework/cli-plugin-platform` 6.2.0 or later installs. Use the default
+runtime, without `--sync` or `--opt-size`. When you install the compiler
+yourself, use the `di` dist-tag (`bun add @di-framework/componentize-qjs@di`):
+npm's `latest` tag of `@di-framework/componentize-qjs` still points at
+`0.4.4-di.1`. Older bindings, and the `--sync` / `--opt-size` runtimes, lower
+WIT `s64` only from Numbers, and such a parameter traps the guest instance
+instead of throwing a catchable error. Safe integers (`number` or `bigint`)
+are sent as Numbers and work on every binding.
+
+> **Upgrading.** Before this release, a `bigint` past 2^53 was sent as decimal
+> text. It is now sent as an exact `int8` integer. If your guest binds such
+> values, update the CLI plugin to 6.2.0 or later (componentize-qjs
+> `0.4.4-di.5`) before you update this package. Guests that bind only safe
+> integers need no change.
+
 ```ts
 import type { SqlDatabase } from '@di-framework/repo';
 import { createWasmPgliteDatabase } from '@di-framework/pglite-component';
@@ -207,8 +250,8 @@ handle and share it: every call goes through one async mutex.
 
 - **Transactions.** `transaction(fn)` runs the provider's `begin` and `commit`, and `rollback` when `fn` throws. Statements issued from inside `fn`, through the callback view or the outer handle, join the transaction; other tasks wait for it. Inside `fn`, prefer the callback view: while the transaction is open it joins from any async context, including a worker loop or `AsyncResource` created earlier, and Wasm-guest code that the `node:async_hooks` shim does not instrument (native async generators). The outer handle joins only from `fn`'s own async context. From any other context it waits for the mutex, so awaiting it from `fn` deadlocks. A nested `transaction()` opens a savepoint. When it throws, only its own work rolls back, and the outer transaction can continue. Its work commits only with the outer transaction. Sibling savepoints started concurrently run one at a time. A plain statement issued through a view while a sibling savepoint is open joins that savepoint and rolls back with it: in `Promise.all([tx.transaction(failing), (async () => { await work(); await tx.run(...); })()])`, a `run` issued while the savepoint is open lands inside it, so await the savepoint first when the statement must survive it. Statements issued concurrently inside one transaction reach the connection one at a time, also with bindings that return promises. `transaction()` on a view, called from another async context while a sibling savepoint is open, waits for that sibling to finish; if the sibling awaits that call, it waits forever. Joining lasts only while a transaction is open. A savepoint's callback view kept after the savepoint returns joins the nearest open ancestor while the root transaction is still open, and its work commits or rolls back with that ancestor. Once the root transaction has ended, a retained callback view, like a timer scheduled inside `fn`, waits for the mutex like any other caller and never runs inside another task's transaction.
 - **Placeholders.** `?` placeholders become `$1`, `$2`, ... in order (`toPgPlaceholders`). The rewrite skips `'...'` and `E'...'` strings, `"..."` identifiers, `$tag$...$tag$` bodies, `--` and `/* */` comments, and the jsonb operators `?|` and `?&`. Because of that, `?||` reads as `?|` followed by `|`: put a space in the concatenation (`? || 'x'`). The bare jsonb `?` operator looks like a placeholder: use `jsonb_exists(col, ?)` in a statement with parameters. A statement run without parameters is not rewritten. You can write `$n` yourself, but do not mix `$n` with `?` in one statement.
-- **Parameters.** `string` is sent as text, and PostgreSQL infers its type from context, so a UUID or timestamp string works against `uuid` and `timestamptz` columns. A safe integer is `int8`, another number is `float8`, a `boolean` is `bool`, and `Uint8Array`, `ArrayBuffer` and typed arrays are `bytea`. A `Date` is sent as an RFC 3339 timestamp. Plain objects and arrays are sent as JSON, so a JavaScript array is not a PostgreSQL array: pass a literal such as `'{a,b}'`. A `bigint` outside the safe integer range is sent as decimal text, so it is not rounded. A `number` that is an integer outside the safe range throws a `TypeError`, because it has already lost precision: pass a `bigint` or a decimal string for `int8`. NaN and Infinity are valid `float8` values and are sent as `real`.
-- **Results.** Values match the `wasmcloud:postgres` codec in `@di-framework/repo`, so repositories behave the same on both backends. `json` and `jsonb` are parsed. `timestamptz` is an ISO string with milliseconds (`2024-01-15T10:30:00.123Z`, microseconds truncated); `infinity` and BC dates are returned as PostgreSQL prints them. An `int8` outside the safe integer range is a decimal string, but only when the binding lifts WIT `s64` as a `bigint`; a binding that lifts it as a JavaScript number (componentize-qjs lowers `s64` from numbers) has already lost the precision, so cast large `int8` columns to `text` in the query (`id::text`) when exact values matter (#153). `bool` is a boolean, `bytea` is a `Uint8Array`, and `timestamp` without zone, `date`, `uuid`, `numeric` and arrays are strings.
+- **Parameters.** `string` is sent as text, and PostgreSQL infers its type from context, so a UUID or timestamp string works against `uuid` and `timestamptz` columns. A safe integer (`number` or `bigint`) is `int8`, sent as a JavaScript number, another number is `float8`, a `boolean` is `bool`, and `Uint8Array`, `ArrayBuffer` and typed arrays are `bytea`. A `Date` is sent as an RFC 3339 timestamp. Plain objects and arrays are sent as JSON, so a JavaScript array is not a PostgreSQL array: pass a literal such as `'{a,b}'`. A `bigint` past 2^53 that fits `int8` is sent as an exact `int8` with a `BigInt` payload, which needs componentize-qjs `0.4.4-di.5` or later (see the requirement above); one outside the `int8` range is sent as decimal text, so a `numeric` column receives it exactly. A `number` that is an integer outside the safe range throws a `TypeError`, because it has already lost precision: pass a `bigint` or a decimal string for `int8`. NaN and Infinity are valid `float8` values and are sent as `real`.
+- **Results.** Values match the `wasmcloud:postgres` codec in `@di-framework/repo`, so repositories behave the same on both backends. `json` and `jsonb` are parsed. `timestamptz` is an ISO string with milliseconds (`2024-01-15T10:30:00.123Z`, microseconds truncated); `infinity` and BC dates are returned as PostgreSQL prints them. An `int8` outside the safe integer range is an exact decimal string when the binding lifts WIT `s64` as a `bigint` (componentize-qjs `0.4.4-di.5` or later with the default runtime, or jco). Older componentize-qjs releases and the `--sync` / `--opt-size` runtimes lift `s64` as a Number, which has already rounded it, so cast large `int8` columns to `text` (`id::text`) on those. `bool` is a boolean, `bytea` is a `Uint8Array`, and `timestamp` without zone, `date`, `uuid`, `numeric` and arrays are strings.
 - **Errors.** Failures throw `WasmPgliteError` with the WIT `tag`. A PostgreSQL error keeps its SQLSTATE in `error.code` (`'23505'` for a unique violation), and the message starts with `PostgreSQL <code>`, so `isUniqueViolation` from `@di-framework/repo` works too.
 
 Pass `module` or `loadModule` to supply the interface yourself (for tests), and
@@ -319,7 +362,12 @@ Blowfish (`bf`), CAST5 (`cast5`) and single DES (`des`) are unavailable in
 this build, because the OpenSSL legacy provider is not built or loaded.
 pgcrypto refuses them with `Cipher cannot be initialized`: in `encrypt()` and
 `decrypt()`, in the PGP functions, and when decrypting PGP messages that use
-them. `3des` (DES-EDE3) is in OpenSSL's default provider and still works, for
+them. For PGP this is upstream PostgreSQL's own check (17.11, CVE-2026-14663);
+pgcrypto is otherwise unmodified. Provider releases before the #355 fix wrote
+Blowfish and CAST5 PGP messages that are not actually encrypted. To recover such
+a message, decrypt it once with upstream's `ignore-cipher-failure=1` option
+(`pgp_sym_decrypt`, `pgp_pub_decrypt`; decryption only), then re-encrypt it with
+AES. Plaintext recovered that way is not authenticated by the key. `3des` (DES-EDE3) is in OpenSSL's default provider and still works, for
 legacy data only. Use `aes` (`aes128`, `aes192`, `aes256` for PGP). Password hashing with
 `crypt()` and `gen_salt('bf')`, `'md5'`, `'xdes'` or `'des'` is unaffected,
 because pgcrypto implements those itself.
@@ -329,17 +377,97 @@ libraries per engine instance. pgcrypto resolves before that table and never
 uses a slot. A `LOAD` of a new library after the table is full fails with
 `dlopen table is full` and leaves the session usable.
 
+### Application database
+
+Application data lives in the `postgres` database on data directories this
+provider initializes. Directories created before this release keep it in
+`template1` (#212). With `open-options.database` unset:
+
+| Data directory | Default database |
+| --- | --- |
+| Initialized by this provider: `<root>/data/di-framework-database` contains `postgres` | `postgres` |
+| No marker: created before this release (6.0.16 and earlier) | `template1`, unchanged |
+
+Upgrading the provider never moves data: an existing directory keeps opening
+`template1`, and it never gets the marker. Fresh directories open `postgres`
+from their first session on.
+
+**Do not roll back below this release for a directory it created.** Providers
+from before this release (6.0.16 and earlier) ignore the marker and open
+`template1`. On a directory created by this release, that database is empty:
+the application sees no data, may re-run its migrations, and writes into
+`template1`. Upgrading again brings the `postgres` data back, and everything
+written during the rollback stays stranded in `template1`. To roll back,
+either roll back to a build that reads the marker, or restore the backup of
+the root taken before the upgrade.
+
+Explicit `open-options.database` values:
+
+- `postgres` and `template1` are accepted. initdb creates both, so they exist
+  in every complete directory; on an older directory, `postgres` exists but is
+  empty. Before the engine starts, the provider checks that the database's
+  fixed-OID directory exists (`base/1` for `template1`, `base/5` for
+  `postgres`). If it does not, `open` fails with `open-failed`
+  (`database "postgres" has no data directory at base/5 ...`) and the same
+  component instance can still open `template1`. This is a filesystem check,
+  not a catalog lookup, so it does not catch every case:
+  - If initdb crashed while creating `postgres`, after copying `base/5` but
+    before committing the database, the check passes and an explicit
+    `postgres` open still stops the engine with
+    `FATAL: database "postgres" does not exist`. Only an initdb that crashed
+    partway through leaves a directory in this state, and with or without the
+    clean error such a directory is unfinished: re-create it (remove the root)
+    or restore it from a backup, do not use it.
+  - A `postgres` database that was dropped and re-created (new OID) or moved
+    with `ALTER DATABASE ... SET TABLESPACE` has no `base/5`, so the provider
+    refuses to open it although it exists.
+- `template0` is always rejected: the single-user engine would not enforce
+  `datallowconn`, so opening it would make the pristine template writable.
+- Any other name is rejected. The list is fixed because the engine picks its
+  database before its backend starts, so it cannot look the name up first.
+
+The embedded backend stays connected to the database its first `open` chose.
+A later `open` in the same component instance that resolves to a different
+database fails with `open-failed`; restart the component to switch.
+
+The marker is part of the data directory. Back it up and restore it with the
+rest of PGDATA. Without it, a directory falls back to `template1`, and an
+application whose tables are in `postgres` finds them missing; the provider
+cannot detect this. Do not add the marker by hand to a directory whose data
+is in `template1`. To move a legacy directory to `postgres`, export the data
+through the application and import it into a fresh directory, as described
+in [Upgrading across PostgreSQL major versions](#upgrading-across-postgresql-major-versions)
+(no `pg_dump` is bundled).
+
+Initialization runs in a separate, single-use engine instance bundled into
+the provider: initdb's post-bootstrap step runs in `template1` and the
+single-user backend cannot change databases afterwards. That instance creates
+the cluster and the marker. The serving instance then boots on the finished
+cluster in the selected database and verifies it with `current_database()`
+before the first session is handed out.
+
+Cost: the bootstrap instance runs only when a directory is created, but the
+component model cannot drop an instance, so its linear memory and its open
+files stay held until the process exits. The first start on a new directory
+peaks at about 690 MB RSS (about 106 MB more than a single engine) and holds
+about 43 more host file handles under the root. Later starts on an existing
+directory cost the same as before (about 264 MB in the smoke consumer).
+Restart the component after creating a directory if that memory matters.
+
 ## Persistence and ownership
 
 For an `open("/data/orders", ...)` call:
 
-- `/data/orders/data/` is PGDATA (catalogs, tables, WAL and configuration).
+- `/data/orders/data/` is PGDATA (catalogs, tables, WAL and configuration,
+  plus the `di-framework-database` marker on directories this provider
+  initialized; see [Application database](#application-database)).
 - `/data/orders/runtime/` contains bundled initialization/support files.
 - Bootstrap and shared-memory scratch files also stay beneath `/data/orders`.
 
 Mount the entire root on persistent storage and reuse it after restarts.
 Initialization creates the cluster once; later starts reuse it. Incomplete
-clusters or an incompatible PostgreSQL major version are rejected.
+clusters are rejected, and so is a data directory from another PostgreSQL major
+version (see [below](#upgrading-across-postgresql-major-versions)).
 `fsync`, `synchronous_commit`, and `full_page_writes` are enabled before the
 backend starts. The host filesystem must honor WASI sync operations; a local
 restart test is not a power-loss durability certification.
@@ -370,17 +498,52 @@ its components the matching WASI preopen. Use a stable workload identity on
 redeploy and configure exclusive execution for this database. These
 annotations provide storage; they do not enforce database ownership.
 
+## Upgrading across PostgreSQL major versions
+
+A data directory belongs to one PostgreSQL major version, recorded in
+`<root>/data/PG_VERSION`. Minor releases share the on-disk format: a directory
+written by the 17.5 engine (provider 6.0.15 and earlier) opens in place under
+17.11, and `make smoke` checks this.
+
+The engine opens only major version 17. For any other `PG_VERSION`, `open`
+fails with `open-failed` and a message such as:
+
+```text
+incompatible PostgreSQL data directory: PG_VERSION is 16, but this provider bundles
+PostgreSQL 17.11 and opens only major version 17 data directories; see
+platform/pglite-component/README.md#upgrading-across-postgresql-major-versions
+```
+
+The provider does not convert directories between major versions; it bundles
+neither a second engine nor `pg_upgrade`. To move a database across a major
+version:
+
+1. Stop every writer. Keep the provider version that wrote the directory,
+   pinned by its digest or npm version, and back up the whole root.
+2. With that provider, export the data through the application, for example
+   with a migration step that reads each table through the `database`
+   interface into a portable format.
+3. Deploy the new provider on a new, empty root, and recreate the schema with
+   the application's migrations.
+4. Import the exported data, check it, then retire the old root.
+
+If the root is encrypted with `pglite-encfs`, compose encfs with the same key
+for both the export and the import. PostgreSQL 18 is tracked in #401.
+
 ## Implementation
 
 - `js/adapter.ts`: the `SqlDatabase` adapter published on npm (`bun run build:adapter`).
 - `js/wit.d.ts`: generated TypeScript view of the `database` interface.
 - `src/lib.rs`: public WIT resources and connection lifecycle.
 - `src/pgwire.rs`: PostgreSQL message encoding and typed rows, over memory.
-- `src/engine.rs`: persistent filesystem setup and exclusive engine access.
+- `src/engine.rs`: persistent filesystem setup, exclusive engine access, and the application database choice (marker, crash windows).
 - `engine/bridge.wat`: private canonical ABI bridge to the core engine.
 - `engine/build-pgcrypto.sh`: builds OpenSSL libcrypto and pgcrypto in the engine container and generates pgcrypto's static `dlsym` table; `scripts/patch-engine-source.ts` links both into the engine. The libcrypto build is cached under a key of the OpenSSL source tarball's sha256, the Configure options and `SOURCE_DATE_EPOCH`, so an OpenSSL version bump always rebuilds it.
 - `scripts/patch-engine-source.ts`: also replaces the upstream `dlopen` emulation's unbounded table (`dltab`) with the bounded one described under [Extensions](#extensions), and keeps pgcrypto's hook ahead of it.
+- `engine/patches/postgresql-17.11-wasi.patch`: Electric's 17.5 WASI changes replayed onto upstream `REL_17_11`; see [engine/patches/README.md](engine/patches/README.md).
+- `scripts/build-engine.ts`: builds the engine source tree (pinned tag, checked commit, checked patches) and runs the wasipg container build; `scripts/check-engine-patch.ts` (`make check-engine-patch`) runs the same source steps without the build.
 - `scripts/prepare-engine.ts`: pinned engine preparation and componentization (all build scripts are Bun TypeScript; see `scripts/`).
 - `wit/deps/pglite-engine/engine.wit`: internal interface, composed away at build.
+- `wit/deps/pglite-engine-bootstrap/bootstrap.wit`: internal interface of the single-use initdb engine instance; `scripts/build.ts` (`providerWac`) feeds it from a second instance of the same engine component.
 
 Engine provenance and modifications are described in `engine/NOTICE`.

package/dist/BUILD-INFO.txt

@@ -1,14 +1,16 @@
 component:       di-framework:pglite@0.2.0
 profile:         release
-built:           2026-10-16T03:00:39Z
+built:           2026-10-17T04:21:44Z
 rustc:           rustc 1.97.1 (8bab26f4f 2026-07-14)
 target:          wasm32-wasip2
 wasm-tools:      wasm-tools 1.258.0 (5c6d31c78 2026-08-24)
 wit-bindgen:     0.61.1
 md5:             0.7.0
-engine:          PostgreSQL 17.5, persistent WASI filesystem
+engine:          PostgreSQL 17.11, persistent WASI filesystem
 extensions:      plpgsql, pgcrypto (OpenSSL 3.5.9 libcrypto)
-engine-source:   https://github.com/moznion/wasipg/tree/fa290be67946c0d3c4540bd1400b11e193d874e1
+engine-source:   https://github.com/postgres/postgres/tree/083ac033419f690758508e08c1736089384bbee8 (REL_17_11)
+engine-patch:    engine/patches/postgresql-17.11-wasi.patch (sha256 6beb64a561caa80e3669733f9e24e344edb0445d2623c17eee79d48ec28fac65)
+engine-recipe:   https://github.com/moznion/wasipg/tree/fa290be67946c0d3c4540bd1400b11e193d874e1
 adapter-sha256:  e51dd61669a20daca34befe7fdadf1ac84e4795a2c84a8400818ee1de5373ccc
-engine-sha256:   ad2d96c9ce85a35620719fbc6a038c407234d11c5a106e70c2863b104dcfa52c
-size:            20116132 bytes
+engine-sha256:   eb374344cff24c4cedacdad05a636a3b75b5eb1c4e55aa1a3ff9930be2ebc328
+size:            20176453 bytes

package/dist/SHA256SUMS

@@ -1,4 +1,4 @@
-bff475faba7eecde56427e40704c282523e0f84482389e029f9dd58d9cf0f6aa  di-framework-pglite.wasm
-6053154ec1bc94de63ce4f4f4cce5922ef57dce794c2dde326f5845b8982d35f  di-framework-pglite.wit
-f7a7643d858d330dc4e114d63b554e15dcacfcf19c5afae6454b456e33216b12  BUILD-INFO.txt
-e19368fcd3dc22d06c46a5256950924b3775154cd77f7be2d3105036be576619  THIRD-PARTY-NOTICES.txt
+04cea641db9ac90a954fefd7783100175ce15bb2cc2e6fc47660fb4090eb2663  di-framework-pglite.wasm
+fcce3740d3bc8501368fa6c4686eb626a1e6d4d15d017817de273dfd77afcab9  di-framework-pglite.wit
+c3744f0613035d64fc6120bb9404a56e5759761e7cd64c55feeadd74b9727ad0  BUILD-INFO.txt
+443fd294671eb64972556656d3ee871e48448ad1169c012d18aa868568f628c1  THIRD-PARTY-NOTICES.txt

package/dist/THIRD-PARTY-NOTICES.txt

@@ -1,14 +1,22 @@
 di-framework embedded PGlite component
 
-The provider bundles PostgreSQL 17.5 (PGlite WASI), originally maintained by
-ElectricSQL. PostgreSQL's license is reproduced in POSTGRESQL-COPYRIGHT.
-The upstream bindings license and WASI adapter license are reproduced in
-PGLITE-BINDINGS-LICENSE and WASMTIME-LICENSE. The engine statically links
-the pgcrypto extension and OpenSSL libcrypto; their notices are in
-PGCRYPTO-NOTICES and the OpenSSL license (Apache-2.0) in OPENSSL-LICENSE.
+The provider bundles PostgreSQL 17.11 built for WASI. The engine source is
+upstream PostgreSQL REL_17_11 (commit 083ac033419f690758508e08c1736089384bbee8)
+with ElectricSQL's PGlite WASI changes from postgres-pglite branch
+REL_17_5_WASM-pglite (commit 2194acf356e9b7bf7cff29c4ed4bd6b82b93895d) replayed
+onto it; that replay is engine/patches/postgresql-17.11-wasi.patch in the
+di-framework source. PostgreSQL, postgres-pglite and the replay patch are
+distributed under the PostgreSQL License, reproduced in POSTGRESQL-COPYRIGHT.
+The engine is built with the wasipg recipe and its sjlj patches (Apache-2.0;
+notice below). The upstream bindings license and WASI adapter license are
+reproduced in PGLITE-BINDINGS-LICENSE and WASMTIME-LICENSE. The engine
+statically links the pgcrypto extension and OpenSSL libcrypto; their notices
+are in PGCRYPTO-NOTICES and the OpenSSL license (Apache-2.0) in
+OPENSSL-LICENSE.
 
 Sources:
-https://github.com/electric-sql/postgres-pglite
+https://github.com/postgres/postgres/tree/REL_17_11
+https://github.com/electric-sql/postgres-pglite/tree/REL_17_5_WASM-pglite
 https://github.com/electric-sql/pglite-bindings
 https://github.com/moznion/wasipg
 https://github.com/bytecodealliance/wasmtime/tree/v29.0.1
@@ -21,9 +29,17 @@ bootstrap files within the database's persistent filesystem mount. A growable,
 bounded memory buffer replaces socket-file spillover for query replies. Backend
 startup restores application session defaults after bootstrap and enables
 durable writes. The emulated dlopen keeps loaded libraries in a bounded table
-instead of writing past the end of an unsized array. pgcrypto's PGP CFB mode
-(contrib/pgcrypto/pgp-cfb.c) is patched to refuse ciphers that are unavailable
-in this build.
+instead of writing past the end of an unsized array. Two small changes to the
+WASI glue let it compile against 17.11: initdb's frontend SplitGUCList
+declaration is renamed where initdb is compiled into the backend, and the
+frontend allocator stubs gain the overflow-checked pg_malloc_mul and
+pg_realloc_mul. pgcrypto is unmodified: PostgreSQL 17.11 itself refuses
+ciphers OpenSSL cannot run (CVE-2026-14663), which in this build includes
+Blowfish and CAST5.
+
+The wasipg notice below describes wasipg's own release artifacts, which were
+built from REL_17_5_WASM-pglite; this provider uses wasipg's build recipe and
+patches with the 17.11 source tree above.
 
 The engine's core module, support files, adapter, and the provider are
 composed into one deployable artifact. Engine code executes in the Wasm
@@ -86,9 +102,9 @@ wasi-libc from wasi-sdk 33, distributed under
 "Apache-2.0 WITH LLVM-exception OR Apache-2.0 OR MIT". The shadow headers
 under build/hotfix/ are derived from wasi-libc headers.
 PostgreSQL Database Management System
-(formerly known as Postgres, then as Postgres95)
+(also known as Postgres, formerly known as Postgres95)
 
-Portions Copyright (c) 1996-2025, PostgreSQL Global Development Group
+Portions Copyright (c) 1996-2026, PostgreSQL Global Development Group
 
 Portions Copyright (c) 1994, The Regents of the University of California
 
@@ -110,7 +126,7 @@ ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATIONS TO
 PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
 
 --------------------------------------------------------------------------
-pgcrypto (PostgreSQL 17.5 contrib/pgcrypto)
+pgcrypto (PostgreSQL 17.11 contrib/pgcrypto)
 --------------------------------------------------------------------------
 
 pgcrypto is part of PostgreSQL and is distributed under the PostgreSQL

package/dist/di-framework-pglite.wit

@@ -1,6 +1,7 @@
 package root:component;
 
 world root {
+  import wasi:random/random@0.2.3;
   import wasi:io/poll@0.2.9;
   import wasi:clocks/monotonic-clock@0.2.9;
   import wasi:clocks/wall-clock@0.2.9;
@@ -18,11 +19,17 @@ world root {
   import wasi:cli/terminal-stderr@0.2.9;
   import wasi:filesystem/types@0.2.9;
   import wasi:filesystem/preopens@0.2.9;
-  import wasi:random/random@0.2.3;
 
   export di-framework:pglite/types@0.2.0;
   export di-framework:pglite/database@0.2.0;
 }
+package wasi:random@0.2.3 {
+  interface random {
+    get-random-bytes: func(len: u64) -> list<u8>;
+  }
+}
+
+
 package wasi:io@0.2.9 {
   interface poll {
     resource pollable {
@@ -40,16 +47,16 @@ package wasi:io@0.2.9 {
 
     resource input-stream {
       read: func(len: u64) -> result<list<u8>, stream-error>;
-      subscribe: func() -> pollable;
       blocking-read: func(len: u64) -> result<list<u8>, stream-error>;
+      subscribe: func() -> pollable;
     }
 
     resource output-stream {
       check-write: func() -> result<u64, stream-error>;
       write: func(contents: list<u8>) -> result<_, stream-error>;
+      blocking-write-and-flush: func(contents: list<u8>) -> result<_, stream-error>;
       blocking-flush: func() -> result<_, stream-error>;
       subscribe: func() -> pollable;
-      blocking-write-and-flush: func(contents: list<u8>) -> result<_, stream-error>;
     }
 
     variant stream-error {
@@ -64,15 +71,15 @@ package wasi:clocks@0.2.9 {
   interface monotonic-clock {
     use wasi:io/poll@0.2.9.{pollable};
 
-    type duration = u64;
-
     type instant = u64;
 
-    subscribe-duration: func(when: duration) -> pollable;
+    type duration = u64;
 
     now: func() -> instant;
 
     subscribe-instant: func(when: instant) -> pollable;
+
+    subscribe-duration: func(when: duration) -> pollable;
   }
   interface wall-clock {
     record datetime {
@@ -135,42 +142,47 @@ package wasi:cli@0.2.9 {
 
 package wasi:filesystem@0.2.9 {
   interface types {
-    use wasi:io/streams@0.2.9.{input-stream, output-stream};
-    use wasi:clocks/wall-clock@0.2.9.{datetime};
     use wasi:io/error@0.2.9.{error};
+    use wasi:clocks/wall-clock@0.2.9.{datetime};
+    use wasi:io/streams@0.2.9.{input-stream, output-stream};
 
     resource descriptor {
       read-via-stream: func(offset: filesize) -> result<input-stream, error-code>;
       write-via-stream: func(offset: filesize) -> result<output-stream, error-code>;
       append-via-stream: func() -> result<output-stream, error-code>;
+      advise: func(offset: filesize, length: filesize, advice: advice) -> result<_, error-code>;
+      sync-data: func() -> result<_, error-code>;
       get-flags: func() -> result<descriptor-flags, error-code>;
+      get-type: func() -> result<descriptor-type, error-code>;
+      set-size: func(size: filesize) -> result<_, error-code>;
+      read: func(length: filesize, offset: filesize) -> result<tuple<list<u8>, bool>, error-code>;
+      write: func(buffer: list<u8>, offset: filesize) -> result<filesize, error-code>;
       read-directory: func() -> result<directory-entry-stream, error-code>;
       sync: func() -> result<_, error-code>;
       create-directory-at: func(path: string) -> result<_, error-code>;
       stat: func() -> result<descriptor-stat, error-code>;
       stat-at: func(path-flags: path-flags, path: string) -> result<descriptor-stat, error-code>;
       open-at: func(path-flags: path-flags, path: string, open-flags: open-flags, %flags: descriptor-flags) -> result<descriptor, error-code>;
-      rename-at: func(old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>;
-      metadata-hash: func() -> result<metadata-hash-value, error-code>;
-      metadata-hash-at: func(path-flags: path-flags, path: string) -> result<metadata-hash-value, error-code>;
-      advise: func(offset: filesize, length: filesize, advice: advice) -> result<_, error-code>;
-      sync-data: func() -> result<_, error-code>;
-      get-type: func() -> result<descriptor-type, error-code>;
-      set-size: func(size: filesize) -> result<_, error-code>;
-      read: func(length: filesize, offset: filesize) -> result<tuple<list<u8>, bool>, error-code>;
-      write: func(buffer: list<u8>, offset: filesize) -> result<filesize, error-code>;
       readlink-at: func(path: string) -> result<string, error-code>;
       remove-directory-at: func(path: string) -> result<_, error-code>;
+      rename-at: func(old-path: string, new-descriptor: borrow<descriptor>, new-path: string) -> result<_, error-code>;
       symlink-at: func(old-path: string, new-path: string) -> result<_, error-code>;
       unlink-file-at: func(path: string) -> result<_, error-code>;
-    }
-
-    resource directory-entry-stream {
-      read-directory-entry: func() -> result<option<directory-entry>, error-code>;
+      metadata-hash: func() -> result<metadata-hash-value, error-code>;
+      metadata-hash-at: func(path-flags: path-flags, path: string) -> result<metadata-hash-value, error-code>;
     }
 
     type filesize = u64;
 
+    enum advice {
+      normal,
+      sequential,
+      random,
+      will-need,
+      dont-need,
+      no-reuse,
+    }
+
     enum error-code {
       access,
       would-block,
@@ -211,6 +223,10 @@ package wasi:filesystem@0.2.9 {
       cross-device,
     }
 
+    resource directory-entry-stream {
+      read-directory-entry: func() -> result<option<directory-entry>, error-code>;
+    }
+
     flags descriptor-flags {
       read,
       write,
@@ -231,6 +247,15 @@ package wasi:filesystem@0.2.9 {
       socket,
     }
 
+    record directory-entry {
+      %type: descriptor-type,
+      name: string,
+    }
+
+    flags path-flags {
+      symlink-follow,
+    }
+
     type link-count = u64;
 
     record descriptor-stat {
@@ -242,10 +267,6 @@ package wasi:filesystem@0.2.9 {
       status-change-timestamp: option<datetime>,
     }
 
-    flags path-flags {
-      symlink-follow,
-    }
-
     flags open-flags {
       create,
       directory,
@@ -258,20 +279,6 @@ package wasi:filesystem@0.2.9 {
       upper: u64,
     }
 
-    record directory-entry {
-      %type: descriptor-type,
-      name: string,
-    }
-
-    enum advice {
-      normal,
-      sequential,
-      random,
-      will-need,
-      dont-need,
-      no-reuse,
-    }
-
     filesystem-error-code: func(err: borrow<error>) -> option<error-code>;
   }
   interface preopens {
@@ -282,13 +289,6 @@ package wasi:filesystem@0.2.9 {
 }
 
 
-package wasi:random@0.2.3 {
-  interface random {
-    get-random-bytes: func(len: u64) -> list<u8>;
-  }
-}
-
-
 package di-framework:pglite@0.2.0 {
   interface types {
     record pg-error {

package/dist/js/adapter.d.ts

@@ -51,7 +51,13 @@ export interface WasmPgliteConnection {
 }
 /** The `open-options` record. Every field is optional. */
 export interface WasmPgliteOpenOptions {
-    /** Session database. The provider currently accepts only `template1`. */
+    /**
+     * Session database: `postgres` or `template1`. Unset selects the data
+     * directory's default: `postgres` for a directory the provider initialized
+     * (it writes a `di-framework-database` marker in PGDATA), `template1` for
+     * one created by an earlier release. The provider rejects `template0` and
+     * any other name.
+     */
     database?: string;
     /** Reserved by the provider: only `0` (or unset) is accepted. */
     statementTimeoutMs?: number;
@@ -87,9 +93,17 @@ export declare function unwrapWasmPgliteResult<T>(value: T | WasmResult<T>): T;
 /**
  * Converts a bound JavaScript parameter into a `value` variant.
  *
- * - `bigint` in the safe integer range becomes `integer`; a larger one is sent
- *   as `text` (OID 0), so PostgreSQL parses it for an `int8`/`numeric` column
- *   without rounding through a double.
+ * - Integers are sent in three bands:
+ *   - A safe integer (`number` or `bigint`, |v| <= 2^53-1) becomes `integer`
+ *     with a `number` payload. Every componentize-qjs release, including the
+ *     `--sync` / `--opt-size` runtimes, and jco lower WIT `s64` from it.
+ *   - A `bigint` past 2^53 that fits `int8` becomes `integer` with a `bigint`
+ *     payload, so it reaches PostgreSQL exact. That needs a binding that lowers
+ *     `s64` from `BigInt`: componentize-qjs 0.4.4-di.5 or later (default
+ *     runtime) or jco. Older componentize-qjs bindings trap on it.
+ *   - A `bigint` outside the `int8` range is sent as `text` (OID 0), so
+ *     PostgreSQL parses it for a `numeric` column instead of the binding
+ *     wrapping it modulo 2^64.
  * - A `number` that is an integer outside the safe range throws a `TypeError`
  *   (pass a `bigint` or string for `int8`); other non-safe numbers, including
  *   NaN and Infinity, are `real` (`float8`).

package/dist/js/adapter.js

@@ -84,12 +84,22 @@ export function unwrapWasmPgliteResult(value) {
 }
 const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
 const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_INT8 = 2n ** 63n - 1n;
+const MIN_INT8 = -(2n ** 63n);
 /**
  * Converts a bound JavaScript parameter into a `value` variant.
  *
- * - `bigint` in the safe integer range becomes `integer`; a larger one is sent
- *   as `text` (OID 0), so PostgreSQL parses it for an `int8`/`numeric` column
- *   without rounding through a double.
+ * - Integers are sent in three bands:
+ *   - A safe integer (`number` or `bigint`, |v| <= 2^53-1) becomes `integer`
+ *     with a `number` payload. Every componentize-qjs release, including the
+ *     `--sync` / `--opt-size` runtimes, and jco lower WIT `s64` from it.
+ *   - A `bigint` past 2^53 that fits `int8` becomes `integer` with a `bigint`
+ *     payload, so it reaches PostgreSQL exact. That needs a binding that lowers
+ *     `s64` from `BigInt`: componentize-qjs 0.4.4-di.5 or later (default
+ *     runtime) or jco. Older componentize-qjs bindings trap on it.
+ *   - A `bigint` outside the `int8` range is sent as `text` (OID 0), so
+ *     PostgreSQL parses it for a `numeric` column instead of the binding
+ *     wrapping it modulo 2^64.
  * - A `number` that is an integer outside the safe range throws a `TypeError`
  *   (pass a `bigint` or string for `int8`); other non-safe numbers, including
  *   NaN and Infinity, are `real` (`float8`).
@@ -101,14 +111,20 @@ export function toWasmPgValue(value) {
         return { tag: 'null' };
     switch (typeof value) {
         case 'bigint':
-            // componentize-qjs lowers WIT s64 from JS numbers (f64), not BigInt (#153).
+            // Safe values go as Numbers so bindings that lower s64 only from Numbers
+            // (componentize-qjs before 0.4.4-di.5, --sync, --opt-size) keep working.
             if (value >= MIN_SAFE && value <= MAX_SAFE) {
                 return { tag: 'integer', val: Number(value) };
             }
+            // Past 2^53 only a BigInt is exact (componentize-qjs 0.4.4-di.5+, jco).
+            if (value >= MIN_INT8 && value <= MAX_INT8) {
+                return { tag: 'integer', val: value };
+            }
             return { tag: 'text', val: value.toString() };
         case 'number':
             if (Number.isSafeInteger(value)) {
-                return { tag: 'integer', val: value };
+                // `+ 0` turns -0 into 0, which is the int8 PostgreSQL stores anyway.
+                return { tag: 'integer', val: value + 0 };
             }
             if (Number.isInteger(value)) {
                 // An integral double past 2^53 has already lost its low bits, and the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@di-framework/pglite-component",
-  "version": "6.0.15",
+  "version": "6.0.17",
   "type": "module",
   "description": "Embedded PostgreSQL component with persistent WASI storage and no TCP, plus its SqlDatabase adapter for @di-framework/repo.",
   "license": "(MIT OR Apache-2.0)",

package/wit/deps/pglite-engine-bootstrap/bootstrap.wit

@@ -0,0 +1,22 @@
+package di-framework:pglite-engine-bootstrap@0.1.0;
+
+/// Private: a second, single-use instance of the bundled engine that runs
+/// initdb on an empty data directory (#212).
+///
+/// The functions match `di-framework:pglite-engine/engine@0.1.0`; the build
+/// composes this import from a second instance of the same engine component
+/// (see `scripts/build.ts`). Like the engine import, it is never a host import
+/// in the final artifact.
+///
+/// Why a second instance: the engine's first backend session after initdb
+/// runs initdb's post-bootstrap SQL, which creates the `postgres` database
+/// from a `template1` session, and a single-user backend cannot change
+/// databases afterwards. The provider therefore initializes the cluster here
+/// and serves every session, the first included, from the main engine
+/// instance booted on the existing cluster with the selected database.
+interface bootstrap {
+  set-env: func(name: string, value: string) -> s32;
+  start: func(arguments: list<string>) -> s32;
+  initdb: func() -> s32;
+  backend: func();
+}

package/wit/world.wit

@@ -91,7 +91,15 @@ interface types {
   /// Options accepted by `open`. Every field is optional; `none` means the
   /// documented default.
   record open-options {
-    /// Database name for the session. Only `template1` is currently supported.
+    /// Database name for the session: `postgres` or `template1`.
+    ///
+    /// `none` selects the data directory's default. A directory this
+    /// provider initializes keeps application data in `postgres` and records
+    /// that with a `di-framework-database` marker in PGDATA. A directory
+    /// without the marker (one created by an earlier release) keeps using
+    /// `template1`, unchanged. `template0` and every other name fail `open`.
+    /// The engine stays in the database its first `open` selected until the
+    /// component restarts; a later `open` naming another one fails.
     database: option<string>,
     /// Reserved: WASI lacks the signal timer used for query cancellation.
     /// Only none or zero is supported; nonzero values fail open.
@@ -114,7 +122,7 @@ interface database {
   /// are supported. Close/drop releases the connection for reuse at that root.
   open: func(path: string, options: option<open-options>) -> result<connection, error>;
 
-  /// The bundled engine version string, `17.5`; does not open a database.
+  /// The bundled engine version string, `17.11`; does not open a database.
   server-version: func() -> result<string, error>;
 
   /// An exclusive handle to the embedded session. Closing or dropping it
@@ -174,10 +182,11 @@ interface database {
 /// Kept symmetric with the sqlite-component: `types` is exported explicitly
 /// so the component is self-contained for `wac plug`.
 ///
-/// The private engine import is resolved during the provider build. The
+/// The private engine imports are resolved during the provider build. The
 /// shipped artifact has only WASI imports, including filesystem and randomness.
 world pglite-provider {
   import di-framework:pglite-engine/engine@0.1.0;
+  import di-framework:pglite-engine-bootstrap/bootstrap@0.1.0;
   export types;
   export database;
 }