diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f93aa25..555e3ed9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ - **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). - **Behavior change:** Support Arrow TIME results on Thrift and SEA as UTC `time.Time` values on `0001-01-01`, preserving precision and using clock-only nested JSON. TIME metadata now reports `TIME`/`time.Time` with no length, including empty and NULL-only results; previously Thrift reported `STRING`/`string` with unbounded length, and SEA reported an empty name with `*interface{}` (databricks/databricks-sql-go#505). - **Behavior change:** Explicit `WithMaxDownloadThreads` / `maxDownloadThreads` settings tuned for Thrift also control kernel buffering and can change memory use and throughput. The kernel window defaults to 16 when unset; explicit chunk-setting overrides take precedence. +- **Behavior change:** Support Volume PUT/GET/REMOVE through kernel ExecContext with staging roots, including resolved-symlink authorization and context cancellation. QueryContext retains raw instructions (databricks/databricks-sql-go#560). - **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. - Fix CloudFetch reads failing with `row number 0 is not contained in any arrow batch: EOF` when `WithMaxDownloadThreads` / `maxDownloadThreads` is 0 or negative. Such values now log a warning and use the default of 10 (databricks/databricks-sql-go#439). - **Behavior change:** On the Thrift backend, `ExecuteStatement` is now retried (per `WithRetries`) when the connection to the server or proxy can't be opened, for example connection refused or a connect timeout, because the statement was never sent. Failures after the connection exists are still not retried, so a statement never runs twice. With default retry settings, a refused connection now fails after about 15 seconds instead of immediately (databricks/databricks-sql-go#423). diff --git a/KERNEL_REV b/KERNEL_REV index de1b52ca..39d79c6f 100644 --- a/KERNEL_REV +++ b/KERNEL_REV @@ -1 +1 @@ -0b5d0edfed32c0745d5abc2468fc3070e2eb2a17 +23e45bafa9b0d1688fbffa5ecc975e1d91f40f01 diff --git a/connection.go b/connection.go index b6269686..40439341 100644 --- a/connection.go +++ b/connection.go @@ -821,6 +821,12 @@ func (c *conn) execStagingOperation( } if len(driverctx.StagingPathsFromContext(ctx)) != 0 { + if native, ok := op.(backend.StagingCompleter); ok { + if err := native.CompleteStaging(ctx); err != nil { + return dbsqlerrint.NewDriverError(ctx, "error performing staging operation", 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 { diff --git a/connection_test.go b/connection_test.go index 9057e50f..566d0f40 100644 --- a/connection_test.go +++ b/connection_test.go @@ -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" @@ -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) { + completionErr := errors.New("native completion failed") + for _, tc := range []struct { + name string + marked, roots, wantCall, wantError bool + completionErr error + }{ + {name: "missing roots", marked: true, wantError: true}, + {name: "unmarked operation with roots", roots: true}, + {name: "native completion", marked: true, roots: true, wantCall: true}, + {name: "native completion error", marked: true, roots: true, wantCall: true, wantError: true, completionErr: 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) + } + }) + } +} diff --git a/doc.go b/doc.go index d2ae07be..653ec5b4 100644 --- a/doc.go +++ b/doc.go @@ -227,13 +227,13 @@ 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 +Kernel SQL HTTP requests inherit the driver's ClientTimeout (900s by default). If that value is zero, the kernel uses its own 120s default; zero is neither -unlimited nor an immediate timeout. +unlimited nor an immediate timeout. Use a context deadline to bound Volume storage +transfers; ClientTimeout does not apply to storage requests. OAuth U2M is interactive: on a cache miss, connecting launches the system browser and blocks until login completes or the kernel's ~120s callback timeout expires. Because @@ -371,6 +371,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. +The staging context is required for REMOVE as well as PUT and GET. + # Errors There are three error types exposed via dbsql/errors diff --git a/examples/kernel/main.go b/examples/kernel/main.go index 51d99c31..e3f19775 100644 --- a/examples/kernel/main.go +++ b/examples/kernel/main.go @@ -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) - } } diff --git a/internal/backend/backend.go b/internal/backend/backend.go index 795c6be9..c679a866 100644 --- a/internal/backend/backend.go +++ b/internal/backend/backend.go @@ -114,6 +114,12 @@ type ResultFormatReporter interface { ResultFormat() string } +// StagingCompleter is implemented by operations that run the staging (Volume) +// file transfer themselves. +type StagingCompleter interface { + CompleteStaging(context.Context) error +} + // ExecRequest is a backend-neutral statement-execution request. Per-backend wire // options (Arrow flags, CloudFetch, direct results, query tags, timeouts) are // derived from the config and context inside the backend implementation. diff --git a/internal/backend/kernel/backend.go b/internal/backend/kernel/backend.go index d8e20d08..6dbd235d 100644 --- a/internal/backend/kernel/backend.go +++ b/internal/backend/kernel/backend.go @@ -65,14 +65,12 @@ import "C" import ( "context" - "errors" "fmt" "strconv" "strings" "sync/atomic" "time" - dbsqlerr "github.com/databricks/databricks-sql-go/errors" "github.com/databricks/databricks-sql-go/internal/backend" ) @@ -893,8 +891,7 @@ func (k *KernelBackend) markSessionDead() { k.valid = false } // Uses errors.As, not a bare type assertion, so it still fires if a caller wraps // the KernelError before passing it here. func (k *KernelBackend) evictIfSessionFatal(err error) { - var ke *KernelError - if errors.As(err, &ke) && isSessionFatal(ke.Code) { + if isSessionFatal(err) { k.markSessionDead() } } @@ -908,15 +905,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) } diff --git a/internal/backend/kernel/cgo.go b/internal/backend/kernel/cgo.go index a8a79f6d..b0e1eac4 100644 --- a/internal/backend/kernel/cgo.go +++ b/internal/backend/kernel/cgo.go @@ -38,7 +38,9 @@ import "C" import ( "context" "fmt" + "os" "runtime" + "syscall" "unsafe" "github.com/databricks/databricks-sql-go/driverctx" @@ -178,6 +180,11 @@ func lastError(code C.KernelStatusCode) *KernelError { if e.query_id != nil { ke.QueryID = C.GoString(e.query_id) } + ke.ErrorCode = C.GoString(C.kernel_get_last_error_code()) + if code := C.kernel_get_last_error_local_os_error(); code != 0 { + // The C ABI reports a path and errno without a syscall name. + ke.cause = &os.PathError{Op: "file", Path: C.GoString(C.kernel_get_last_error_local_path()), Err: syscall.Errno(code)} + } klog("kernel error: code=%d sqlstate=%q vendor=%d http=%d retryable=%v msg=%q", ke.Code, ke.SQLState, ke.VendorCode, ke.HTTPStatus, ke.Retryable, ke.Message) // Also emit through the driver's logger — no SQL text or PII, just the diff --git a/internal/backend/kernel/errors_classify.go b/internal/backend/kernel/errors_classify.go index 73b7c39c..5c433403 100644 --- a/internal/backend/kernel/errors_classify.go +++ b/internal/backend/kernel/errors_classify.go @@ -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) @@ -129,15 +133,19 @@ func isBadConnection(code int) bool { } } -// isSessionFatal reports whether a status code means the server-side session is no +// isSessionFatal reports whether an error means the server-side session is no // longer usable, so the conn must be evicted from the pool rather than reused for // the next query. Broader than isBadConnection: it also covers Unauthenticated (an // expired/revoked token kills the session) — but unlike isBadConnection it is NOT // used to produce driver.ErrBadConn on the statement path, so eviction happens // without database/sql replaying the statement (see toStatementError + the // KernelBackend.markSessionDead call sites). -func isSessionFatal(code int) bool { - switch code { +func isSessionFatal(err error) bool { + var detail *KernelError + if !errors.As(err, &detail) || detail.ErrorCode == "VOLUME_STORAGE_HTTP_ERROR" || detail.ErrorCode == "VOLUME_STORAGE_NETWORK_ERROR" { + return false + } + switch detail.Code { case statusUnauthenticated, statusUnavailable, statusNetworkError: return true default: diff --git a/internal/backend/kernel/errors_classify_test.go b/internal/backend/kernel/errors_classify_test.go index 32eeec09..ef40c416 100644 --- a/internal/backend/kernel/errors_classify_test.go +++ b/internal/backend/kernel/errors_classify_test.go @@ -39,16 +39,24 @@ func TestIsBadConnection(t *testing.T) { func TestIsSessionFatal(t *testing.T) { fatal := []int{statusUnauthenticated, statusUnavailable, statusNetworkError} for _, code := range fatal { - if !isSessionFatal(code) { + if !isSessionFatal(fmt.Errorf("call: %w", &KernelError{Code: code})) { t.Errorf("code %d should be session-fatal", code) } } notFatal := []int{statusInvalidArgument, statusSqlError, statusTimeout} for _, code := range notFatal { - if isSessionFatal(code) { + if isSessionFatal(&KernelError{Code: code}) { t.Errorf("code %d should not be session-fatal", code) } } + for _, err := range []*KernelError{ + {Code: statusUnauthenticated, ErrorCode: "VOLUME_STORAGE_HTTP_ERROR"}, + {Code: statusNetworkError, ErrorCode: "VOLUME_STORAGE_NETWORK_ERROR"}, + } { + if isSessionFatal(err) { + t.Errorf("storage error %s should not be session-fatal", err.ErrorCode) + } + } } // isUserFault picks the log level for a kernel-call failure: user/query faults diff --git a/internal/backend/kernel/include/databricks_kernel.h b/internal/backend/kernel/include/databricks_kernel.h index 965c09b6..f1d27a86 100644 --- a/internal/backend/kernel/include/databricks_kernel.h +++ b/internal/backend/kernel/include/databricks_kernel.h @@ -54,8 +54,9 @@ * `KernelStatusCode_InvalidStatementHandle`. Don't hold two live * executed handles from one statement. * - **A result stream borrows its executed handle.** Closing the executed - * handle invalidates any stream obtained from it: subsequent stream - * calls return `InvalidStatementHandle` (a defined error, not UB). + * handle invalidates any stream obtained from it: schema access, fetching + * and Volume completion return `InvalidStatementHandle` (a defined error, + * not UB). * - **Close is awaited.** `kernel_session_close` waits for the server-side * delete to complete and flushes close-session telemetry before returning. * If close fails, the kernel still schedules best-effort cleanup when the @@ -190,6 +191,11 @@ 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_path(void); /* ─── Opaque handles ────────────────────────────────────────────────── * @@ -369,10 +375,16 @@ 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 apply to Volume file transfers; see the storage read timeout. * `request_timeout_ms == 0` keeps the kernel default (120s). */ KernelStatusCode kernel_session_config_set_request_timeout(KernelSessionConfig* config, uint64_t request_timeout_ms); +/* Idle limit for Volume file transfers: a transfer fails after this long without + * progress. Also caps connection setup. Zero sets no limit. */ +KernelStatusCode kernel_session_config_set_storage_read_timeout(KernelSessionConfig* config, + uint64_t timeout_ms); + /* Configure the maximum number of idle HTTP connections retained per host. * `max_connections` must be greater than zero. Omitting this setter keeps the * kernel default (100). */ @@ -595,12 +607,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). @@ -966,6 +978,32 @@ KernelStatusCode kernel_executed_async_statement_close( */ KernelStatusCode kernel_result_stream_get_schema(kernel_result_stream_t* stream, struct ArrowSchema* out); +typedef enum KernelVolumeCompletion { + KernelVolumeCompletion_NotVolume = 0, + KernelVolumeCompletion_NeedsInputStream = 1, + KernelVolumeCompletion_Completed = 2 +} KernelVolumeCompletion; + +/* Whether the statement is a Volume PUT, GET or REMOVE. + * out is written only on success. */ +KernelStatusCode kernel_executed_statement_is_volume_operation( + const kernel_executed_statement_t* exec, bool* out); +/* Same flag, read from the stream. Still succeeds after the executed statement + * is closed. + * out is written only on success. */ +KernelStatusCode kernel_result_stream_is_volume_operation( + const kernel_result_stream_t* stream, bool* out); +/* Runs the file transfer for a Volume PUT, GET or REMOVE result. Call before + * fetching; the rows stay readable afterwards. + * allowed_paths_json: JSON array of local directories the transfer may use. + * remove_not_found_is_success: report success when the remote file is missing. + * Returns NeedsInputStream for a stream upload, which this API cannot perform. + * kernel_result_stream_canceller_cancel interrupts it from another thread. + * out_status is written only on success. */ +KernelStatusCode kernel_result_stream_complete_volume_operation( + kernel_result_stream_t* stream, const char* allowed_paths_json, + bool remove_not_found_is_success, KernelVolumeCompletion* out_status); + KernelStatusCode kernel_result_stream_next_batch(kernel_result_stream_t* stream, struct ArrowArray* out_array, struct ArrowSchema* out_schema); diff --git a/internal/backend/kernel/kernel_test.go b/internal/backend/kernel/kernel_test.go index cd379412..0c0dc6eb 100644 --- a/internal/backend/kernel/kernel_test.go +++ b/internal/backend/kernel/kernel_test.go @@ -8,9 +8,11 @@ import ( "database/sql/driver" "encoding/json" "errors" + "io/fs" "os" "strings" "sync" + "syscall" "testing" "time" @@ -531,33 +533,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 @@ -569,7 +544,8 @@ func TestExecutionErrorContract(t *testing.T) { t.Errorf("ExecutionError(nil) = %v, want nil", got) } - cause := &KernelError{Code: statusSqlError, Message: "boom", SQLState: "42000", QueryID: "q-123"} + cause := &KernelError{Code: statusSqlError, Message: "boom", SQLState: "42000", QueryID: "q-123", + cause: &os.PathError{Op: "file", Path: "missing.bin", Err: syscall.ENOENT}} err := o.ExecutionError(context.Background(), cause) if err == nil { t.Fatal("ExecutionError(cause) should not be nil") @@ -595,6 +571,9 @@ func TestExecutionErrorContract(t *testing.T) { if !errors.As(err, &ke) { t.Error("the *KernelError cause should remain reachable via errors.As") } + if !errors.Is(err, fs.ErrNotExist) { + t.Errorf("local file error should match fs.ErrNotExist; got %v", err) + } } // The execute error path must NEVER report retryable, even when the kernel marks diff --git a/internal/backend/kernel/operation.go b/internal/backend/kernel/operation.go index e2f355f0..34b4df32 100644 --- a/internal/backend/kernel/operation.go +++ b/internal/backend/kernel/operation.go @@ -11,10 +11,12 @@ import "C" import ( "context" "database/sql/driver" + "encoding/json" "errors" "fmt" "sync" "time" + "unicode/utf8" "github.com/databricks/databricks-sql-go/driverctx" dbsqlerr "github.com/databricks/databricks-sql-go/errors" @@ -35,8 +37,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 @@ -350,6 +351,7 @@ type kernelOp struct { } var _ backend.Operation = (*kernelOp)(nil) +var _ backend.StagingCompleter = (*kernelOp)(nil) // StatementID returns the server query id — captured at execute time on success, // or from the KernelError on an execute failure (empty only when the server @@ -384,11 +386,75 @@ 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 } +// IsStaging reports whether the server marked the statement as a Volume PUT, GET or REMOVE. +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 +} + +// CompleteStaging runs the Volume file transfer, limited to the staging paths set on ctx. +func (o *kernelOp) CompleteStaging(ctx context.Context) error { + if err := ctx.Err(); err != nil { + return err + } + // These two calls do no network I/O, so their errors never mean the session is dead. + var stream *C.kernel_result_stream_t + if err := call(func() C.KernelStatusCode { + return C.kernel_executed_statement_get_result_stream(o.exec, &stream) + }); err != nil { + return toStatementError(err) + } + defer C.kernel_result_stream_close(stream) + var canceller *C.kernel_result_stream_canceller_t + 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: + } + }() + // Join the watcher before freeing its canceller and result stream. + defer func() { close(done); <-stopped }() + roots := driverctx.StagingPathsFromContext(ctx) + for _, root := range roots { + if !utf8.ValidString(root) { + return errors.New("kernel: staging root must be valid UTF-8") + } + } + encoded, _ := json.Marshal(roots) + paths := newCStr(string(encoded)) + defer paths.free() + var outcome C.KernelVolumeCompletion + err := call(func() C.KernelStatusCode { + // Go Thrift REMOVE treats a missing object as success. + return C.kernel_result_stream_complete_volume_operation(stream, paths.c, true, &outcome) + }) + if err != nil { + 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 != C.KernelVolumeCompletion_Completed { + 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 diff --git a/internal/backend/kernel/staging.go b/internal/backend/kernel/staging.go deleted file mode 100644 index c614169c..00000000 --- a/internal/backend/kernel/staging.go +++ /dev/null @@ -1,67 +0,0 @@ -package kernel - -import "strings" - -// This file is intentionally NOT behind the `cgo && databricks_kernel` build tag. -// Staging detection is pure Go (string inspection of the SQL), so keeping it -// untagged lets its test run under CGO_ENABLED=0. - -// isStagingStatement reports whether sql is a Unity Catalog volume staging -// command (PUT / GET / REMOVE). The Thrift backend learns a statement is staging -// from server result metadata (IsStagingOperation); the kernel C ABI exposes no -// such signal, and the kernel path cannot perform the local file transfer these -// commands require. We therefore detect them from the SQL and reject at execute -// time (see Execute) rather than silently returning success with no file moved — -// which is what returning false from IsStaging would do. Case-insensitive; skips -// leading whitespace AND leading SQL comments (`-- ...` and `/* ... */`), so a -// comment-prefixed staging command is still caught rather than slipping through -// as a silent no-op. Errs toward matching only a clear leading keyword — a false -// negative just yields the kernel's normal "unsupported syntax" server error, -// whereas a false positive would reject a legitimate query. -func isStagingStatement(sql string) bool { - s := stripLeadingSQLComments(sql) - for _, kw := range []string{"PUT", "GET", "REMOVE"} { - if len(s) > len(kw) && - strings.EqualFold(s[:len(kw)], kw) && - isSQLTokenBreak(s[len(kw)]) { - return true - } - } - return false -} - -// stripLeadingSQLComments removes leading whitespace and leading SQL comments -// (both `-- ...` line comments and `/* ... */` block comments), repeatedly, so -// the first real token is exposed. An unterminated block comment consumes the -// rest of the string (yielding ""). Comment bodies are not scanned for nested -// markers — SQL block comments do not nest — and this only touches the LEADING -// run, so a comment later in the statement is untouched. -func stripLeadingSQLComments(sql string) string { - s := strings.TrimSpace(sql) - for { - switch { - case strings.HasPrefix(s, "--"): - if i := strings.IndexByte(s, '\n'); i >= 0 { - s = s[i+1:] - } else { - return "" // line comment to end of input - } - case strings.HasPrefix(s, "/*"): - if i := strings.Index(s[2:], "*/"); i >= 0 { - s = s[2+i+2:] - } else { - return "" // unterminated block comment - } - default: - return s - } - s = strings.TrimSpace(s) - } -} - -// isSQLTokenBreak reports whether b ends a leading keyword — a space or a quote -// (staging commands take a quoted path, e.g. PUT '' INTO ''), so -// "PUT '..." matches but an identifier like "PUTS" or "GETTER" does not. -func isSQLTokenBreak(b byte) bool { - return b == ' ' || b == '\t' || b == '\n' || b == '\r' || b == '\'' || b == '"' -} diff --git a/internal/backend/kernel/staging_test.go b/internal/backend/kernel/staging_test.go deleted file mode 100644 index 91d69794..00000000 --- a/internal/backend/kernel/staging_test.go +++ /dev/null @@ -1,41 +0,0 @@ -package kernel - -import "testing" - -func TestIsStagingStatement(t *testing.T) { - staging := []string{ - "PUT '/tmp/f.csv' INTO '/Volumes/main/s/e/f.csv' OVERWRITE", - "GET '/Volumes/main/s/e/f.csv' TO 'local.csv'", - "REMOVE '/Volumes/main/s/e/f.csv'", - " put '/tmp/f' into '/Volumes/x'", // leading space + lowercase - "Get\t'/Volumes/x' to 'y'", // tab after keyword, mixed case - "/* audit */ PUT '/local' INTO '/Volumes/main/s/v'", // leading block comment - "/* a */ /* b */ PUT '/l' INTO '/Volumes/x'", // multiple block comments - "-- upload the file\nPUT '/l' INTO '/Volumes/x'", // leading line comment, then staging - " /* c */\n -- d\n REMOVE '/Volumes/x'", // mixed comments + whitespace - } - for _, sql := range staging { - if !isStagingStatement(sql) { - t.Errorf("expected staging: %q", sql) - } - } - - notStaging := []string{ - "SELECT 1", - "PUTS ON A SHOW", // PUT is a prefix of an identifier, not a token - "GETTER()", // likewise for GET - "REMOVED_AT FROM t", // likewise for REMOVE - "INSERT INTO t VALUES (1)", // contains INTO but is not staging - "", // empty - "-- PUT '/x' INTO '/y'", // whole line commented out; nothing after - "/* PUT '/x' INTO '/y' */", // whole statement inside a block comment - "SELECT 'PUT ' AS col", // keyword only inside a literal - "/* unterminated PUT '/x'", // unterminated block comment consumes the rest - "/* c */ SELECT 1", // real leading comment, but not a staging command - } - for _, sql := range notStaging { - if isStagingStatement(sql) { - t.Errorf("did not expect staging: %q", sql) - } - } -} diff --git a/staging_kernel_test.go b/staging_kernel_test.go new file mode 100644 index 00000000..372cc51c --- /dev/null +++ b/staging_kernel_test.go @@ -0,0 +1,233 @@ +//go:build cgo && databricks_kernel + +package dbsql + +import ( + "bytes" + "context" + "database/sql" + "database/sql/driver" + "encoding/base64" + "encoding/json" + "io" + "io/fs" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/apache/arrow-go/v18/arrow" + "github.com/apache/arrow-go/v18/arrow/array" + "github.com/apache/arrow-go/v18/arrow/ipc" + "github.com/apache/arrow-go/v18/arrow/memory" + "github.com/databricks/databricks-sql-go/driverctx" + dbsqlerr "github.com/databricks/databricks-sql-go/errors" + "github.com/databricks/databricks-sql-go/internal/backend" + "github.com/databricks/databricks-sql-go/internal/backend/kernel" + "github.com/stretchr/testify/require" +) + +type cancelOnCompletionErrorContext struct { + context.Context + cancel context.CancelFunc + errCalls int +} + +func (c *cancelOnCompletionErrorContext) Err() error { + c.errCalls++ + // CompleteStaging checks Err before completion and again after a native failure. + if c.errCalls == 2 { + c.cancel() + } + return c.Context.Err() +} + +func TestKernelVolumeCompletionControlsSessionValidity(t *testing.T) { + for _, tc := range []struct { + name, operation, local, errorCode, message string + status int + instruction, cancelAfterError, inFlight, success, invalidRoot, missingLocal bool + }{ + {name: "instruction401", instruction: true, errorCode: "SESSION_EXPIRED"}, + {name: "storage401", status: 401, errorCode: "VOLUME_STORAGE_HTTP_ERROR"}, + {name: "storageBody", errorCode: "VOLUME_STORAGE_NETWORK_ERROR"}, + {name: "instruction401Cancelled", instruction: true, cancelAfterError: true, errorCode: "SESSION_EXPIRED"}, + {name: "getSuccess", success: true}, + {name: "removeNotFound", operation: "REMOVE", status: 404, success: true}, + {name: "inFlightCancel", inFlight: true}, + {name: "streamPut", operation: "PUT", local: "__input_stream__", message: "requires a local file instruction"}, + {name: "invalidUTF8Root", invalidRoot: true, message: "valid UTF-8"}, + {name: "putMissingFile", operation: "PUT", missingLocal: true, errorCode: "VOLUME_LOCAL_FILE_ERROR"}, + } { + t.Run(tc.name, func(t *testing.T) { + directory := t.TempDir() + destination := filepath.Join(directory, "download.bin") + var result map[string]any + storageStarted := make(chan struct{}) + server := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + _, _ = io.Copy(io.Discard, r.Body) + w.Header().Set("Content-Type", "application/json") + switch { + case r.Method == "POST" && strings.HasSuffix(r.URL.Path, "/sessions"): + _, _ = io.WriteString(w, `{"session_id":"volume-session"}`) + case r.Method == "POST" && r.URL.Path == "/api/2.0/sql/statements": + _ = json.NewEncoder(w).Encode(result) + case r.URL.Path == "/api/2.0/sql/statements/volume-stmt/result/chunks/1": + w.WriteHeader(401) + _, _ = io.WriteString(w, `{"error_code":"SESSION_EXPIRED","message":"instruction session expired","sql_state":"08003"}`) + case r.URL.Path == "/object": + if tc.inFlight { + close(storageStarted) + <-r.Context().Done() + } else if tc.status != 0 { + w.WriteHeader(tc.status) + } else if tc.success { + _, _ = io.WriteString(w, "downloaded") + } else { + w.Header().Set("Content-Length", "20") + _, _ = io.WriteString(w, "short") + } + default: + _, _ = io.WriteString(w, `{}`) + } + })) + defer server.Close() + names := []string{"operation", "presignedUrl", "headers", "localFile"} + operation, local := tc.operation, destination + if operation == "" { + operation = "GET" + } + if tc.local != "" { + local = tc.local + } + if tc.missingLocal { + local = filepath.Join(directory, "missing.bin") + } + values := []string{operation, server.URL + "/object", "{}", local} + fields, columns := make([]arrow.Field, 4), make([]arrow.Array, 4) + manifestColumns := make([]map[string]any, 4) + for i, name := range names { + fields[i] = arrow.Field{Name: name, Type: arrow.BinaryTypes.String, Nullable: true} + builder := array.NewStringBuilder(memory.DefaultAllocator) + builder.Append(values[i]) + columns[i] = builder.NewStringArray() + builder.Release() + defer columns[i].Release() + manifestColumns[i] = map[string]any{"name": name, "type_name": "STRING", "type_text": "STRING", "position": i} + } + schema := arrow.NewSchema(fields, nil) + record := array.NewRecordBatch(schema, columns, 1) + defer record.Release() + var attachment bytes.Buffer + writer := ipc.NewWriter(&attachment, ipc.WithSchema(schema)) + require.NoError(t, writer.Write(record)) + require.NoError(t, writer.Close()) + chunk := map[string]any{"chunk_index": 0, "row_offset": 0, "row_count": 1, "attachment": base64.StdEncoding.EncodeToString(attachment.Bytes())} + chunks := 1 + if tc.instruction { + chunk["next_chunk_index"], chunks = 1, 2 + } + result = map[string]any{ + "statement_id": "volume-stmt", "status": map[string]any{"state": "CLOSED"}, + "manifest": map[string]any{"format": "ARROW_STREAM", "is_volume_operation": true, "schema": map[string]any{"column_count": 4, "columns": manifestColumns}, "total_row_count": 1, "total_chunk_count": chunks}, + "result": chunk, + } + connector, err := NewConnector(WithServerHostname(server.URL), WithHTTPPath("/sql/1.0/warehouses/test"), + WithAccessToken("test-token"), WithUseKernel(true), WithSkipTLSHostVerify(), WithRetries(-1, time.Millisecond, time.Millisecond)) + require.NoError(t, err) + db := sql.OpenDB(connector) + defer db.Close() + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + connection, err := db.Conn(ctx) + require.NoError(t, err) + defer func() { + cancel() + server.CloseClientConnections() + closed := make(chan struct{}) + go func() { + defer close(closed) + _ = connection.Close() + }() + select { + case <-closed: + case <-time.After(5 * time.Second): + t.Error("connection.Close did not return") + } + }() + var execResult sql.Result + if tc.cancelAfterError { + err = connection.Raw(func(raw any) error { + operation, err := raw.(*conn).backend.Execute(ctx, backend.ExecRequest{Query: "GET instruction"}) + if err != nil { + return err + } + defer operation.Close(ctx) + cancelContext, cancelError := context.WithCancel(ctx) + defer cancelError() + stagingContext := driverctx.NewContextWithStagingInfo(&cancelOnCompletionErrorContext{Context: cancelContext, cancel: cancelError}, []string{directory}) + return operation.(backend.StagingCompleter).CompleteStaging(stagingContext) + }) + require.ErrorIs(t, err, context.Canceled) + } else { + roots := []string{directory} + if tc.invalidRoot { + roots = []string{directory + string([]byte{0xff})} + } + if tc.inFlight { + go func() { <-storageStarted; cancel() }() + } + type executionResult struct { + result sql.Result + err error + } + done := make(chan executionResult, 1) + go func() { + result, err := connection.ExecContext(driverctx.NewContextWithStagingInfo(ctx, roots), "Volume instruction") + done <- executionResult{result, err} + }() + select { + case completed := <-done: + execResult, err = completed.result, completed.err + case <-time.After(10 * time.Second): + cancel() + t.Fatal("ExecContext did not return") + } + } + if tc.success { + require.NoError(t, err) + if tc.operation != "REMOVE" { + n, _ := execResult.RowsAffected() + require.Zero(t, n) + content, readErr := fs.ReadFile(os.DirFS(directory), "download.bin") + require.NoError(t, readErr) + require.Equal(t, "downloaded", string(content)) + } + } else if tc.errorCode == "" { + require.ErrorIs(t, err, dbsqlerr.DriverError) + if tc.message != "" { + require.ErrorContains(t, err, tc.message) + } + if tc.inFlight { + require.ErrorIs(t, err, context.Canceled) + } + } else { + require.Error(t, err) + require.NotErrorIs(t, err, driver.ErrBadConn) + var detail *kernel.KernelError + require.ErrorAs(t, err, &detail) + require.Equal(t, tc.errorCode, detail.ErrorCode) + if tc.missingLocal { + require.ErrorIs(t, err, fs.ErrNotExist) + } + } + require.NoError(t, connection.Raw(func(raw any) error { + require.Equal(t, !tc.instruction, raw.(driver.Validator).IsValid()) + return nil + })) + }) + } +}