Add River for Rust

.github/dependabot.yml

@@ -5,6 +5,21 @@
 
 version: 2
 updates:
+  - package-ecosystem: "cargo"
+    directory: "/rust"
+    cooldown:
+      default-days: 7
+    groups:
+      rust-dependencies:
+        update-types:
+          - "minor"
+          - "patch"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
   - package-ecosystem: "gomod"
     directories:
       - "**/*"

.github/workflows/ci.yaml

@@ -410,6 +410,23 @@ jobs:
       - name: Run lint
         run: make lint
 
+  conformance_artifacts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.27"
+
+      # Fails when a Go feature, migration, or protocol value changes
+      # without its conformance fixture, Rust mirror, or feature inventory
+      # classification being updated.
+      - name: Verify conformance fixtures, feature inventory, and Rust migrations
+        run: make verify/conformance verify/feature-inventory verify/rust-migrations
+
   migration_and_sqlc_verify:
     runs-on: ubuntu-latest
     timeout-minutes: 2

.github/workflows/release-candidate.yaml

@@ -0,0 +1,65 @@
+name: Release candidate
+
+# Manual gate before releasing the Rust crates: blocking performance gates and
+# a one-hour soak for Go with Rust on every supported PostgreSQL version.
+
+on:
+  workflow_dispatch:
+    inputs:
+      soak-duration:
+        default: 1h
+        description: Soak duration per job
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+env:
+  # Keep the cross-run cache small; Cargo still reuses compiled dependencies.
+  CARGO_INCREMENTAL: "0"
+
+jobs:
+  release-candidate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 240
+    strategy:
+      fail-fast: false
+      matrix:
+        postgres-version: [14, 15, 16, 17, 18]
+    env:
+      RIVER_CONFORMANCE_DATABASE_URL: postgres://postgres:postgres@localhost:5432/river_release_candidate?sslmode=disable
+      RIVER_CONFORMANCE_REQUIRED: "1"
+
+    services:
+      postgres:
+        image: postgres:${{ matrix.postgres-version }}
+        env:
+          POSTGRES_PASSWORD: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.27"
+      - uses: dtolnay/rust-toolchain@stable
+      - name: Create test database
+        run: PGPASSWORD=postgres createdb -h localhost -U postgres river_release_candidate
+      - name: Go and Rust release performance
+        env:
+          RIVER_CONFORMANCE_PERFORMANCE: "1"
+        run: make test/conformance/performance
+      - name: Go and Rust soak
+        env:
+          RIVER_CONFORMANCE_SOAK_DURATION: ${{ inputs.soak-duration }}
+          # Keeps the soak's `go test` backstop inside this job's timeout. A
+          # soak that can't finish within it fails at startup.
+          CONFORMANCE_SOAK_TIMEOUT: 3h
+        run: make test/conformance/soak

.github/workflows/rust-soak.yaml

@@ -0,0 +1,67 @@
+name: Rust scheduled soak
+
+on:
+  schedule:
+    - cron: "17 3 * * 0"
+  workflow_dispatch:
+    inputs:
+      duration:
+        default: 6h
+        description: Mixed Go/Rust soak duration
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+env:
+  # Keep the cross-run cache small; Cargo still reuses compiled dependencies.
+  CARGO_INCREMENTAL: "0"
+
+jobs:
+  soak:
+    runs-on: ubuntu-latest
+    timeout-minutes: 390
+    strategy:
+      fail-fast: false
+      matrix:
+        postgres-version: [14, 15, 16, 17, 18]
+    env:
+      RIVER_CONFORMANCE_DATABASE_URL: postgres://postgres:postgres@localhost:5432/river_rust_soak?sslmode=disable
+      RIVER_CONFORMANCE_REQUIRED: "1"
+      RIVER_CONFORMANCE_SOAK_DURATION: ${{ inputs.duration || '6h' }}
+
+    services:
+      postgres:
+        image: postgres:${{ matrix.postgres-version }}
+        env:
+          POSTGRES_PASSWORD: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.27"
+      - uses: dtolnay/rust-toolchain@stable
+        id: rust
+      - name: Cache Rust dependencies and build artifacts
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            rust/target
+          key: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-${{ hashFiles('rust/**/Cargo.toml', 'rust/Cargo.lock') }}
+          restore-keys: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-
+      - name: Create test database
+        run: PGPASSWORD=postgres createdb -h localhost -U postgres river_rust_soak
+      - name: Mixed soak
+        run: make test/conformance/soak

.github/workflows/rust.yaml

@@ -0,0 +1,191 @@
+name: Rust
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  # Keep the cross-run cache small; Cargo still reuses compiled dependencies.
+  CARGO_INCREMENTAL: "0"
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: dtolnay/rust-toolchain@stable
+        id: rust
+        with:
+          components: clippy,rustfmt
+      - name: Cache Rust dependencies and build artifacts
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            rust/target
+          key: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-${{ hashFiles('rust/**/Cargo.toml', 'rust/Cargo.lock') }}
+          restore-keys: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-deny@0.20.2
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: cargo-semver-checks@0.49.0
+
+      - name: Lint, including PostgreSQL-only and SQLite-only builds
+        run: make lint/rust
+
+      - name: Documentation and examples
+        run: make doc/rust
+
+      - name: Dependency and license policy
+        run: make check/rust/dependencies
+
+      - name: Package archives
+        run: make check/rust/package
+
+      # Compare with the latest published Rust release tag, which the full
+      # checkout above includes. Before the first release there is no
+      # baseline and the step reports that instead of failing.
+      - name: Public API compatibility
+        run: make check/rust/semver
+
+      # docs.rs builds with a nightly toolchain and `--cfg docsrs`, which
+      # enables the crates' `doc_cfg` feature badges. Last, since installing
+      # nightly makes it the default toolchain for later steps.
+      - uses: dtolnay/rust-toolchain@nightly
+      - name: Documentation as docs.rs builds it
+        run: make doc/rust/docsrs
+
+  msrv:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        rust-version: ["1.95", "1.96", "1.97"]
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: dtolnay/rust-toolchain@master
+        id: rust
+        with:
+          toolchain: ${{ matrix.rust-version }}
+      - name: Cache Rust dependencies and build artifacts
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            rust/target
+          key: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-${{ hashFiles('rust/**/Cargo.toml', 'rust/Cargo.lock') }}
+          restore-keys: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-
+      - name: Check every target and feature
+        run: cargo check --manifest-path rust/Cargo.toml --workspace --all-targets --all-features --locked
+      - name: Unit, doc, and SQLite tests
+        run: make test/rust/sqlite
+
+  sqlite-conformance:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    env:
+      RIVER_CONFORMANCE_REQUIRED: "1"
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.27"
+      - uses: dtolnay/rust-toolchain@stable
+        id: rust
+      - name: Cache Rust dependencies and build artifacts
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            rust/target
+          key: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-${{ hashFiles('rust/**/Cargo.toml', 'rust/Cargo.lock') }}
+          restore-keys: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-
+      - name: SQLite storage and runtime conformance
+        run: make test/conformance/sqlite
+
+  postgres-conformance:
+    runs-on: ubuntu-latest
+    # Builds plus the Rust suite (~10m), mixed conformance (~5m), the
+    # ten-minute soak (up to its 20m backstop), and the advisory performance
+    # tier (~10m on PostgreSQL 18) need more than 45 minutes on a slow runner.
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        postgres-version: [14, 15, 16, 17, 18]
+    env:
+      RIVER_CONFORMANCE_DATABASE_URL: postgres://postgres:postgres@localhost:5432/river_rust_test?sslmode=disable
+      RIVER_CONFORMANCE_REQUIRED: "1"
+      RIVER_CONFORMANCE_SOAK_DURATION: 10m
+      # Keeps the soak's `go test` backstop inside this job's timeout.
+      CONFORMANCE_SOAK_TIMEOUT: 20m
+      RIVER_RUST_DATABASE_URL: postgres://postgres:postgres@localhost:5432/river_rust_test?sslmode=disable
+
+    services:
+      postgres:
+        image: postgres:${{ matrix.postgres-version }}
+        env:
+          POSTGRES_PASSWORD: postgres
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 2s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.27"
+      - uses: dtolnay/rust-toolchain@stable
+        id: rust
+      - name: Cache Rust dependencies and build artifacts
+        uses: actions/cache@v5
+        with:
+          path: |
+            ~/.cargo/registry/index
+            ~/.cargo/registry/cache
+            ~/.cargo/git/db
+            rust/target
+          key: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-${{ hashFiles('rust/**/Cargo.toml', 'rust/Cargo.lock') }}
+          restore-keys: rust-v1-${{ runner.os }}-${{ runner.arch }}-${{ github.job }}-${{ steps.rust.outputs.cachekey }}-
+      - name: Create test database
+        run: PGPASSWORD=postgres createdb -h localhost -U postgres river_rust_test
+      - name: Rust unit, SQLite, and PostgreSQL tests
+        run: make test/rust
+      - name: Mixed correctness and chaos
+        run: make test/conformance
+      - name: Insert-only profile
+        run: make test/conformance/insert-only
+      - name: Ten-minute mixed soak
+        run: make test/conformance/soak
+      # Shared runners are too noisy to gate every pull request on timing.
+      # This run reports regressions; the release candidate workflow gates.
+      - name: Release performance (advisory)
+        if: matrix.postgres-version == 18
+        continue-on-error: true
+        env:
+          RIVER_CONFORMANCE_PERFORMANCE: "1"
+        run: make test/conformance/performance

.gitignore

@@ -4,3 +4,4 @@
 /river
 /riverdriver/riverdrivertest/example_libsql_test.libsql
 /sqlite/
+/rust/**/target/