build.yml

name: build

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  release:
    types:
      - released
  workflow_dispatch: {}

env:
  # See https://github.com/nodejs/release#release-schedule
  # Node.js v20 EOL = 2026-04-30. v22 EOL = 2027-04-30. v23 EOL = 2025-06-01. v24 EOL = 2028-04-30. v25 EOL = 2026-06-01. v26 EOL = TBD.
  # prebuildify writes per-ABI binaries into prebuilds/<platform>-<arch>/;
  # each job uploads that directory as an artifact and the publish job merges
  # them all into the npm package (no more GitHub-release download step).
  # Linux jobs append --tag-libc so glibc and musl binaries can coexist in the
  # same prebuilds/linux-<arch>/ directory.
  # --no-napi: better-sqlite3 uses V8 APIs directly, so binaries are per-ABI.
  # --name node: emit canonical node-gyp-build names (node.abi<N>[.<libc>].node)
  # instead of prebuildify's package-name default, which would drop the
  # runtime/abi tags that node-gyp-build matches on.
  # Node.js 22-24 can build with GCC 10 (bullseye). No Node.js 20 binaries:
  # the addon uses V8 APIs that Node.js 20 lacks, and `engines` is 22.x || 24.x.
  NODE_BUILD_CMD_LEGACY: npx --no-install prebuildify --strip --no-napi --name node -t 22.0.0 -t 23.0.0 -t 24.0.0
  # Node.js 25+ requires GCC 11+ for <source_location> header (bookworm)
  NODE_BUILD_CMD_MODERN: npx --no-install prebuildify --strip --no-napi --name node -t 25.0.0 -t 26.0.0

jobs:
  test:
    strategy:
      fail-fast: false
      matrix:
        os:
          - ubuntu-22.04
          - macos-15
          - macos-15-intel
          - windows-2022
        node:
          - 22
          - 24
          - 26
        # Node 26 on Windows can't build: Node 26's bundled gyp config feeds
        # Clang/LLD ThinLTO flags (-flto=thin, /opt:lldltojobs) into the MSVC link
        # step, which link.exe rejects (LNK1117). Upstream Node 26 + MSVC toolchain
        # bug -- our build sets no LTO flags, and Node <=25 on Windows is fine.
        # Revisit when the upstream toolchain is fixed. (Node 26 prebuilds still
        # ship for macOS/Linux via NODE_BUILD_CMD_MODERN; the release-time Windows
        # prebuild will need the same exclusion before it builds Node 26.)
        exclude:
          - os: windows-2022
            node: 26
    name: Testing Node ${{ matrix.node }} on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          # Node 24.19.0+ (through at least 24.21.0) aborts when it garbage
          # collects a node::ObjectWrap compiled against its own headers: the
          # header's destructor calls RemoveEnvironmentCleanupHook, which the
          # 24.x runtime can't handle without a current Environment
          # (https://github.com/nodejs/node/issues/65446). The release
          # prebuilds compile against 24.0.0 headers and are unaffected.
          # Unpin once a 24.x release ships the fix.
          node-version: ${{ matrix.node == 24 && '24.18.1' || matrix.node }}
      - if: ${{ startsWith(matrix.os, 'windows') }}
        run: pip.exe install setuptools
      - if: ${{ startsWith(matrix.os, 'macos') }}
        run: brew install python-setuptools icu4c
      - if: ${{ !startsWith(matrix.os, 'windows') && !startsWith(matrix.os, 'macos') }}
        run: python3 -m pip install setuptools
      - if: ${{ startsWith(matrix.os, 'ubuntu') && matrix.node < 25 }}
        run: |
          sudo apt update
          sudo apt install -y gcc-10 g++-10 libreadline-dev libncurses5-dev libicu-dev
          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100 --slave /usr/bin/g++ g++ /usr/bin/g++-10 --slave /usr/bin/gcov gcov /usr/bin/gcov-10
      - if: ${{ startsWith(matrix.os, 'ubuntu') && matrix.node >= 25 }}
        run: |
          sudo apt update
          sudo apt install -y gcc-11 g++-11 libreadline-dev libncurses5-dev libicu-dev
          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100 --slave /usr/bin/g++ g++ /usr/bin/g++-11 --slave /usr/bin/gcov gcov /usr/bin/gcov-11
      - run: npm install --ignore-scripts
      - run: npm run build-debug
      - run: npm test
      - run: npm run build-release
      - name: Test shell wrapper (Windows)
        if: ${{ startsWith(matrix.os, 'windows') }}
        shell: powershell
        run: |
          echo "SELECT 'wrapper test';" | node shell.js
          node shell.js --version
      - name: Test shell wrapper (Unix)
        if: ${{ !startsWith(matrix.os, 'windows') }}
        shell: bash
        run: |
          echo "SELECT 'wrapper test';" | node shell.js
          node shell.js --version

  publish:
    if: ${{ github.event_name == 'release' }}
    name: Publishing to NPM
    runs-on: ubuntu-22.04
    permissions:
      id-token: write # Required for OIDC trusted publishing
      contents: read
    needs:
      - prebuild
      - prebuild-alpine
      - prebuild-alpine-arm64
      - prebuild-linux-x64
      - prebuild-linux-arm64
      - prebuild-linux-x64-node-modern
      - prebuild-linux-arm64-node-modern
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          node-version: 24.15.0
          registry-url: https://registry.npmjs.org
      - name: Collect prebuilds from all platforms
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          pattern: prebuilds-*
          path: prebuilds
          merge-multiple: true
      - name: Show collected prebuilds
        run: ls -lR prebuilds
      - name: Upgrade npm for OIDC support
        run: npm install -g npm@latest
      - run: npm publish --provenance

  prebuild:
    if: ${{ github.event_name == 'release' }}
    strategy:
      fail-fast: false
      matrix:
        os:
          - macos-15
          - macos-15-intel
          - windows-2022
    name: Prebuild on ${{ matrix.os }}
    runs-on: ${{ matrix.os }}
    needs: test
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          node-version: 20
      - if: ${{ startsWith(matrix.os, 'windows') }}
        run: pip.exe install setuptools
      - if: ${{ startsWith(matrix.os, 'macos') }}
        run: brew install python-setuptools icu4c
      - run: npm install --ignore-scripts
      - run: ${{ env.NODE_BUILD_CMD_LEGACY }}
      - run: ${{ env.NODE_BUILD_CMD_MODERN }}
      - run: node deps/copy-shell.js
      - if: matrix.os == 'windows-2022'
        run: |
          ${{ env.NODE_BUILD_CMD_LEGACY }} --arch ia32
          ${{ env.NODE_BUILD_CMD_MODERN }} --arch ia32
          node deps/copy-shell.js --arch ia32
          ${{ env.NODE_BUILD_CMD_LEGACY }} --arch arm64
          ${{ env.NODE_BUILD_CMD_MODERN }} --arch arm64
          node deps/copy-shell.js --arch arm64
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: prebuilds-${{ matrix.os }}
          path: prebuilds
          if-no-files-found: error

  prebuild-linux-x64:
    if: ${{ github.event_name == 'release' }}
    name: Prebuild on Linux x64
    runs-on: ubuntu-latest
    container: node:20-bullseye
    needs: test
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - run: apt-get update && apt-get install -y libicu-dev
      - run: npm install --ignore-scripts
      - run: ${{ env.NODE_BUILD_CMD_LEGACY }} --tag-libc
      - run: node deps/copy-shell.js
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: prebuilds-linux-x64
          path: prebuilds
          if-no-files-found: error

  prebuild-linux-x64-node-modern:
    if: ${{ github.event_name == 'release' }}
    name: Prebuild on Linux x64 (Node 25+)
    runs-on: ubuntu-latest
    container: node:20-bookworm
    needs: test
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - run: apt-get update && apt-get install -y libicu-dev
      - run: npm install --ignore-scripts
      - run: ${{ env.NODE_BUILD_CMD_MODERN }} --tag-libc
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: prebuilds-linux-x64-node-modern
          path: prebuilds
          if-no-files-found: error

  prebuild-alpine:
    if: ${{ github.event_name == 'release' }}
    name: Prebuild on alpine
    runs-on: ubuntu-latest
    container: node:20-alpine
    needs: test
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - run: apk add build-base git python3 py3-setuptools libstdc++ readline-dev ncurses-dev icu-dev --update-cache
      - run: npm install --ignore-scripts
      - run: ${{ env.NODE_BUILD_CMD_LEGACY }} --tag-libc
      - run: ${{ env.NODE_BUILD_CMD_MODERN }} --tag-libc
      # No copy-shell here: the zero_sqlite3 shell target is not built on
      # alpine (type "none" in binding.gyp).
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: prebuilds-alpine
          path: prebuilds
          if-no-files-found: error

  # arm64 prebuilds run on native GitHub-hosted ARM runners (ubuntu-24.04-arm,
  # free for public repos) instead of QEMU emulation. This is faster and avoids
  # the QEMU "illegal instruction" crashes seen with emulated musl/arm64. 32-bit
  # arm (arm/v7) is no longer built — Zero does not support it.
  # Alpine (musl) arm64: GitHub doesn't support JavaScript actions inside an
  # Alpine *job container* on arm64 runners (only x64), so actions/checkout
  # fails there. Instead check out on the glibc arm64 host and run the build
  # inside `docker run node:20-alpine` — native on the arm64 runner, so still no
  # QEMU.
  prebuild-alpine-arm64:
    if: ${{ github.event_name == 'release' }}
    name: Prebuild on alpine (arm64)
    runs-on: ubuntu-24.04-arm
    needs: test
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - run: |
          docker run --rm -v "$(pwd)":/tmp/project --entrypoint /bin/sh node:20-alpine -c "\
          apk add build-base git python3 py3-setuptools libstdc++ readline-dev ncurses-dev icu-dev --update-cache && \
          cd /tmp/project && \
          npm install --ignore-scripts && \
          ${{ env.NODE_BUILD_CMD_LEGACY }} --tag-libc && \
          ${{ env.NODE_BUILD_CMD_MODERN }} --tag-libc"
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: prebuilds-alpine-arm64
          path: prebuilds
          if-no-files-found: error

  prebuild-linux-arm64:
    if: ${{ github.event_name == 'release' }}
    name: Prebuild on Linux arm64
    runs-on: ubuntu-24.04-arm
    container: node:20-bullseye
    needs: test
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - run: apt-get update && apt-get install -y libicu-dev
      - run: npm install --ignore-scripts
      - run: ${{ env.NODE_BUILD_CMD_LEGACY }} --tag-libc
      - run: node deps/copy-shell.js
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: prebuilds-linux-arm64
          path: prebuilds
          if-no-files-found: error

  prebuild-linux-arm64-node-modern:
    if: ${{ github.event_name == 'release' }}
    name: Prebuild on Linux arm64 (Node 25+)
    runs-on: ubuntu-24.04-arm
    container: node:20-bookworm
    needs: test
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
      - run: apt-get update && apt-get install -y libicu-dev
      - run: npm install --ignore-scripts
      - run: ${{ env.NODE_BUILD_CMD_MODERN }} --tag-libc
      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: prebuilds-linux-arm64-node-modern
          path: prebuilds
          if-no-files-found: error