Merge remote-tracking branch 'origin/trunk' into phillip/adbc-reauth-on-session-expiry

# Conflicts:
#	adbc.go

Author: lukekim

.github/workflows/go.yml

@@ -16,7 +16,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        go-version: ['1.24', '1.25']
+        go-version: ['1.25', '1.26']
     steps:
       - uses: actions/checkout@v5
 
@@ -31,11 +31,18 @@ jobs:
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v8
         with:
-          version: v2.1
+          version: v2.12
 
       - name: Build
         run: go build -v ./...
 
+      # The Spice runtime cannot be installed or run natively on Windows, so the
+      # Windows job runs the runtime-free unit tests natively and defers the
+      # runtime install + integration tests to WSL (see the WSL steps below).
+      - name: Unit tests (Windows native)
+        if: matrix.os == 'windows-latest'
+        run: go test -v -run 'TestUserAgent|TestPrependedUserAgent|TestInferArrowType|TestAppendValueToBuilder|TestComprehensiveArrowTypes|TestParamType|TestTypedParamInference|TestExtendedArrowTypes' ./...
+
       - name: Install Spice (https://install.spiceai.org) (Linux)
         if: matrix.os == 'ubuntu-latest' || matrix.os == 'macos-latest'
         env:
@@ -45,17 +52,6 @@ jobs:
           echo "$HOME/.spice/bin" >> $GITHUB_PATH
           $HOME/.spice/bin/spice install
 
-      - name: install Spice (Windows)
-        if: matrix.os == 'windows-latest'
-        run: |
-          curl -L "https://install.spiceai.org/Install.ps1" -o Install.ps1 && PowerShell -ExecutionPolicy Bypass -File ./Install.ps1
-
-      - name: add Spice bin to PATH (Windows)
-        if: matrix.os == 'windows-latest'
-        run: |
-          Add-Content $env:GITHUB_PATH (Join-Path $HOME ".spice\bin")
-        shell: pwsh
-
       - name: Init and start spice app (Unix)
         if: matrix.os != 'windows-latest'
         run: |
@@ -74,82 +70,90 @@ jobs:
             sleep 1
           done
 
-      - name: Init and start spice app (Windows)
-        if: matrix.os == 'windows-latest'
-        run: |
-          spice install
-          spice init spice_qs
-          cd spice_qs
-          spice add spiceai/quickstart
-        shell: pwsh
-
       - name: Test
         if: matrix.os != 'windows-latest'
         env:
           SPICE_API_KEY: ${{ secrets.SPICE_CLOUD_API_KEY }}
         run: go test -v ./...
 
-      - name: Start runtime and test (Windows)
+      # Native Windows local runtime is unsupported ("Open WSL and run the Linux
+      # Spice CLI there instead"), so the integration tests run inside WSL against
+      # a Linux Spice runtime.
+      - name: Set up WSL (Windows)
+        if: matrix.os == 'windows-latest'
+        uses: Vampire/setup-wsl@v7
+        with:
+          # Ubuntu 24.04 (glibc 2.39) — the Spice binary requires glibc >= 2.38.
+          distribution: Ubuntu-24.04
+          additional-packages: curl ca-certificates git
+
+      # Forward the workspace path and API key into every wsl-bash step.
+      - name: Configure WSLENV (Windows)
         if: matrix.os == 'windows-latest'
+        shell: bash
+        run: echo "WSLENV=GITHUB_WORKSPACE:SPICE_API_KEY" >> "$GITHUB_ENV"
+
+      - name: Install Spice and run integration tests in WSL (Windows)
+        if: matrix.os == 'windows-latest'
+        shell: wsl-bash {0}
         env:
           SPICE_API_KEY: ${{ secrets.SPICE_CLOUD_API_KEY }}
         run: |
-          $spicedPath = Join-Path $HOME ".spice\bin\spiced"
-          $spicedDir = Join-Path (Get-Location) "spice_qs"
-          $logPath = Join-Path $spicedDir "spice.log"
-          $errPath = Join-Path $spicedDir "spice.err.log"
-          $proc = Start-Process -FilePath $spicedPath -WorkingDirectory $spicedDir -RedirectStandardOutput $logPath -RedirectStandardError $errPath -PassThru
-          Write-Host "Started spiced PID=$($proc.Id)"
-          # Wait for Spice HTTP to be ready
-          Write-Host "Waiting for Spice HTTP to be ready..."
-          for ($i = 1; $i -le 60; $i++) {
-            try {
-              $response = Invoke-WebRequest -Uri "http://127.0.0.1:8090/v1/ready" -UseBasicParsing -ErrorAction Stop
-              if ($response.Content -match "ready") {
-                Write-Host "Spice HTTP is ready!"
-                break
-              }
-            } catch { }
-            Write-Host "Waiting HTTP... ($i/60)"
-            Start-Sleep -Seconds 1
-          }
-          # Wait for Spice Flight (gRPC) to be ready by checking the TCP port
-          Write-Host "Waiting for Spice Flight to be ready..."
-          for ($i = 1; $i -le 60; $i++) {
-            $tcp = New-Object System.Net.Sockets.TcpClient
-            try {
-              $tcp.Connect("127.0.0.1", 50051)
-              if ($tcp.Connected) {
-                Write-Host "Spice Flight is ready!"
-                $tcp.Close()
-                break
-              }
-            } catch { }
-            finally { $tcp.Close() }
-            Write-Host "Waiting Flight... ($i/60)"
-            Start-Sleep -Seconds 1
+          # Retry helper for flaky network installs.
+          retry() {
+            local n
+            for n in 1 2 3; do
+              if "$@"; then return 0; fi
+              echo "::warning::attempt ${n}/3 failed: $*"
+              sleep 5
+            done
+            return 1
           }
-          try {
-            go test -v ./...
-            $testExit = $LASTEXITCODE
-          } finally {
-            Write-Host "Stopping spiced PID=$($proc.Id)"
-            Stop-Process -Id $proc.Id -Force -ErrorAction SilentlyContinue
-          }
-          exit $testExit
-        shell: pwsh
+
+          # Install a current Go toolchain inside the WSL distribution.
+          GO_VER="$(curl -fsSL --retry 3 'https://go.dev/VERSION?m=text' | head -1)"
+          echo "Installing ${GO_VER} in WSL"
+          curl -fsSL --retry 3 "https://go.dev/dl/${GO_VER}.linux-amd64.tar.gz" -o /tmp/go.tgz
+          rm -rf /usr/local/go && tar -C /usr/local -xzf /tmp/go.tgz
+          export PATH="/usr/local/go/bin:${HOME}/.spice/bin:${PATH}"
+          go version
+
+          # Enter the checked-out repo (Windows workspace, mounted under /mnt).
+          cd "$(wslpath -u "${GITHUB_WORKSPACE}")"
+
+          # Install the Spice CLI and runtime (downloads can be flaky, so retry).
+          retry bash -c 'curl -sSL https://install.spiceai.org | /bin/bash'
+          retry spice install
+
+          # Start a quickstart runtime.
+          spice init spice_qs
+          cd spice_qs
+          retry spice add spiceai/quickstart
+          nohup spice run > spice.log 2>&1 &
+          cd ..
+
+          echo "Waiting for Spice to be ready..."
+          for i in $(seq 1 90); do
+            if curl -fs http://localhost:8090/v1/ready >/dev/null 2>&1; then
+              echo "Spice is ready!"
+              break
+            fi
+            echo "Waiting... ($i/90)"
+            sleep 2
+          done
+
+          go test -v ./...
 
       - name: Print Spice logs (Unix)
         if: always() && matrix.os != 'windows-latest'
         run: |
           echo "=== Spice Runtime Logs ==="
           cat spice_qs/spice.log || echo "No log file found"
 
-      - name: Print Spice logs (Windows)
+      - name: Print Spice logs (WSL) (Windows)
         if: always() && matrix.os == 'windows-latest'
+        shell: wsl-bash {0}
         run: |
-          Write-Host "=== Spice Runtime Logs (stdout) ==="
-          Get-Content spice_qs\spice.log -ErrorAction SilentlyContinue
-          Write-Host "=== Spice Runtime Logs (stderr) ==="
-          Get-Content spice_qs\spice.err.log -ErrorAction SilentlyContinue
-        shell: pwsh
+          cd "$(wslpath -u "${GITHUB_WORKSPACE:-}" 2>/dev/null)" 2>/dev/null || true
+          echo "=== Spice Runtime Logs (WSL) ==="
+          cat spice_qs/spice.log 2>/dev/null || echo "No log file found"

README.md

@@ -2,7 +2,7 @@
 
 Golang SDK for Spice.ai
 
-See Go Docs at [pkg.go.dev/github.com/spiceai/gospice/v8](https://pkg.go.dev/github.com/spiceai/gospice/v8).
+See Go Docs at [pkg.go.dev/github.com/spiceai/gospice/v9](https://pkg.go.dev/github.com/spiceai/gospice/v9).
 
 For full documentation visit [docs.spice.ai](https://docs.spice.ai/sdks/go).
 
@@ -11,13 +11,13 @@ For full documentation visit [docs.spice.ai](https://docs.spice.ai/sdks/go).
 1. Get the gospice package.
 
 ```go
-go get github.com/spiceai/gospice/v8@latest
+go get github.com/spiceai/gospice/v9@latest
 ```
 
 1. Import the package.
 
 ```go
-import "github.com/spiceai/gospice/v8"
+import "github.com/spiceai/gospice/v9"
 ```
 
 1. Create a SpiceClient passing in your API key. Get your free API key at [spice.ai](https://spice.ai).
@@ -41,7 +41,7 @@ if err := spice.Init(
 1. Execute a query and get back an Apache Arrow Reader.
 
 ```go
-    reader, err := spice.Query(context.Background(), "SELECT 1")
+    reader, err := spice.Sql(context.Background(), "SELECT 1")
     if err != nil {
         panic(fmt.Errorf("error querying: %w", err))
     }
@@ -60,7 +60,7 @@ if err := spice.Init(
 
 ### Using Parameterized Queries (Recommended)
 
-gospice v8 supports parameterized queries using ADBC (Arrow Database Connectivity), which is the recommended approach for queries with parameters to prevent SQL injection:
+gospice v9 supports parameterized queries using ADBC (Arrow Database Connectivity), which is the recommended approach for queries with parameters to prevent SQL injection:
 
 ```go
 // Query with a single parameter
@@ -110,7 +110,7 @@ defer reader.Release()
 For precise control over Arrow types, use typed parameter constructors:
 
 ```go
-import "github.com/spiceai/gospice/v8"
+import "github.com/spiceai/gospice/v9"
 
 // Explicit type control for complex scenarios
 reader, err := spice.SqlWithParams(
@@ -161,9 +161,54 @@ if err := spice.Init(
 }
 ```
 
+## Async Queries
+
+`Query` and `QueryWithParams` submit SQL for **asynchronous** execution and return an `*AsyncQuery` handle. Async queries run in the background on the Spice runtime and are designed for long-running analytical and batch workloads. They require the runtime to be running in distributed/scheduler mode (`spiced --role scheduler` with `runtime.scheduler.state_location` configured).
+
+```go
+// Submit a query for async execution
+query, err := spice.Query(context.Background(), "SELECT * FROM taxi_trips")
+if err != nil {
+    panic(fmt.Errorf("error submitting query: %w", err))
+}
+fmt.Println("query id:", query.ID())
+
+// Wait for completion and fetch results as an Apache Arrow reader
+reader, err := query.Results(context.Background())
+if err != nil {
+    panic(fmt.Errorf("error fetching results: %w", err))
+}
+defer reader.Release()
+
+for reader.Next() {
+    fmt.Println(reader.RecordBatch())
+}
+```
+
+Parameterized async queries bind positional parameters (`$1`, `$2`, ...):
+
+```go
+query, err := spice.QueryWithParams(
+    context.Background(),
+    "SELECT * FROM taxi_trips WHERE trip_distance > $1 LIMIT $2",
+    5.0,
+    100,
+)
+```
+
+The `*AsyncQuery` handle provides:
+
+- `ID()` - the server-assigned query ID
+- `Status(ctx)` - poll the current status once (`PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`, `CLOSED`)
+- `Wait(ctx)` - block until the query reaches a terminal status
+- `Results(ctx)` - wait for completion and return results as an `array.RecordReader`
+- `Cancel(ctx)` - request cancellation
+
+For synchronous, real-time streaming queries, use `Sql` / `SqlWithParams` instead.
+
 ## Health Checks
 
-gospice v8 provides health check methods to verify Spice instance status before executing queries:
+gospice v9 provides health check methods to verify Spice instance status before executing queries:
 
 ```go
 // Check if Spice instance is healthy (unauthenticated)
@@ -202,32 +247,32 @@ spice.SetMaxRetries(5) // Setting to 0 will disable retries
 Retries are performed for connection and system internal errors. It is the SDK user's responsibility to properly
 handle other errors, for example RESOURCE_EXHAUSTED (HTTP 429).
 
-## Upgrading from v7 to v8
+## Upgrading from v8 to v9
 
-gospice v8 is fully backward compatible with v7. To upgrade:
+gospice v9 is a new major version with breaking changes. To upgrade:
 
 ```bash
-go get github.com/spiceai/gospice/v8@latest
+go get github.com/spiceai/gospice/v9@latest
 go mod tidy
 ```
 
 Update your imports:
 
 ```go
 // Before
-import "github.com/spiceai/gospice/v7"
+import "github.com/spiceai/gospice/v8"
 
 // After
-import "github.com/spiceai/gospice/v8"
+import "github.com/spiceai/gospice/v9"
 ```
 
-**What's new in v8:**
+**Breaking changes in v9:**
 
-- New `Sql()` and `SqlWithParams()` methods for cleaner API (`.Query()` methods still work for backward compatibility)
-- `IsSpiceHealthy()` and `IsSpiceReady()` health check methods
-- Apache Arrow v18 and Go 1.24 support
+- `Query()` and `QueryWithParams()` are now **asynchronous** and return an `*AsyncQuery` handle instead of an `array.RecordReader`. Use the handle's `Wait()` / `Results()` methods (see [Async Queries](#async-queries)), or switch to the synchronous `Sql()` / `SqlWithParams()` methods.
+- Minimum Go version is now **1.25** (was 1.24).
+- Upgraded to Apache Arrow v18.6.0 and ADBC v1.11.0, matching the Spice.ai runtime's DataFusion 54.
 
-See [UPGRADE_V7_TO_V8.md](UPGRADE_V7_TO_V8.md) for detailed migration guide.
+See [UPGRADE_V8_TO_V9.md](UPGRADE_V8_TO_V9.md) for the detailed migration guide.
 
 ## Testing and Benchmarking