# Publishing Guide ## Keeping the C source in sync Each `versions//package.json` pins its libpg_query source in `x-publish` (`libpgQueryRepo`, `libpgQueryTag`, `libpgQueryCommit`), and the Docker build uses `emscripten/emsdk:6.0.3`. Every generated Makefile and the protobufs come from those pins, and the pins ship in the published package.json. To move a version to new C code, do all of this in one commit: ```bash # 1. edit x-publish.libpgQueryCommit (full 40-char SHA) in versions//package.json pnpm copy:templates # regenerate the Makefiles pnpm fetch:protos # protos//pg_query.proto at the new commit pnpm build:types && pnpm build:enums cd versions/ && pnpm build && pnpm test ``` If you skip the build when publishing, `versions//wasm/` must have been built after the last pin change, or the package will name one commit and ship another. After publishing, `npm view libpg-query@pg x-publish` should show the commit you expect. `publish:pkg` also writes `x-publish.wasmSha256`, the sha256 of `wasm/libpg-query.wasm` and `wasm/libpg-query.js`, into the published package.json. To verify a release, check out the `gitHead` it was published from, run `pnpm wasm:build` in `versions/`, and compare `sha256sum wasm/libpg-query.*` with `npm view libpg-query@ x-publish.wasmSha256`. ## Automated Publishing (Recommended) ### Version Packages (libpg-query) ```bash pnpm run publish:versions ``` This interactive script will: - Check for uncommitted changes (will error if any exist) - Let you select which versions to publish (or all) - Ask for version bump type (patch or minor only) - Ask if you want to skip the build step (useful if already built) - Always run tests (even if build is skipped) - Publish each selected version - If the highest major (pg18) was published, optionally promote it to `latest` ### Types Packages ```bash pnpm run publish:types ``` This interactive script will: - Check for uncommitted changes (will error if any exist) - Let you select which versions to publish (or all) - Ask for version bump type (patch or minor only) - Build, prepare, and publish each selected version - Optionally promote pg17 to latest ### Enums Packages ```bash pnpm run publish:enums ``` This interactive script will: - Check for uncommitted changes (will error if any exist) - Let you select which versions to publish (or all) - Ask for version bump type (patch or minor only) - Build, prepare, and publish each selected version - Optionally promote pg17 to latest ### Parser Package The parser package supports multiple build configurations: #### Full Build (all versions 13-18) ```bash pnpm run publish:parser # or with specific build type PARSER_BUILD_TYPE=full pnpm run publish:parser ``` #### LTS Build (versions 15-18) ```bash PARSER_BUILD_TYPE=lts pnpm run publish:parser ``` This command will: - Navigate to the parser directory - Build the parser with the specified configuration - Publish the @pgsql/parser package to npm with appropriate dist-tag - Note: You should manually bump the version and commit changes before running this - **Prerequisite**: The version packages must be built first as the parser copies their WASM files during build ## Manual Publishing ### Types Packages ```bash # Set the version (e.g. 17, 16, 15, etc.) VERSION=18 cd types/${VERSION} pnpm version patch git add . && git commit -m "release: bump @pgsql/types${VERSION} version" pnpm build pnpm prepare:types pnpm publish --tag pg${VERSION} ``` Promote to latest (optional) ```bash # Set the version (e.g. 17, 16, 15, etc.) VERSION=18 # Promote pg${VERSION} tag to latest npm dist-tag add @pgsql/types@pg${VERSION} latest ``` ### What it does - Transforms `@libpg-query/types17` → `@pgsql/types` with tag `pg17` - Transforms `@libpg-query/types16` → `@pgsql/types` with tag `pg16` - etc. ### Enums Packages ```bash # Set the version (e.g. 17, 16, 15, etc.) VERSION=18 cd enums/${VERSION} pnpm version patch git add . && git commit -m "release: bump @pgsql/enums${VERSION} version" pnpm build pnpm prepare:enums pnpm publish --tag pg${VERSION} ``` Promote to latest (optional) ```bash # Set the version (e.g. 17, 16, 15, etc.) VERSION=18 # Promote pg${VERSION} tag to latest npm dist-tag add @pgsql/enums@pg${VERSION} latest ``` ### What it does - Transforms `@libpg-query/enums17` → `@pgsql/enums` with tag `pg17` - Transforms `@libpg-query/enums16` → `@pgsql/enums` with tag `pg16` - etc. ## Version Packages ### Quick Publish ```bash # Set the version (e.g. 17, 16, 15, etc.) VERSION=18 # Build and publish a specific version cd versions/${VERSION} pnpm version patch git add . && git commit -m "release: bump libpg-query${VERSION} version" pnpm build pnpm test pnpm run publish:pkg ``` ### What it does - Transforms `@libpg-query/v17` → `libpg-query` with tag `pg17` - Transforms `@libpg-query/v16` → `libpg-query` with tag `pg16` - Uses `x-publish.publishName` and `x-publish.distTag` from package.json - Temporarily modifies package.json during publish, then restores it ### Install published packages ```bash npm install libpg-query@pg17 # PostgreSQL 17 specific npm install libpg-query@pg16 # PostgreSQL 16 specific npm install libpg-query # Latest/default version ``` ## Full API on PG 18+ The former `full/` package (`@libpg-query/parser`) has been retired. Starting with PostgreSQL 18, the regular `libpg-query` package (`versions/18`) ships the full API: `parse`, `parsePlPgSQL`, `scan`, `fingerprint`, `normalize` + sync variants. Versions 13–17 remain slim (parse only). ```bash npm install libpg-query@pg18 # full API npm install libpg-query@pg17 # parse only ``` ## WASM memory defaults Every major builds with `WASM_INITIAL_MEMORY=41943040` (40MiB), `WASM_STACK_SIZE=33554432` (32MiB) and `WASM_MAXIMUM_MEMORY=1073741824` (1GiB), set in `templates/Makefile.template`. The initial size is only the floor: the heap grows on demand up to the maximum, so it decides the idle footprint of a parser instance (about 42MiB of V8 `external` memory), not the largest input it can parse. The 32MiB stack is what prevents deep-recursion traps, and untouched stack pages cost no resident memory, so it is never lowered. There are no separate low-memory releases. If a downstream user needs an ad-hoc build with a different floor, override it on the build line and keep the stack: ```bash pnpm wasm:make build WASM_INITIAL_MEMORY=50331648 # 48MiB floor; never set WASM_STACK_SIZE below 33554432 ``` ### Later, separate step: retire the `pg18-lowmem-*` dist-tags The `pg18-lowmem-16/-32/-64` tags point at pre-`18.2.x` builds with 4/8MiB stacks. Do this only after downstream users (Supabase) have been notified; it is not part of a release: ```bash npm dist-tag rm libpg-query pg18-lowmem-16 npm dist-tag rm libpg-query pg18-lowmem-32 npm dist-tag rm libpg-query pg18-lowmem-64 ``` ## Parser Package (@pgsql/parser) ### Quick Publish ```bash cd parser pnpm version patch git add . && git commit -m "release: bump @pgsql/parser version" pnpm build pnpm test pnpm publish ``` ### Build Configurations The parser package is now a simple distribution package that copies pre-built WASM files. No TypeScript compilation needed! #### Available Build Types: - **full**: All versions (13, 14, 15, 16, 17, 18) - Default - **lts**: LTS versions only (15, 16, 17, 18) ```bash # Full build (default) npm run build # LTS build npm run build:lts # Or using environment variable PARSER_BUILD_TYPE=lts npm run build ``` ### Build Process The simplified parser package: 1. Copies WASM files from the `versions/*/wasm/` directories 2. Copies TypeScript type definitions from the `types/*/dist/` directories 3. Updates import paths to use local types instead of `@pgsql/types` 4. Generates index files from templates based on the build configuration 5. Creates version-specific export files 6. Creates a `build-info.json` file documenting what was included The templates automatically adjust to include only the versions specified in the build configuration, ensuring proper TypeScript types and runtime validation. The package is completely self-contained with all necessary types bundled. **Note**: Build scripts use `cross-env` for Windows compatibility. **Important**: Before building the parser package, ensure that the version packages are built first: ```bash # Build all version packages first pnpm build:versions # Then build the parser with desired configuration cd parser npm run build:lts # or build:full ``` ### Types Bundling The parser build process automatically: 1. Copies TypeScript type definitions from `types/*/dist/` directories 2. Places them in `wasm/v*/types/` for each version 3. Updates all import references from `@pgsql/types` to `./types` 4. Makes the package self-contained without external type dependencies ### Publishing with Different Tags ```bash # Publish full version as latest npm run build:full npm publish # Publish LTS version with lts tag npm run build:lts npm publish --tag lts ``` ### What it does - Publishes `@pgsql/parser` - a multi-version PostgreSQL parser with dynamic version selection - Provides a unified interface to work with multiple PostgreSQL versions - Supports different build configurations for different use cases - Includes both CommonJS and ESM builds - Exports version-specific parsers via subpaths (e.g., `@pgsql/parser/v17`) - **Self-contained**: Bundles TypeScript types locally (no external @pgsql/types dependency) ### Install published package ```bash # Install latest (full build) npm install @pgsql/parser # Use version-specific imports: # import { parse } from '@pgsql/parser/v17' # import { parse } from '@pgsql/parser/v16' # import { parse } from '@pgsql/parser/v13' ``` ### Alternative: Using npm scripts from root ```bash # From the repository root: pnpm build:parser # Build the parser package (full build) PARSER_BUILD_TYPE=lts pnpm build:parser # Build LTS version pnpm publish:parser # Publish the parser package ```