Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

## Unreleased (v2.0.0 prototype)

- Support Volume PUT/GET/REMOVE through kernel ExecContext with staging roots, including resolved-symlink authorization and context cancellation. QueryContext retains raw instructions.
- Fix the module-root package conflict when building, linting, or running Gazelle with the `tools` build tag (databricks/databricks-sql-go#162).
- **Behavior change:** Report declared DECIMAL precision and scale through `sql.ColumnType.DecimalSize()` on Thrift and SEA, including zero-row results. Tools such as ORM migrators can now act on these qualifiers (databricks/databricks-sql-go#500).
- **Breaking change:** Upgrade Apache Arrow Go from v12 to v18.8.0 (`github.com/apache/arrow-go/v18`). The public `rows.ArrowBatchIterator` now uses v18 `arrow.RecordBatch` and `*arrow.Schema` types; callers using Arrow batches must migrate their Arrow imports and dependent code. This requires a major driver release (v2.0.0), including a `/v2` driver module path before publication.
Expand Down
2 changes: 1 addition & 1 deletion KERNEL_REV
Original file line number Diff line number Diff line change
@@ -1 +1 @@
0b5d0edfed32c0745d5abc2468fc3070e2eb2a17
d9fcf834d36dc7f3de1621225db716200151fa0f
36 changes: 20 additions & 16 deletions connection.go
Original file line number Diff line number Diff line change
Expand Up @@ -820,25 +820,29 @@ func (c *conn) execStagingOperation(
return nil
}

if len(driverctx.StagingPathsFromContext(ctx)) != 0 {
// Telemetry callback for staging operation row fetching (chunk timing not tracked for staging ops).
telemetryUpdate := func(chunkCount int, bytesDownloaded int64, chunkIndex int, chunkLatencyMs int64, totalChunksPresent int32) {
if c.telemetry != nil {
c.telemetry.AddTag(ctx, telemetry.TagChunkCount, chunkCount)
c.telemetry.AddTag(ctx, telemetry.TagBytesDownloaded, bytesDownloaded)
}
if len(driverctx.StagingPathsFromContext(ctx)) == 0 {
return dbsqlerrint.NewDriverError(ctx, "staging ctx must be provided.", nil)
}
if native, ok := op.(interface{ CompleteStaging(context.Context) error }); ok {
if err := native.CompleteStaging(ctx); err != nil {
return dbsqlerrint.NewDriverError(ctx, "error performing staging operation", err)
}
row, err = op.Results(ctx, &rows.TelemetryCallbacks{
OnChunkFetched: telemetryUpdate,
})
if err != nil {
return dbsqlerrint.NewDriverError(ctx, "error reading row.", err)
return nil
}
// Telemetry callback for staging operation row fetching (chunk timing not tracked for staging ops).
telemetryUpdate := func(chunkCount int, bytesDownloaded int64, chunkIndex int, chunkLatencyMs int64, totalChunksPresent int32) {
if c.telemetry != nil {
c.telemetry.AddTag(ctx, telemetry.TagChunkCount, chunkCount)
c.telemetry.AddTag(ctx, telemetry.TagBytesDownloaded, bytesDownloaded)
}
defer row.Close() //nolint:errcheck

} else {
return dbsqlerrint.NewDriverError(ctx, "staging ctx must be provided.", nil)
}
row, err = op.Results(ctx, &rows.TelemetryCallbacks{
OnChunkFetched: telemetryUpdate,
})
if err != nil {
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
return dbsqlerrint.NewDriverError(ctx, "error reading row.", err)
}
defer row.Close() //nolint:errcheck

var sqlRow []driver.Value
colNames := row.Columns()
Expand Down
42 changes: 42 additions & 0 deletions connection_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,9 @@ import (
"github.com/apache/thrift/lib/go/thrift"
"github.com/pkg/errors"

"github.com/databricks/databricks-sql-go/driverctx"
dbsqlerr "github.com/databricks/databricks-sql-go/errors"
"github.com/databricks/databricks-sql-go/internal/backend"
thriftbackend "github.com/databricks/databricks-sql-go/internal/backend/thrift"
"github.com/databricks/databricks-sql-go/internal/cli_service"
"github.com/databricks/databricks-sql-go/internal/client"
Expand Down Expand Up @@ -1074,3 +1076,43 @@ func TestConn_handleStagingRetry(t *testing.T) {
assert.Less(t, elapsed, 2*time.Second, "context cancel should abort PUT retry backoff promptly")
})
}

type nativeStagingStub struct {
backend.Operation
marked bool
completed bool
err error
}

func (o *nativeStagingStub) StatementID() string { return "volume-test" }
func (o *nativeStagingStub) IsStaging(context.Context) (bool, error) { return o.marked, nil }
func (o *nativeStagingStub) CompleteStaging(context.Context) error { o.completed = true; return o.err }

func TestConnNativeStagingDispatch(t *testing.T) {
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
completionErr := errors.New("native completion failed")
for _, tc := range []struct {
name string
marked, roots, wantCall, wantError bool
completionErr error
}{
{"ordinary query", false, true, false, false, nil},
{"missing roots", true, false, false, true, nil},
{"native completion", true, true, true, false, nil},
{"native completion error", true, true, true, true, completionErr},
} {
t.Run(tc.name, func(t *testing.T) {
ctx := context.Background()
if tc.roots {
ctx = driverctx.NewContextWithStagingInfo(ctx, []string{t.TempDir()})
}
op := &nativeStagingStub{marked: tc.marked, err: tc.completionErr}
err := (&conn{}).execStagingOperation(op, ctx)
assert.Equal(t, tc.wantError, err != nil)
assert.Equal(t, tc.wantCall, op.completed)
if tc.completionErr != nil {
assert.ErrorIs(t, err, dbsqlerr.DriverError)
assert.ErrorIs(t, err, tc.completionErr)
}
})
}
}
10 changes: 8 additions & 2 deletions doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -227,8 +227,7 @@ RetryWaitMin / RetryWaitMax / RetryMax, including the disable form, forwarded to
kernel's HTTP retry config); and the TLS, proxy, and session-conf (query tags,
statement timeout, time zone) options. Federated token providers use one token snapshot
during setup. Nothing is silently ignored: WithTimeout and token-provider / external /
static authenticators are rejected at connect; staging (PUT/GET/REMOVE on a
Unity Catalog volume) is rejected at execute. WithMaxRows is accepted but inert (the
static authenticators are rejected at connect. WithMaxRows is accepted but inert (the
kernel manages fetching below the C ABI).

Kernel HTTP requests inherit the driver's ClientTimeout (900s by default). If
Expand Down Expand Up @@ -368,6 +367,13 @@ After doing so, you can execute staging operations using this context using the

_, err1 := db.ExecContext(ctx, `PUT 'staging/file.csv' INTO '/Volumes/main/staging_test/e2etests/file.csv' OVERWRITE`)

With the kernel backend, ExecContext completes the transfer and reports zero
rows affected. QueryContext returns raw instruction rows without file effects.
Both the requested local path and its resolved symlink target must remain
within the configured staging roots. Symlinks within those roots are permitted;
escapes are rejected, which is stricter than Thrift's requested-path check.
The staging context is required for REMOVE as well as PUT and GET.

# Errors

There are three error types exposed via dbsql/errors
Expand Down
10 changes: 0 additions & 10 deletions examples/kernel/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -87,14 +87,4 @@ func main() {
log.Fatalf("query: %v", err)
}
fmt.Printf("server version: %s\n", version)

// Options the kernel can't honor are rejected with an error wrapping
// ErrNotSupportedByKernel, never silently ignored. Staging (PUT/GET/REMOVE on a
// Unity Catalog volume) is one such feature, rejected at execute.
_, err = db.ExecContext(ctx, "PUT '/tmp/local.csv' INTO '/Volumes/main/default/vol/f.csv' OVERWRITE")
if errors.Is(err, dbsqlerr.ErrNotSupportedByKernel) {
fmt.Println("staging is not supported on the kernel backend (use Thrift for staging)")
} else if err != nil {
fmt.Printf("staging: %v\n", err)
}
}
11 changes: 0 additions & 11 deletions internal/backend/kernel/backend.go
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,6 @@ import (
"sync/atomic"
"time"

dbsqlerr "github.com/databricks/databricks-sql-go/errors"
"github.com/databricks/databricks-sql-go/internal/backend"
)

Expand Down Expand Up @@ -908,15 +907,5 @@ func (k *KernelBackend) SessionID() string { return k.sessionID }
// parameters (req.Params) are bound onto the statement in execute (see
// bindParams).
func (k *KernelBackend) Execute(ctx context.Context, req backend.ExecRequest) (backend.Operation, error) {
// Staging (Unity Catalog volume PUT/GET/REMOVE) needs a local file transfer the
// kernel path can't perform, and the kernel C ABI surfaces no IsStagingOperation
// signal to drive conn.execStagingOperation. Reject it here rather than let
// IsStaging return false and report success with no file moved (silent data loss).
// (Bound parameters, by contrast, ARE now supported — bound in execute via the
// kernel's raw-param C ABI.)
if isStagingStatement(req.Query) {
return &kernelOp{}, fmt.Errorf("databricks: staging operations (PUT/GET/REMOVE on a volume) are %w; "+
"use the default (Thrift) backend", dbsqlerr.ErrNotSupportedByKernel)
}
return k.execute(ctx, req)
}
6 changes: 6 additions & 0 deletions internal/backend/kernel/cgo.go
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,9 @@ import "C"
import (
"context"
"fmt"
"os"
"runtime"
"syscall"
"unsafe"

"github.com/databricks/databricks-sql-go/driverctx"
Expand Down Expand Up @@ -171,6 +173,10 @@ func lastError(code C.KernelStatusCode) *KernelError {
VendorCode: int32(e.vendor_code),
HTTPStatus: uint16(e.http_status),
Retryable: bool(e.retryable),
ErrorCode: C.GoString(C.kernel_get_last_error_code()),
}
if code := C.kernel_get_last_error_local_os_error(); code != 0 {
ke.cause = &os.PathError{Op: "file", Path: C.GoString(C.kernel_get_last_error_local_path()), Err: syscall.Errno(code)}
}
if e.sql_state != nil {
ke.SQLState = C.GoString(e.sql_state)
Expand Down
4 changes: 4 additions & 0 deletions internal/backend/kernel/errors_classify.go
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,12 @@ type KernelError struct {
HTTPStatus uint16
Retryable bool
QueryID string
ErrorCode string
cause error
}

func (e *KernelError) Unwrap() error { return e.cause }

func (e *KernelError) Error() string {
// Append the server query id when present — it is the one correlation handle
// to server-side query history, and on the execute-error path (no exec handle)
Expand Down
22 changes: 20 additions & 2 deletions internal/backend/kernel/include/databricks_kernel.h
Original file line number Diff line number Diff line change
Expand Up @@ -190,6 +190,12 @@ typedef struct KernelError {
* last kernel call cleared the buffer.
*/
bool kernel_get_last_error(KernelError* out);
/* These accessors preserve the last error. Strings are borrowed until the next
* error-clearing kernel call; absent strings are NULL, absent OS code is zero. */
int32_t kernel_get_last_error_local_os_error(void);
const char* kernel_get_last_error_code(void);
const char* kernel_get_last_error_local_kind(void);
const char* kernel_get_last_error_local_path(void);

/* ─── Opaque handles ──────────────────────────────────────────────────
*
Expand Down Expand Up @@ -369,6 +375,7 @@ KernelStatusCode kernel_session_config_set_sea_response_compression_enabled(
/* Configure the total timeout for one HTTP request, from connection start
* through response-body completion. A separate 30s connection timeout also
* applies, so connection establishment is bounded by the shorter limit.
* Does not bound Volume storage requests or configure their inactivity limit.
* `request_timeout_ms == 0` keeps the kernel default (120s). */
KernelStatusCode kernel_session_config_set_request_timeout(KernelSessionConfig* config,
uint64_t request_timeout_ms);
Expand Down Expand Up @@ -595,12 +602,12 @@ KernelStatusCode kernel_session_config_set_u2m_token_cache_config(KernelSessionC
*
* Recognised keys (case-insensitive):
* - "cloudfetch_enabled" = "true"|"false" — false serves every result
* inline (SEA disposition = INLINE), mirroring JDBC EnableQueryResultDownload=0.
* through paged inline delivery without cloud-storage downloads.
* - "cloudfetch_link_prefetch_window" = positive integer.
* - "cloudfetch_max_chunks_in_memory" = positive integer (bounds peak RSS;
* values above the kernel ceiling of 256 are clamped with a warning).
* - "inline_max_chunks_in_memory" = positive integer (inline-Arrow prefetch
* window, used when cloudfetch_enabled = false).
* window for paged inline results).
* - "complex_types_as_json" = "true"|"false" — render ARRAY / MAP / STRUCT /
* VARIANT / GEOMETRY / GEOGRAPHY as JSON text (PySQL
* _use_arrow_native_complex_types=False, JDBC complexDatatypeSupport=false).
Expand Down Expand Up @@ -966,6 +973,17 @@ KernelStatusCode kernel_executed_async_statement_close(
*/
KernelStatusCode kernel_result_stream_get_schema(kernel_result_stream_t* stream,
struct ArrowSchema* out);
/* Volume completion preserves raw rows. Roots are a JSON array of strings;
* out_status is 0=ordinary result, 1=input bytes required, 2=completed.
* The detached result-stream canceller can interrupt completion. */
KernelStatusCode kernel_executed_statement_is_volume_operation(
const kernel_executed_statement_t* exec, bool* out);
KernelStatusCode kernel_result_stream_is_volume_operation(
const kernel_result_stream_t* stream, bool* out);
KernelStatusCode kernel_result_stream_complete_volume_operation(
kernel_result_stream_t* stream, const char* allowed_paths_json,
bool remove_not_found_is_success, int32_t* out_status);

KernelStatusCode kernel_result_stream_next_batch(kernel_result_stream_t* stream,
struct ArrowArray* out_array,
struct ArrowSchema* out_schema);
Expand Down
27 changes: 0 additions & 27 deletions internal/backend/kernel/kernel_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -531,33 +531,6 @@ func TestExecuteHandleLessOpContract(t *testing.T) {
}
}

// TestExecuteRejectsStaging drives Execute with a staging statement (not just the
// isStagingStatement detector in isolation) to pin the detector→Execute wiring: a
// refactor that dropped or reordered the check would silently reopen the
// silent-no-op data-loss path. Mirrors TestExecuteRejectsParams.
func TestExecuteRejectsStaging(t *testing.T) {
k := &KernelBackend{}
op, err := k.Execute(context.Background(), backend.ExecRequest{
Query: "PUT '/tmp/f' INTO '/Volumes/main/s/e/f.csv'",
})
if err == nil {
t.Fatal("expected an error for a staging statement, got nil")
}
if !errors.Is(err, dbsqlerr.ErrNotSupportedByKernel) {
t.Errorf("staging rejection should wrap ErrNotSupportedByKernel, got %v", err)
}
if op == nil {
t.Fatal("Execute must return a non-nil Operation per the Backend contract")
}
closed, closeErr := op.Close(context.Background())
if closeErr != nil {
t.Errorf("Close error = %v, want nil", closeErr)
}
if closed {
t.Error("Close on a handle-less op must report closed=false (no CLOSE_STATEMENT)")
}
}

// ExecutionError must satisfy the same public contract as the Thrift path so the
// errors.Is → errors.As → SqlState()/QueryId() recipe documented in doc.go works
// on the kernel backend too (it previously returned a bare *KernelError that
Expand Down
73 changes: 66 additions & 7 deletions internal/backend/kernel/operation.go
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import "C"
import (
"context"
"database/sql/driver"
"encoding/json"
"errors"
"fmt"
"sync"
Expand All @@ -35,8 +36,7 @@ import (
// client-timeout path, let an in-flight cancel finish in the background so
// it cannot extend the client deadline
//
// Binds any query parameters (bindParams) before executing; staging statements
// are rejected up front by Execute, so none reach here.
// Binds any query parameters (bindParams) before executing.
func (k *KernelBackend) execute(ctx context.Context, req backend.ExecRequest) (backend.Operation, error) {
// Log the SQL length, not the text: query bodies can carry PII/secrets in
// WHERE/INSERT/SET, and this goes to stderr. Matches the driver's own
Expand Down Expand Up @@ -384,11 +384,70 @@ func (o *kernelOp) Results(ctx context.Context, callbacks *dbsqlrows.TelemetryCa
return newKernelRows(ctx, o, stream, callbacks)
}

// IsStaging reports whether this is a staging (PUT/GET/REMOVE) operation. Always
// false on the kernel path: staging statements are rejected up front in
// Execute (isStagingStatement), so no kernelOp is ever produced for one — there
// is nothing for conn.execStagingOperation to act on here.
func (o *kernelOp) IsStaging(ctx context.Context) (bool, error) { return false, nil }
func (o *kernelOp) IsStaging(ctx context.Context) (bool, error) {
if o.exec == nil {
return false, nil
}
var marked C.bool
err := call(func() C.KernelStatusCode {
return C.kernel_executed_statement_is_volume_operation(o.exec, &marked)
})
return bool(marked), err
}

func (o *kernelOp) CompleteStaging(ctx context.Context) error {
if err := ctx.Err(); err != nil {
return err
}
var stream *C.kernel_result_stream_t
if err := call(func() C.KernelStatusCode {
return C.kernel_executed_statement_get_result_stream(o.exec, &stream)
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
}); err != nil {
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
return toStatementError(err)
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
}
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
Comment thread
peco-review-bot[bot] marked this conversation as resolved.
Resolved
defer C.kernel_result_stream_close(stream)
var canceller *C.kernel_result_stream_canceller_t

ghost Nov 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Low — CompleteStaging converts kernel failures with toStatementError but never calls o.backend.evictIfSessionFatal(err). That applies to get_result_stream, canceller_new and complete_volume_operation. Every other kernel path that runs after execute does call it, including Results on the same get_result_stream call and every failure branch in execute. A completion that runs long enough for the token to expire, or for the session to be dropped, will return the error but leave the conn marked valid in the pool. The next statement on that conn then fails as well. Call o.backend.evictIfSessionFatal(err) on these failure branches, the same way Results does.

if err := call(func() C.KernelStatusCode {
return C.kernel_result_stream_canceller_new(stream, &canceller)
}); err != nil {
return toStatementError(err)
}
defer C.kernel_result_stream_canceller_free(canceller)
done, stopped := make(chan struct{}), make(chan struct{})
go func() {
defer close(stopped)
select {
case <-ctx.Done():
C.kernel_result_stream_canceller_cancel(canceller)
case <-done:
}
}()

ghost Nov 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Low — CompleteStaging returns toStatementError(err) for failures from get_result_stream, canceller_new, and complete_volume_operation, but it never calls o.backend.evictIfSessionFatal(err). Both Results (L373-382) and execute make that call on the same kinds of kernel errors. Suppose the token expires or the session is dropped while a Volume transfer completes. The error still reaches the caller, but the conn stays marked valid, so the pool keeps handing out a dead connection. The non-staging read path doesn't have this problem. IsStaging's error path has the same gap. Calling o.backend.evictIfSessionFatal(err) before returning in these branches would match Results.

ghost Nov 14, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked the reachable error sources before adding eviction. kernel_executed_statement_get_result_stream only validates/takes the existing synchronous stream (src/c_abi/statement.rs:733–772); marker and detached-canceller creation are local ABI operations. They cannot observe an expired token or dropped remote session.

Completion can encounter both result transport and presigned-storage failures. Their shared kernel error codes do not establish that the SQL session is dead; applying evictIfSessionFatal indiscriminately could discard a healthy SQL connection on a storage authentication/permission failure. I have not found a demonstrated session-origin failure requiring a change here. No message-prefix classifier or new error-origin framework was added for this hypothetical case.

The native source pin is updated to 22f96fac for the required shared retries. Native-enabled package tests and the final named two-backend Volume workflow pass with exact bytes/deletion proof. A concrete session-origin reproduction would be useful evidence to reassess selective eviction.

ghost Nov 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right about get_result_stream and the canceller: they're local ABI operations, so they can't report a dead session, and that part of my finding was wrong. The complete_volume_operation branch still looks inconsistent to me, though. isSessionFatal only matches Unauthenticated, Unavailable and NetworkError. Results/rows.go already call evictIfSessionFatal on those codes even when the error comes from CloudFetch downloads to presigned storage, which carry the same "storage, not session" ambiguity you describe. So the trade-off you're avoiding here is one the read path already makes. Accepting it in one place and not the other is reasonable, but it's a call for a maintainer. The worst case is a dead conn going back to the pool after a Volume completion fails with an auth or transport error. That's low severity, so I'll leave the thread open for a human to decide instead of pushing further.

defer func() { close(done); <-stopped }()
encoded, err := json.Marshal(driverctx.StagingPathsFromContext(ctx))
if err != nil {
return err
}
paths := newCStr(string(encoded))
defer paths.free()
var outcome C.int32_t
err = call(func() C.KernelStatusCode {
return C.kernel_result_stream_complete_volume_operation(stream, paths.c, true, &outcome)
})
if err != nil {
var ke *KernelError
if !errors.As(err, &ke) || (ke.ErrorCode != "VOLUME_STORAGE_HTTP_ERROR" && ke.ErrorCode != "VOLUME_STORAGE_NETWORK_ERROR") {
o.backend.evictIfSessionFatal(err)
}
if ctx.Err() != nil {
return fmt.Errorf("kernel: volume transfer cancelled: %w (kernel error: %w)", ctx.Err(), toStatementError(err))
}
return toStatementError(err)
}
if outcome != 2 {
return errors.New("kernel: volume operation requires a local file instruction")
}
return nil
}

// Close best-effort closes the executed statement and its statement handle. It is
// idempotent (a second call, or a call after Rows.Close already tore the
Expand Down
Loading