chdb-rust 2.2.0

chDB FFI bindings for Rust(Experimental)
name: Rust

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

env:
  CARGO_TERM_COLOR: always

jobs:
  # Seconds, and ahead of the build, because a pin that disagrees with itself
  # makes everything after it a test of an engine nobody chose.
  engine_pin:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - run: .github/scripts/check-engine-pin.sh

  build:
    # Not merely ordered before the build — a gate on it. Without this the two run
    # side by side, and a disagreeing pin still downloads an engine, links against
    # it and reports test results for it, which is exactly the misleading outcome
    # the check exists to prevent.
    needs: engine_pin
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, ubuntu-24.04-arm, macos-latest, macos-15-intel]
    runs-on: ${{ matrix.os }}
    steps:
    - uses: actions/checkout@v4
    # --global rather than moving the library into /usr/lib by hand: it installs
    # into /usr/local, which is on the default search path of both loaders, and
    # skips ldconfig where there is none. One command for every platform here,
    # and the same one the README gives users.
    - name: Install the engine
      run: ./update_libchdb.sh --global
    # Once rather than once per platform: neither depends on the target.
    - name: Check formatting
      if: matrix.os == 'ubuntu-latest'
      run: cargo fmt --check
    # Default features only. --all-features enables `static`, which downloads a
    # few hundred megabytes of archive that clippy then does not link; that
    # belongs in the job that links it.
    - name: Check clippy
      if: matrix.os == 'ubuntu-latest'
      run: cargo clippy --all-targets -- --deny warnings
    - name: Build
      run: cargo build --verbose
      env:
        RUST_BACKTRACE: full
    - name: Run tests
      run: cargo test -- --test-threads=1
      env:
        RUST_BACKTRACE: full
    # A second cell of the same matrix rather than a job of its own: the durable
    # protocol is only as good as the engine underneath it, so it has to be
    # exercised on every platform the crate claims, against the engine installed
    # above. The feature is off by default, so nothing else here would compile
    # it, let alone run it.
    - name: Run the durable tests
      run: cargo test --features durable -- --test-threads=1
      env:
        RUST_BACKTRACE: full
    # The S3 backend has no credentials here, and the tests that need a bucket
    # are `#[ignore]`d, so they are reported as ignored rather than run. What
    # this still catches is the half that needs no bucket: that the feature
    # compiles, and that the signer, the URL parsing — including the refusal of
    # a URL carrying credentials — and the status mapping still agree with their
    # unit tests. `durable::` rather than `durable::backends`, because the URL
    # parsing those rest on lives in `durable::namespace`. The real bucket runs
    # locally: `cargo test --features durable-s3 --test durable_s3 -- --ignored`.
    - name: Check the S3 backend
      if: matrix.os == 'ubuntu-latest'
      # Quoted: a plain YAML scalar may not end in a colon.
      run: "cargo test --features durable-s3 --lib -- --test-threads=1 durable::"
      env:
        RUST_BACKTRACE: full

  # Static linking, built and run rather than merely compiled. Until this job
  # existed the only step that enabled the feature was a `clippy --all-features`
  # run, and clippy does not link: the archive was downloaded and nothing was
  # learned from it, while the build and test steps that followed ran against
  # the default dynamic build. That clippy run now lives here, where the archive
  # is on disk for a reason.
  #
  # No libchdb is installed on these runners, deliberately. build.rs downloads
  # the static archive and there is no dynamic library anywhere for the link to
  # reach instead, which is half of what check-static-link.sh then confirms.
  #
  # CHDB_TEST_MIN_MACOS raises the macOS deployment floor of this crate's test
  # binaries and nothing else. That is where the property has to be exercised:
  # under macOS 12 the linker emits no chained fixups, so nothing can rebind a
  # call made inside the archive to the system C++ runtime, and a green run
  # would say nothing about whether it could. The library, the examples and
  # anything a user builds stay at the default floor - see build.rs.
  #
  # It goes through the build script rather than MACOSX_DEPLOYMENT_TARGET
  # because that variable is not part of Cargo's fingerprint: changing it does
  # not relink, so a second cell sharing a target directory would silently
  # re-run the first cell's binaries. A build script's output is fingerprinted.
  static:
    needs: engine_pin
    strategy:
      # The four platforms this crate claims to support. One failing should not
      # hide the others: the two operating systems link with different linkers,
      # only one of them has ever had this problem, and the two architectures
      # get separately built archives.
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
          - os: ubuntu-24.04-arm
          - os: macos-latest
            test_min_macos: "12.0"
          - os: macos-15-intel
            test_min_macos: "12.0"
    runs-on: ${{ matrix.os }}
    env:
      # Empty on the platforms that have no deployment target, which build.rs
      # reads as unset.
      CHDB_TEST_MIN_MACOS: ${{ matrix.test_min_macos }}
    steps:
    - uses: actions/checkout@v4

    # One cell, like the other lints: what clippy reports does not vary by
    # architecture, and this is the step that materialises a second copy of the
    # engine as a static rlib. Leaving it on every cell cost the arm64 runner
    # its disk, and the runner service dies with it - "the runner has received a
    # shutdown signal", exit 143, at the same point in the next step every time.
    - name: Check clippy with every feature
      if: matrix.os == 'ubuntu-latest'
      run: cargo clippy --all-targets --all-features -- --deny warnings

    # --tests, because without it cargo also links the eight examples, and the
    # filter below then discards them: seventeen artifacts of a few hundred
    # megabytes built to keep nine.
    #
    # -j 2, because one link of this crate peaks at 4.7 GiB of resident memory,
    # measured on aarch64 with GNU time. Cargo defaults to one job per core, so
    # four of those at once want around 19 GiB on a runner that has 16, and the
    # kernel takes the runner agent down with the build. Two fit.
    #
    # Both numbers are printed: the disk one because it was the first suspect
    # and turned out to have 109 GB spare, the memory one because it is the
    # constraint that actually binds.
    - name: Build the tests
      run: |
        df -h /
        free -m || true
        cargo test --features static --no-run --tests -j 2 --message-format=json > artifacts.json
        jq -r 'select(.reason == "compiler-artifact" and .profile.test == true and .executable != null)
               | .executable' artifacts.json > test-binaries.txt
        if [ ! -s test-binaries.txt ]; then
          echo "::error::cargo reported no test binaries, so there is nothing to check"
          exit 1
        fi
        echo "built $(wc -l < test-binaries.txt) test binaries"
      env:
        RUST_BACKTRACE: full

    - name: Check every test binary carries the engine
      run: xargs .github/scripts/check-static-link.sh < test-binaries.txt

    # The files that were just checked, run directly. `cargo test` would be
    # equivalent for as long as nothing relinks in between; running the list
    # removes the "for as long as".
    #
    # The list is read on fd 3 and each binary gets /dev/null for stdin, and both
    # halves matter. A `while read ... done < file` loop hands the child whatever
    # is left of the file, and chdb reads a non-empty stdin as external query
    # data, so a query carrying inlined data is then rejected with "Processing
    # async inserts with both inlined and external data". That failed exactly the
    # binaries that were not last in the list, which is as confusing as it sounds.
    - name: Run tests
      run: |
        while read -r binary <&3; do
          echo "== $binary"
          "$binary" --test-threads=1 < /dev/null
        done 3< test-binaries.txt
      env:
        RUST_BACKTRACE: full

    # `cargo test` would have run these; running the checked binaries directly
    # does not. They are outside the carried-engine check because rustdoc builds
    # and discards its own binaries, but leaving them out would make this job
    # cover less than the dynamic one. Two seconds, measured.
    - name: Run doc tests
      run: cargo test --features static --doc
      env:
        RUST_BACKTRACE: full