From f164120a3159109446de2fc95ea9a5a5c84f23fe Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Sat, 22 Aug 2026 01:00:59 +0000 Subject: [PATCH 1/2] feat: make wasm memory flags overridable and document pg18-lowmem-* publish flow --- PUBLISH.md | 50 +++++++++++++++++++++++++++++++++++++ templates/Makefile.template | 12 ++++++--- versions/13/Makefile | 12 ++++++--- versions/14/Makefile | 12 ++++++--- versions/15/Makefile | 12 ++++++--- versions/16/Makefile | 12 ++++++--- versions/17/Makefile | 12 ++++++--- versions/18/Makefile | 12 ++++++--- 8 files changed, 113 insertions(+), 21 deletions(-) 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/templates/Makefile.template b/templates/Makefile.template index 340d51ff..a3d05be7 100644 --- a/templates/Makefile.template +++ b/templates/Makefile.template @@ -1,6 +1,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 := {{VERSION_TAG}} @@ -71,9 +77,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) diff --git a/versions/13/Makefile b/versions/13/Makefile index 4ace1182..0d3af13f 100644 --- a/versions/13/Makefile +++ b/versions/13/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 := 13-2.2.0 @@ -74,9 +80,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) diff --git a/versions/14/Makefile b/versions/14/Makefile index 1d9b0738..aeaa4981 100644 --- a/versions/14/Makefile +++ b/versions/14/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 := 14-3.0.0 @@ -71,9 +77,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) diff --git a/versions/15/Makefile b/versions/15/Makefile index 68777d3b..d0d6ffdd 100644 --- a/versions/15/Makefile +++ b/versions/15/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 := 15-4.2.4 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) diff --git a/versions/16/Makefile b/versions/16/Makefile index 6bd9e62a..ad45e489 100644 --- a/versions/16/Makefile +++ b/versions/16/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 := 16-5.2.0 @@ -71,9 +77,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) diff --git a/versions/17/Makefile b/versions/17/Makefile index 2d091cba..2078165b 100644 --- a/versions/17/Makefile +++ b/versions/17/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 := 17-6.1.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) 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) From 8bfb1ef84d98ab1f85cb439799a4e99cf76c3c45 Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Sat, 22 Aug 2026 01:05:47 +0000 Subject: [PATCH 2/2] revert: scope wasm memory overrides to v18 only --- templates/Makefile.template | 12 +++--------- versions/13/Makefile | 12 +++--------- versions/14/Makefile | 12 +++--------- versions/15/Makefile | 12 +++--------- versions/16/Makefile | 12 +++--------- versions/17/Makefile | 12 +++--------- 6 files changed, 18 insertions(+), 54 deletions(-) diff --git a/templates/Makefile.template b/templates/Makefile.template index a3d05be7..340d51ff 100644 --- a/templates/Makefile.template +++ b/templates/Makefile.template @@ -1,12 +1,6 @@ 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 := {{VERSION_TAG}} @@ -77,9 +71,9 @@ ifdef EMSCRIPTEN -sMODULARIZE=1 \ -sEXPORT_ES6=0 \ -sALLOW_MEMORY_GROWTH=1 \ - -sINITIAL_MEMORY=$(WASM_INITIAL_MEMORY) \ - -sMAXIMUM_MEMORY=$(WASM_MAXIMUM_MEMORY) \ - -sSTACK_SIZE=$(WASM_STACK_SIZE) \ + -sINITIAL_MEMORY=134217728 \ + -sMAXIMUM_MEMORY=1073741824 \ + -sSTACK_SIZE=33554432 \ -lpg_query \ -o $@ \ $(SRC_FILES) diff --git a/versions/13/Makefile b/versions/13/Makefile index 0d3af13f..4ace1182 100644 --- a/versions/13/Makefile +++ b/versions/13/Makefile @@ -6,12 +6,6 @@ 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 := 13-2.2.0 @@ -80,9 +74,9 @@ ifdef EMSCRIPTEN -sMODULARIZE=1 \ -sEXPORT_ES6=0 \ -sALLOW_MEMORY_GROWTH=1 \ - -sINITIAL_MEMORY=$(WASM_INITIAL_MEMORY) \ - -sMAXIMUM_MEMORY=$(WASM_MAXIMUM_MEMORY) \ - -sSTACK_SIZE=$(WASM_STACK_SIZE) \ + -sINITIAL_MEMORY=134217728 \ + -sMAXIMUM_MEMORY=1073741824 \ + -sSTACK_SIZE=33554432 \ -lpg_query \ -o $@ \ $(SRC_FILES) diff --git a/versions/14/Makefile b/versions/14/Makefile index aeaa4981..1d9b0738 100644 --- a/versions/14/Makefile +++ b/versions/14/Makefile @@ -6,12 +6,6 @@ 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 := 14-3.0.0 @@ -77,9 +71,9 @@ ifdef EMSCRIPTEN -sMODULARIZE=1 \ -sEXPORT_ES6=0 \ -sALLOW_MEMORY_GROWTH=1 \ - -sINITIAL_MEMORY=$(WASM_INITIAL_MEMORY) \ - -sMAXIMUM_MEMORY=$(WASM_MAXIMUM_MEMORY) \ - -sSTACK_SIZE=$(WASM_STACK_SIZE) \ + -sINITIAL_MEMORY=134217728 \ + -sMAXIMUM_MEMORY=1073741824 \ + -sSTACK_SIZE=33554432 \ -lpg_query \ -o $@ \ $(SRC_FILES) diff --git a/versions/15/Makefile b/versions/15/Makefile index d0d6ffdd..68777d3b 100644 --- a/versions/15/Makefile +++ b/versions/15/Makefile @@ -6,12 +6,6 @@ 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 := 15-4.2.4 LIBPG_QUERY_REPO := https://github.com/constructive-io/libpg_query.git @@ -79,9 +73,9 @@ ifdef EMSCRIPTEN -sMODULARIZE=1 \ -sEXPORT_ES6=0 \ -sALLOW_MEMORY_GROWTH=1 \ - -sINITIAL_MEMORY=$(WASM_INITIAL_MEMORY) \ - -sMAXIMUM_MEMORY=$(WASM_MAXIMUM_MEMORY) \ - -sSTACK_SIZE=$(WASM_STACK_SIZE) \ + -sINITIAL_MEMORY=134217728 \ + -sMAXIMUM_MEMORY=1073741824 \ + -sSTACK_SIZE=33554432 \ -lpg_query \ -o $@ \ $(SRC_FILES) diff --git a/versions/16/Makefile b/versions/16/Makefile index ad45e489..6bd9e62a 100644 --- a/versions/16/Makefile +++ b/versions/16/Makefile @@ -6,12 +6,6 @@ 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 := 16-5.2.0 @@ -77,9 +71,9 @@ ifdef EMSCRIPTEN -sMODULARIZE=1 \ -sEXPORT_ES6=0 \ -sALLOW_MEMORY_GROWTH=1 \ - -sINITIAL_MEMORY=$(WASM_INITIAL_MEMORY) \ - -sMAXIMUM_MEMORY=$(WASM_MAXIMUM_MEMORY) \ - -sSTACK_SIZE=$(WASM_STACK_SIZE) \ + -sINITIAL_MEMORY=134217728 \ + -sMAXIMUM_MEMORY=1073741824 \ + -sSTACK_SIZE=33554432 \ -lpg_query \ -o $@ \ $(SRC_FILES) diff --git a/versions/17/Makefile b/versions/17/Makefile index 2078165b..2d091cba 100644 --- a/versions/17/Makefile +++ b/versions/17/Makefile @@ -6,12 +6,6 @@ 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 := 17-6.1.0 LIBPG_QUERY_REPO := https://github.com/constructive-io/libpg_query.git @@ -79,9 +73,9 @@ ifdef EMSCRIPTEN -sMODULARIZE=1 \ -sEXPORT_ES6=0 \ -sALLOW_MEMORY_GROWTH=1 \ - -sINITIAL_MEMORY=$(WASM_INITIAL_MEMORY) \ - -sMAXIMUM_MEMORY=$(WASM_MAXIMUM_MEMORY) \ - -sSTACK_SIZE=$(WASM_STACK_SIZE) \ + -sINITIAL_MEMORY=134217728 \ + -sMAXIMUM_MEMORY=1073741824 \ + -sSTACK_SIZE=33554432 \ -lpg_query \ -o $@ \ $(SRC_FILES)