Go SDK 0.7.0 | ScopeDB Docs

Released October 23, 2026.

Go SDK 0.7.0 brings conditional Catalog changes and complete statement snapshots to Go applications, with explicit controls for write timeouts and retries. For a new application, start with the Go SDK guide.

What's new

Read, preview, and replace Catalog definitions with an ETag to protect against concurrent changes.
Inspect query status, progress, results, and errors through one statement snapshot.
Configure write-attempt timeouts and inspect an interrupted write's outcome before deciding whether to replay it.

Upgrade from 0.6

The changes below apply when upgrading from the published goscopedb 0.6.3 release.

Update the dependency

Upgrade to Go 1.26 or later, then update the dependency and commit go.mod and go.sum:

go get github.com/scopedb/goscopedb@v0.7.0

The module and import paths remain github.com/scopedb/goscopedb.

Review write timeouts

Direct AppendNDJSON requests now have a default 30-second timeout, including the response-body read. Catalog mutations and dry runs use the same Config.WriteTimeout setting. Queries and Catalog reads use the caller's context and HTTP-client settings.

Config.WriteTimeout and AppendStreamOptions.AttemptTimeout are *time.Duration values. Add time to your imports when configuring them:

Setting	Default when omitted	Override	Disable the attempt limit
`Config.WriteTimeout`	30 seconds	`new(2 * time.Minute)`	`new(time.Duration)`
`AppendStreamOptions.AttemptTimeout`	Inherit the client's write timeout	`new(2 * time.Minute)`	`new(time.Duration)`

Replace a positive AttemptTimeout: duration with AttemptTimeout: new(duration). An explicit AttemptTimeout: 0 in old source must become an omitted field or nil to preserve the default. Negative durations are invalid.

Disabling the attempt limit does not disable caller deadlines, HTTP-client timeouts, or the stream's five-minute default delivery/retry budget per batch. A timeout after sending can leave a write's outcome unknown. See Set timeouts for diagnostics and reconciliation before replay.

Update statements and Catalog calls

Previous API	Replacement in 0.7
`handle.LastStatus()`, `Progress()`, `ResultSet()`	`handle.Snapshot()` and its `Status`, `Progress`, `ResultSet`, and `Error` fields
`handle.Status(ctx)`	`handle.Refresh(ctx)`, returning a complete `*StatementSnapshot`
`StatementCancelResult`	`*StatementSnapshot` from `Cancel`; `ID` replaces `StatementID`, and `Error` holds the original failure
`status.Finished()`	`status == scopedb.StatementStatusFinished`; `Terminated()` still covers all terminal states
`table.Describe(ctx)`	`table.Catalog().Get(ctx)`, keeping both `Definition` and `ETag`
`table.Drop(ctx)`	`table.Catalog().Delete(ctx, scopedb.CatalogOptions{IfMatch: etag, AllowDestructive: true})`
Append result, error, or last-failure `.AppendState`	`.Status`; the append JSON field is also `status`
Historical `u_int` type spelling	`uint`

Replace ExecTimeout strings such as "30s" with MaxElapsed: 30 * time.Second. MaxEstimated independently limits estimated execution time. Zero omits the setting: the server defaults to one hour for elapsed time and no estimate limit. Elapsed time includes queueing; negative durations are invalid.

Replace StatementErrorCode and its constants with string codes from Error.Code or StatementErrorDetails.Code. Unknown codes remain available. Use ErrStatementCancelled to distinguish server cancellation from a local context.Canceled.

Replace paginated Catalog list, fetch, and iterator calls with client.Catalog().Get(ctx) or a database, schema, table, or view selector followed by Get(ctx). Use Distinct and RetentionDays in the complete table definition. Typed reads reject unknown fields; Raw() preserves them without numeric conversion. Follow Browse the catalog to read, preview, and conditionally apply a definition. Catalog writes are not automatically retried.

Replace IngestStream with Append

Client.IngestStream, IngestStream, IngestStreamOptions, and IngestResult have been removed. Select the destination with client.Table(name), then use Table.AppendStream for Go values or Table.AppendNDJSON for an existing NDJSON payload. The write example shows queue admission, shutdown, and the delivery report.

Append accepts rows matching the destination columns. Move field renaming, type conversion, filtering, and routing into the producer before Send. For a transformation that must run in ScopeQL, append the original event into an object column in a staging table, then run a separate FROM ... SELECT ... INSERT INTO ... statement. These are separate commits; track processed batches before retrying the transformation.

Review these delivery changes:

Keep each batch within 8 MiB of uncompressed NDJSON and 200,000 rows. Reduce an old ingest batch-byte target above 8 MiB.
Flush and Shutdown return an AppendDeliveryReport for activity since the previous report. Read CommittedRows instead of IngestResult.NumRowsInserted, and inspect Outcome when using the continue policy.
Streams send up to four batches concurrently by default. Set MaxConcurrentBatches: 1 for sequential requests; queries still need ORDER BY for ordered results.
Streams retry confirmed temporary rejections by default. RetryUnknown: true opts into replaying transient unknown outcomes and can duplicate rows. MaxRetries: 0 disables SDK retries. Client timeouts and cancellations are never retried.
Direct AppendNDJSON makes one SDK attempt. HTTP redirects follow the configured HTTP client's policy and are separate from SDK retries.

Append requests use /v1/catalog/databases/{db}/schemas/{schema}/tables/{table}/ingest. The commit outcome is status on success and details.status on failure; missing or unreadable outcomes are unknown. The AppendState enum and stream delivery/report types remain available.