From 52f41a744ca81604d9b65df7963636a91cc4dd54 Mon Sep 17 00:00:00 2001 From: TimelordUK Date: Sun, 13 Sep 2026 11:33:09 +0100 Subject: [PATCH] feat!: declare the platforms and Node versions actually supported BREAKING CHANGE: engines requires node >=22 (was >=18), and cpu is now declared as ["x64", "arm64"], which makes npm refuse 32-bit Windows outright. The old numbers were picked when every Node ABI needed its own binary and the matrix ran to over a hundred artifacts; they were a cut-off, not a support statement. Nothing verified them, and they disagreed with CI: engines promised node >=18 while the test matrix only ever ran 22, 24 and 26. Node 18 and 20 were therefore completely untested, which is exactly the gap that produces a "doesn't work on my Node 18 app" report we cannot answer. Supported now means something checkable: a Node line that upstream still supports, which CI tests on every commit. Node 18 reached end-of-life on 2025-04-30 and Node 20 on 2026-04-30, so node >=22 states the real position and matches the matrix exactly. Nothing in the code needed a floor this high - lib/ bottoms out at Object.hasOwn (Node 16.9), node-addon-api 8 accepts ^18 || ^20 || >= 21, and N-API 8 goes back to Node 12.22. The constraint is support, not capability, and saying so is the point. The 32-bit Windows change fixes a field that was not doing what it looked like. `os: ["win32"]` does not mean 32-bit: win32 is Node's platform string for ALL Windows, including 64-bit. There was no cpu field at all, so 32-bit installs were permitted and then failed at load. Declaring cpu produces a hard EBADPLATFORM at install instead. Both behaviours were verified rather than assumed, using fixtures whose constraints cannot match this machine: - cpu: ["mips"] -> npm error EBADPLATFORM, exit 1 - engines: { >=99 } -> npm warn EBADENGINE, exit 0 -> with engine-strict=true: error, exit 1 That difference is why this is a breaking change. engines only warns under default npm, but pnpm and engine-strict setups fail hard, so narrowing it can break someone's install. Note npm's --os / --cpu flags do NOT simulate the check - they force optional dependency selection, and an install with --cpu=ia32 still succeeds. They are not a way to test this. Docs corrected to match, in README.md and the release template so the next release inherits it rather than repeating the old claims: - "Prebuilt binaries are downloaded automatically" - they have not been since 5.5.0; they ship in the package. - macOS was listed as x64 + arm64; only arm64 is bundled. - Windows was listed as x64 + ia32. - glibc was listed as >= 2.28; the builder is Ubuntu 22.04, so 2.35+. - "Electron binaries are published alongside Node binaries" - there are no separate Electron artifacts any more. - "win32 is no longer supported" now reads "32-bit Windows (ia32)", because the old phrasing reads as dropping Windows entirely. - The "prebuilt binary fails to load" entry no longer blames a Node ABI or Electron mismatch, which cannot be the cause of an N-API build failing. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01K5wuZia58hUzEqN7CvHtz9 --- .github/RELEASE_TEMPLATE.md | 18 ++++++++++++--- README.md | 45 ++++++++++++++++++++++++++++--------- package.json | 6 ++++- 3 files changed, 55 insertions(+), 14 deletions(-) diff --git a/.github/RELEASE_TEMPLATE.md b/.github/RELEASE_TEMPLATE.md index 1a51a2fd..20f94249 100644 --- a/.github/RELEASE_TEMPLATE.md +++ b/.github/RELEASE_TEMPLATE.md @@ -73,8 +73,18 @@ ABI coupling. Where there is no bundled binary the `install` script falls back to a `node-gyp` source build, which needs a C++ toolchain and the unixODBC headers. -**Runtime requirements:** any Node with N-API ≥ 8 (`engines: node >=18`), and -any Electron with N-API ≥ 8. Electron needs no `electron-rebuild` and no +**Supported means: a Node line that upstream still supports, which CI tests on +every commit.** Currently Node 22, 24 and 26, and `engines` requires +`node >=22`. Node 18 (EOL 2025-04-30) and Node 20 (EOL 2026-04-30) are past +upstream end-of-life and are not tested. + +**32-bit Windows (`ia32`) is not supported.** `cpu` is declared as +`["x64", "arm64"]`, so `npm install` refuses with `EBADPLATFORM` rather than +failing later at load. Note `win32` is Node's platform string for *all* +Windows including 64-bit, so "win32 unsupported" would be the wrong way to say +this. + +Any Electron with N-API ≥ 8 works, with no `electron-rebuild` and no Electron-specific artifact.
@@ -218,7 +228,9 @@ production rollout. 4. Linux support requires **glibc 2.35+** (Ubuntu 22.04 or later). Earlier distributions must build the driver themselves. 5. As close to a drop-in replacement for 4.x as possible. -6. **win32 (32-bit Windows) is no longer supported.** +6. **32-bit Windows (`ia32`) is no longer supported**, and `npm install` now + refuses it outright with `EBADPLATFORM`. 64-bit Windows is fully supported - + Node calls it `win32` too, which the old wording made sound otherwise. 7. Windows, Linux and macOS are the supported platforms. 8. Alpine/musl was originally best-effort and out of scope. **As of 5.5.0 a musl binary is built, smoke tested in CI and shipped in the package.** diff --git a/README.md b/README.md index 51498b23..e6abbe23 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,10 @@ Reproduce: `node samples/javascript/benchmark.js --rows 1000,10000,100000 --mode npm install msnodesqlv8 --save ``` -Prebuilt binaries are downloaded automatically for Linux (x64, glibc ≥ 2.28 and musl), macOS (x64, arm64) and Windows (x64, ia32). Electron binaries are published alongside Node binaries for current major versions. +Prebuilt binaries **ship inside the package** - nothing is downloaded at install +time and nothing is compiled on a supported platform. One binary per platform +serves every Node line and every Electron version, because the addon is pure +N-API. See [Platform support](#platform-support) for what is bundled. You also need a Microsoft ODBC driver on the host: @@ -120,13 +123,32 @@ Full runnable projects in their own repos, showing `msnodesqlv8` wired into real ## Platform support -| Platform | Arch | Node | Electron | -| --------------------- | ------------ | ----------------- | -------- | -| Linux (glibc ≥ 2.28) | x64 | 20, 22, 24 | 32+ | -| Linux (musl / Alpine) | x64 | 20, 22, 24 | 32+ | -| macOS | x64, arm64 | 20, 22, 24 | 32+ | -| Windows | x64, ia32 | 20, 22, 24 | 32+ | -| Windows Integrated Auth | x64 | supported via `Trusted_Connection=yes` | — | +**Supported means: a Node line that upstream still supports, which CI tests on +every commit.** Currently that is Node 22, 24 and 26. `engines` requires +`node >=22`; older lines are past their upstream end-of-life (Node 18 ended +2025-04-30, Node 20 ended 2026-04-30) and are not tested here. + +Binaries bundled in the published package: + +| Platform | Arch | Bundled | Notes | +| ----------------------- | ------- | ------- | --------------------------------------- | +| Windows | x64 | yes | | +| Linux (glibc) | x64 | yes | built on Ubuntu 22.04, needs glibc 2.35+ | +| Linux (musl / Alpine) | x64 | yes | built in `node:22-alpine` | +| macOS | arm64 | yes | Apple Silicon | +| macOS | x64 | no | compiles from source on install | +| Linux | arm64 | no | compiles from source on install | +| Windows | arm64 | no | compiles from source on install | + +**32-bit Windows (`ia32`) is not supported.** `npm install` refuses with +`EBADPLATFORM` rather than failing later at load. Note that Node reports +*64-bit* Windows as platform `win32` too - `win32` is not the same as 32-bit. + +Any Electron with N-API ≥ 8 works, with no `electron-rebuild` and no +Electron-specific artifact. Verified against Electron 41 (ABI 145) and 43 +(ABI 148) on the same single binary. + +Windows Integrated Auth (x64) is supported via `Trusted_Connection=yes`. Tested against SQL Server 2017, 2019, 2022. Sybase ASE support is smaller in scope — see [samples/javascript/sybase-query.js](samples/javascript/sybase-query.js) and the wiki. @@ -138,11 +160,14 @@ Tested against SQL Server 2017, 2019, 2022. Sybase ASE support is smaller in sco **`SSL Provider: certificate verify failed`** on newer SQL Server — add `Encrypt=yes;TrustServerCertificate=yes` to the connection string, or install the server certificate. -**Segfault on Ubuntu/Debian with Node 18/20** — requires OpenSSL 3.2. See `tool/openssl.sh` in this repo and the [wiki install notes](https://github.com/TimelordUK/node-sqlserver-v8/wiki). +**Segfault on Ubuntu/Debian with Node 18/20** — requires OpenSSL 3.2. See `tool/openssl.sh` in this repo and the [wiki install notes](https://github.com/TimelordUK/node-sqlserver-v8/wiki). Node 18 and 20 are both past end-of-life and are no longer supported; on Node 22+ this does not arise. **BCP crashes or silently falls back** — BCP requires ODBC Driver 17 or 18 *exactly*. Any older driver (SQL Server Native Client, FreeTDS) will either crash the process or silently no-op. Check with `odbcinst -q -d`. -**Prebuilt binary fails to load** — your glibc, Node ABI or Electron version may not match a published binary. Try building from source: [docs/building-from-source.md](docs/building-from-source.md). +**Prebuilt binary fails to load** — the bundled binaries are not ABI-specific, so +a Node or Electron version mismatch is not the cause. The likely reasons are an +unbundled platform (see the table above), or glibc older than 2.35 on Linux. +Build from source: [docs/building-from-source.md](docs/building-from-source.md). More issues and workarounds: [GitHub Issues](https://github.com/TimelordUK/node-sqlserver-v8/issues). diff --git a/package.json b/package.json index 1feffc42..a9ae4e81 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,7 @@ "url": "git+https://github.com/TimelordUK/node-sqlserver-v8.git" }, "engines": { - "node": ">=18" + "node": ">=22" }, "files": [ "lib/", @@ -74,6 +74,10 @@ "linux", "darwin" ], + "cpu": [ + "x64", + "arm64" + ], "scripts": { "build": "tsc", "build:test": "tsc -p tsconfig.json",