diff --git a/PUBLISH.md b/PUBLISH.md index e86e4703..fedc2e2a 100644 --- a/PUBLISH.md +++ b/PUBLISH.md @@ -174,6 +174,56 @@ npm install libpg-query@pg18 # full API npm install libpg-query@pg17 # parse only ``` +## Low-Memory Variants (pg18-lowmem-*) + +Special opt-in builds with a smaller WebAssembly memory floor, published under +dedicated dist-tags so they can never affect `latest` or `pg18`. The Makefiles +accept overrides (defaults unchanged: 128MiB initial / 1GiB max / 32MiB stack): + +| Tag | WASM_INITIAL_MEMORY | WASM_STACK_SIZE | +|------------------|---------------------|-----------------| +| `pg18-lowmem-16` | 16777216 (16MiB) | 4194304 (4MiB) | +| `pg18-lowmem-32` | 33554432 (32MiB) | 8388608 (8MiB) | +| `pg18-lowmem-64` | 67108864 (64MiB) | 33554432 (32MiB, default) | + +Note: `INITIAL_MEMORY` must exceed `STACK_SIZE` + static data (~2.5MiB), which +is why the smaller floors also lower the stack. A smaller stack only limits +extremely deep expression nesting (depth 5000 still parses on the 4MiB stack). + +### Exact publish steps (per variant) + +```bash +# 1. Start clean — the working tree must have no uncommitted changes +git status + +cd versions/18 + +# 2. Set a prerelease version so it can never shadow a normal release. +# Pattern: -lowmem-. e.g. 18.1.5-lowmem-32.0 +npm version 18.1.5-lowmem-32.0 --no-git-tag-version + +# 3. Build the wasm with the memory overrides (32MiB floor shown) +pnpm wasm:clean +pnpm wasm:make build WASM_INITIAL_MEMORY=33554432 WASM_STACK_SIZE=8388608 +pnpm build:js + +# 4. Test against the variant build +pnpm test + +# 5. Publish under the variant tag (TAG overrides x-publish.distTag) +TAG=pg18-lowmem-32 pnpm run publish:pkg + +# 6. IMPORTANT: revert the version bump and rebuild the default wasm so the +# working tree is back to the normal publish state +git checkout -- package.json +pnpm build + +# 7. Verify the tags: latest/pg18 must be untouched +npm dist-tag ls libpg-query +``` + +Consumers install with e.g. `npm install libpg-query@pg18-lowmem-32`. + ## Parser Package (@pgsql/parser) ### Quick Publish diff --git a/versions/18/Makefile b/versions/18/Makefile index 2074e8ec..d1b233be 100644 --- a/versions/18/Makefile +++ b/versions/18/Makefile @@ -6,6 +6,12 @@ WASM_OUT_DIR := wasm WASM_OUT_NAME := libpg-query WASM_MODULE_NAME := PgQueryModule + +# WASM memory configuration (bytes). Override on the make command line for +# low-memory variants, e.g. `make build WASM_INITIAL_MEMORY=33554432` (32MiB). +WASM_INITIAL_MEMORY ?= 134217728 +WASM_MAXIMUM_MEMORY ?= 1073741824 +WASM_STACK_SIZE ?= 33554432 # LIBPG_QUERY_REPO := https://github.com/pganalyze/libpg_query.git # LIBPG_QUERY_TAG := 18.0.0 LIBPG_QUERY_REPO := https://github.com/constructive-io/libpg_query.git @@ -73,9 +79,9 @@ ifdef EMSCRIPTEN -sMODULARIZE=1 \ -sEXPORT_ES6=0 \ -sALLOW_MEMORY_GROWTH=1 \ - -sINITIAL_MEMORY=134217728 \ - -sMAXIMUM_MEMORY=1073741824 \ - -sSTACK_SIZE=33554432 \ + -sINITIAL_MEMORY=$(WASM_INITIAL_MEMORY) \ + -sMAXIMUM_MEMORY=$(WASM_MAXIMUM_MEMORY) \ + -sSTACK_SIZE=$(WASM_STACK_SIZE) \ -lpg_query \ -o $@ \ $(SRC_FILES)