Server SDK(Go)
Replace <APPBASE_ENDPOINT_WITH_V1>, <APPBASE_CONSOLE_ORIGIN>, and <APPBASE_CONSOLE_HOST> where used with values for the intended environment before running the examples.
Go backends / controlled admin scripts call the Server SDK with a project API Key (module agentbase-go-sdk, method names PascalCase, service packages lowercase run together). API Key requests skip row-level permission checks (hasRole); store only on controlled servers. For Node / Java / Python, see nodejs.md / java.md / python.md in the same directory.
Artifacts and installation
Requires go 1.22.5+; the SDK has zero third-party dependencies. It is not published to the public Go module proxy: extract from the agentbase-sdks release ZIP, then in your application module point replace at the local directory with a go.mod directive (require version fixed as v0.0.0), or copy the source tree / go mod vendor directly. For the full download, verification, and replace commands, see ../examples/go.md "Obtaining and installing"; the Go surface has been delivered since agentbase-sdks v2.7.0 (2.6.0 had no such language surface).
Initialization
The facade package agentbase-go-sdk/agentbase provides a unified entry point:
import (
"errors"
"net/http"
"agentbase-go-sdk/agentbase"
)
cl := agentbase.NewClient(
agentbase.WithEndpoint("<APPBASE_ENDPOINT_WITH_V1>"), // SIT: https://appbuild-sit.oceanbase.com/v1
agentbase.WithProject("<PROJECT_ID>"),
agentbase.WithKey("<SERVER_API_KEY>"), // Project API Key with minimal scope
)
cl.Client.CheckRedirect = func(_ *http.Request, _ []*http.Request) error {
return errors.New("refuse redirects")
}Alongside With*, options include WithTimeout, WithSelfSigned, WithJWT, WithSession, WithOrganization (the last three are only for controlled flows where the endpoint explicitly requires a user identity).
The Go 2.12 client above rejects automatic redirects after initialization. WithTimeout replaces the HTTP client, so set CheckRedirect after all initialization options. If cl.Client is replaced later, configure and verify the redirect policy again.
Calling conventions
Pass required parameters positionally; for optional parameters use the With* methods attached to the service (naming rule With<方法名><参数名>; the module source is authoritative for the full list); queries use agentbase-go-sdk/query and IDs use agentbase-go-sdk/id:
tables := agentbase.NewTablesDB(cl)
_, err := tables.CreateTable("app-db", "tasks", "Tasks",
tables.WithCreateTableRowSecurity(true),
tables.WithCreateTableEnabled(true),
tables.WithCreateTableColumns([]models.DatabaseColumnDefinition{
{Key: "title", Type: "string", Size: 256, Required: true},
}),
tables.WithCreateTableIndexes([]models.DatabaseIndexDefinition{
{Key: "idx_title", Type: "unique", Attributes: []string{"title"}},
}),
)Custom business fields of list and detail models such as rows/documents do not go into structs; fetch the raw JSON via Decode():
row, err := tables.GetRow("app-db", "tasks", "<rowId>")
payload := map[string]interface{}{}
_ = row.Decode(&payload)Client configuration options, cursor pagination, and file upload in practice
agentbase.NewClient uses the Functional Options pattern to construct the client; all services share that client instance via agentbase.New<Service>(cl):
NewClient option function | HTTP request header / behavior injected | applicable scenarios and security constraints |
|---|---|---|
WithEndpoint(url) | Request base address | Required, e.g. https://appbuild-sit.oceanbase.com/v1 or https://appbuild.oceanbase.com/v1. |
WithProject(projectId) | X-Appwrite-Project | Required, target project ID (e.g. the demo project enterprise-ai-hub-210). |
WithKey(apiKey) | X-Appwrite-Key | The primary server-side authentication method, skips RLS (hasRole), authorized with the minimal scopes. |
WithJWT(jwt) | X-Appwrite-JWT | Calls data-plane APIs on behalf of a specific logged-in user (bound by that user's RLS row-level permissions). |
WithSession(session) | X-Appwrite-Session | Loaded when the server forwards a browser login session Cookie. |
WithOrganization(orgId) | X-Appwrite-Organization | Specifies the organization context for organization-level query and governance APIs (e.g. 69c6d1aa00062e6bb60). |
WithLocale(locale) | X-Appwrite-Locale | Specifies the language for internationalized responses (e.g. zh-CN). |
WithTimeout(duration) | HTTP client timeout | Defaults to 10 seconds; for large file uploads or long-running AI calls, set 30 * time.Second or higher. |
WithSelfSigned(true) | TLS certificate verification toggle | Only for private test instances with self-signed certificates; strictly forbidden to enable in production. |
Complete example of cursor pagination, custom struct decoding, and file upload
The following example shows how, in a Go backend, to iterate the customer_tickets support ticket table in the business database enterprise_biz_db (using query.CursorAfter cursor pagination and row.Decode to decode business fields), and upload a file (file.NewInputFile):
package main
import (
"net/http"
"errors"
"fmt"
"os"
"time"
"agentbase-go-sdk/agentbase"
agentbaseclient "agentbase-go-sdk/client"
"agentbase-go-sdk/file"
"agentbase-go-sdk/id"
"agentbase-go-sdk/query"
)
type TicketPayload struct {
ID string `json:"$id"`
TicketNo string `json:"ticketNo"`
Title string `json:"title"`
Status string `json:"status"`
Priority string `json:"priority"`
}
func main() {
cl := agentbase.NewClient(
agentbase.WithEndpoint(os.Getenv("APPBASE_ENDPOINT")),
agentbase.WithProject(os.Getenv("APPBASE_PROJECT_ID")),
agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
agentbase.WithTimeout(30*time.Second),
)
cl.Client.CheckRedirect = func(_ *http.Request, _ []*http.Request) error {
return errors.New("refuse redirects")
}
tables := agentbase.NewTablesDB(cl)
storage := agentbase.NewStorage(cl)
// 1. Fetch open support tickets with cursor pagination and decode into strongly typed structs
cursor := ""
pageSize := 50
for {
queries := []string{
query.Equal("status", []interface{}{"open", "in_progress"}),
query.OrderAsc("$id"),
query.Limit(pageSize),
}
if cursor != "" {
queries = append(queries, query.CursorAfter(cursor))
}
page, err := tables.ListRows("enterprise_biz_db", "customer_tickets",
tables.WithListRowsQueries(queries),
tables.WithListRowsTotal(false), // Disable count(*) to improve pagination performance on large tables
)
if err != nil {
var aerr *agentbaseclient.AgentbaseError
if errors.As(err, &aerr) {
fmt.Printf("HTTP %d: %s\n", aerr.GetStatusCode(), aerr.GetMessage())
}
return
}
if len(page.Rows) == 0 {
break
}
for _, row := range page.Rows {
var t TicketPayload
if err := row.Decode(&t); err != nil {
fmt.Println("Decode row failed:", err)
return
}
fmt.Printf("Ticket %s [%s]: %s\n", t.TicketNo, t.Priority, t.Title)
}
if len(page.Rows) < pageSize {
break
}
cursor = page.Rows[len(page.Rows)-1].Id
}
// 2. Upload local files to the knowledge base document bucket kb_enterprise_docs
inputFile := file.NewInputFile("/tmp/智能客服SOP标准作业手册.md", "智能客服SOP标准作业手册.md")
uploaded, err := storage.CreateFile("kb_enterprise_docs", id.Unique(), inputFile)
if err != nil {
fmt.Println("Upload failed:", err)
return
}
fmt.Println("Uploaded file ID:", uploaded.Id)
}Using together with the Console SDK (agentbase-console-go-sdk)
The Go deliverable provides both a Server SDK (agentbase-go-sdk) and a Console SDK (agentbase-console-go-sdk). Within the same Go module, you can import both modules via two replace directives of go.mod, and use package aliases (e.g. serverfacade "agentbase-go-sdk/agentbase" and consolefacade "agentbase-console-go-sdk/agentbase") to distinguish project data-plane from management control-plane calls (see ../console-sdk/go.md for details).
Feature surface navigation
The service surface is isomorphic to the Node surface (full facade constructors NewTablesDB, NewStorage, NewUsers, NewMemory, NewKnowledgeBases, NewLlmGateway, NewAiGateway, NewObservability, NewModeration, etc.); for the full mapping see nodejs.md "Feature surface navigation"; feature pages: Databases, Storage, Functions, Sites, Users, Teams, Messaging, memory, knowledge base, LLM Gateway, AI Gateway, Observability, Moderation, Cross-cutting services.
No Sql service (SQL uses the HTTP form or the Console SDK, see ../databases/sql-proxy.md); no Realtime (client-side capability).
Error Handling
Errors are uniformly *client.AgentbaseError (agentbase-go-sdk/client):
import (
"errors"
agentbaseclient "agentbase-go-sdk/client"
)
_, err := tables.GetRow("app-db", "tasks", "missing-row")
var aerr *agentbaseclient.AgentbaseError
if errors.As(err, &aerr) && aerr.GetStatusCode() == 404 {
// not found; GetMessage() / GetResponse() (raw response body) are also available
}Example Guide
Go (Server / Console) complete call syntax: ../examples/go.md