databricks-isv-go-sdk

<!-- skill-version: 1.0.0 --> # Databricks SDK for Go (ISV) Use this skill when implementing or testing **Databricks SDK for Go** (`databricks-sdk-go`) integrations for PWAF-compliant workspace management, Unity Catalog, Jobs, and REST-style API access. ## PWAF Documentation Links | Resource | URL | |----------|-----| | **PWAF Home** | https://databrickslabs.github.io/partner-architecture/ | | **Authentication Best Practices** | https://databrickslabs.github.io/partner-architecture/isv-partners/lakehouse-patterns/access-auth/ | | **OAuth M2M Guide** | https://databrickslabs.github.io/partner-architecture/isv-partners/lakehouse-patterns/access-auth/oauth-m2m | | **OAuth U2M Guide** | https://databrickslabs.github.io/partner-architecture/isv-partners/lakehouse-patterns/access-auth/oauth-u2m | | **User-Agent Telemetry** | https://databrickslabs.github.io/partner-architecture/isv-partners/telemetry-attribution/sdks#go-sdk | | **Go SDK Docs** | https://docs.databricks.com/aws/en/dev-tools/sdk-go | | **Go SDK GitHub** | https://github.com/databricks/databricks-sdk-go | ## Requirements - **SDK:** `github.com/databricks/databricks-sdk-go` v0.107.0+ - **Go:** 1.21+ - **Install:** `go get github.com/databricks/databricks-sdk-go@latest` ## Authentication Decision Guide ``` Which authentication method to use? Production / automated workloads? → OAuth M2M (client credentials) ✅ RECOMMENDED User-interactive flows? → U2M Custom OAuth App (PKCE) ✅ SUPPORTED Already have an OAuth access token? → U2M Token-Env ✅ SUPPORTED Local development/testing only? → PAT (Personal Access Token) ⚠️ LIMITED ``` ## Authentication Comparison | Method | PWAF Status | Auto Token Refresh | Browser Required | Use Case | |--------|-------------|-------------------|------------------|----------| | PAT | ⚠️ Limited | No | No | Testing only | | OAuth M2M | ✅ Recommended | Yes (SDK handles) | No | Production/automated | | U2M Custom OAuth App | ✅ Supported | No | Yes | User-interactive | | U2M Token-Env | ✅ Supported | No | No | Headless/CI | --- ## User-Agent (Required per PWAF) Call once before creating `WorkspaceClient`: ```go import "github.com/databricks/databricks-sdk-go/useragent" useragent.WithPartner("YourCompany") useragent.WithProduct("YourCompany_YourProduct", "1.0.0") ``` --- ## Environment Variables Reference | Variable | Required For | Description | |----------|-------------|-------------| | `DATABRICKS_HOST` | All | Workspace URL (e.g., `https://myworkspace.cloud.databricks.com`) | | `DATABRICKS_TOKEN` | PAT | Personal access token | | `DATABRICKS_CLIENT_ID` | OAuth M2M | Service principal UUID | | `DATABRICKS_CLIENT_SECRET` | OAuth M2M | Service principal OAuth secret | | `DATABRICKS_U2M_CLIENT_ID` | U2M Custom OAuth | Custom OAuth app client ID from App connections | | `DATABRICKS_U2M_CLIENT_SECRET` | U2M Custom OAuth (optional) | Custom OAuth app client secret (Go SDK doesn't require this for public apps) | | `DATABRICKS_REDIRECT_URI` | U2M Custom OAuth (optional) | Custom redirect URI (default: `http://localhost:8040/callback`) | | `DATABRICKS_ACCESS_TOKEN` | U2M Token-Env | Pre-obtained OAuth access token | | `APP_AUTH_TYPE` | Multi-auth | App-level auth selector: `pat`, `oauth_m2m`, `u2m_custom_oauth_app`, `u2m_token_env` | **Important:** - Use `APP_AUTH_TYPE` (not `DATABRICKS_AUTH_TYPE`) because the SDK reads `DATABRICKS_AUTH_TYPE` internally. - Do not mix M2M and U2M environment variables. Use `env -i` for clean test environments. --- ## Complete Examples ### PAT Authentication (Testing Only) ```go package main import ( "context" "fmt" "os" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/service/catalog" "github.com/databricks/databricks-sdk-go/useragent" ) func main() { useragent.WithPartner("YourCompany") useragent.WithProduct("YourCompany_YourProduct", "1.0.0") w, err := databricks.NewWorkspaceClient(&databricks.Config{ Host: os.Getenv("DATABRICKS_HOST"), Token: os.Getenv("DATABRICKS_TOKEN"), }) if err != nil { panic(err) } ctx := context.Background() table, err := w.Tables.Get(ctx, catalog.GetTableRequest{ FullName: "samples.nyctaxi.trips", }) if err != nil { panic(err) } fmt.Printf("Table: %s (%d columns)\n", table.Name, len(table.Columns)) } ``` **Env vars:** `DATABRICKS_HOST`, `DATABRICKS_TOKEN` --- ### OAuth M2M Authentication (Production Recommended) ```go package main import ( "context" "fmt" "os" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/service/catalog" "github.com/databricks/databricks-sdk-go/useragent" ) func main() { useragent.WithPartner("YourCompany") useragent.WithProduct("YourCompany_YourProduct", "1.0.0") w, err := databricks.NewWorkspaceClient(&databricks.Config{ Host: os.Getenv("DATABRICKS_HOST"), ClientID: os.Getenv("DATABRICKS_CLIENT_ID"), ClientSecret: os.Getenv("DATABRICKS_CLIENT_SECRET"), }) if err != nil { panic(err) } ctx := context.Background() table, err := w.Tables.Get(ctx, catalog.GetTableRequest{ FullName: "samples.nyctaxi.trips", }) if err != nil { panic(err) } fmt.Printf("OAuth M2M OK: %s (%d columns)\n", table.Name, len(table.Columns)) } ``` **Env vars:** `DATABRICKS_HOST`, `DATABRICKS_CLIENT_ID`, `DATABRICKS_CLIENT_SECRET` **Setup:** Create service principal in Account Console → Settings → Service principals. Generate OAuth secret. --- ### U2M Token-Env Authentication (Headless/CI) ```go package main import ( "context" "fmt" "os" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/service/catalog" "github.com/databricks/databricks-sdk-go/useragent" ) func main() { useragent.WithPartner("YourCompany") useragent.WithProduct("YourCompany_YourProduct", "1.0.0") token := os.Getenv("DATABRICKS_ACCESS_TOKEN") if token == "" { token = os.Getenv("DATABRICKS_TOKEN") } w, err := databricks.NewWorkspaceClient(&databricks.Config{ Host: os.Getenv("DATABRICKS_HOST"), Token: token, }) if err != nil { panic(err) } ctx := context.Background() table, err := w.Tables.Get(ctx, catalog.GetTableRequest{ FullName: "samples.nyctaxi.trips", }) if err != nil { panic(err) } fmt.Printf("U2M Token-Env OK: %s (%d columns)\n", table.Name, len(table.Columns)) } ``` **Env vars:** `DATABRICKS_HOST`, `DATABRICKS_ACCESS_TOKEN` (or `DATABRICKS_TOKEN`) --- ### U2M Custom OAuth App (PKCE) - Interactive For user-interactive flows with a custom OAuth app, implement the OAuth Authorization Code flow with PKCE: ```go package main import ( "context" "crypto/rand" "crypto/sha256" "encoding/base64" "encoding/json" "fmt" "net/http" "net/url" "os" "os/exec" "runtime" "strings" "github.com/databricks/databricks-sdk-go" "github.com/databricks/databricks-sdk-go/service/catalog" "github.com/databricks/databricks-sdk-go/useragent" ) func main() { useragent.WithPartner("YourCompany") useragent.WithProduct("YourCompany_YourProduct", "1.0.0") host := os.Getenv("DATABRICKS_HOST") clientID := os.Getenv("DATABRICKS_U2M_CLIENT_ID") clientSecret := os.Getenv("DATABRICKS_U2M_CLIENT_SECRET") // optional redirectURI := os.Getenv("DATABRICKS_REDIRECT_URI") if redirectURI == "" { redirectURI = "http://localhost:8040/callback" } token, err := runPKCEFlow(host, clientID, clientSecret, redirectURI) if err != nil { panic(err) } w, err := databricks.NewWorkspaceClient(&databricks.Config{ Host: host, Token: token, }) if err != nil { panic(err) } ctx := context.Background() table, err := w.Tables.Get(ctx, catalog.GetTableRequest{ FullName: "samples.nyctaxi.trips", }) if err != nil { panic(err) } fmt.Printf("U2M Custom OAuth OK: %s (%d columns)\n", table.Name, len(table.Columns)) } func runPKCEFlow(host, clientID, clientSecret, redirectURI string) (string, error) { // Generate PKCE code verifier and challenge verifierBytes := make([]byte, 32) rand.Read(verifierBytes) codeVerifier := base64.RawURLEncoding.EncodeToString(verifierBytes) hash := sha256.Sum256([]byte(codeVerifier)) codeChallenge := base64.RawURLEncoding.EncodeToString(hash[:]) // Generate state stateBytes := make([]byte, 32) rand.Read(stateBytes) state := base64.RawURLEncoding.EncodeToString(stateBytes) // Parse redirect URI redirectURL, _ := url.Parse(redirectURI) port := redirectURL.Port() if port == "" { port = "8040" } // Build authorization URL hostNorm := strings.TrimPrefix(strings.TrimPrefix(host, "https://"), "http://") authURL := fmt.Sprintf("https://%s/oidc/v1/authorize?"+ "client_id=%s&redirect_uri=%s&response_type=code&scope=all-apis&"+ "code_challenge=%s&code_challenge_method=S256&state=%s", hostNorm, clientID, url.QueryEscape(redirectURI), codeChallenge, state) // Channel to receive auth code codeChan := make(chan string, 1) errChan := make(chan error, 1) // Start local server server := &http.Server{Addr: ":" + port} http.HandleFunc("/callback", func(w http.ResponseWriter, r *http.Request) { if r.URL.Query().Get("state") != state { errChan <- fmt.Errorf("state mismatch") return } code := r.URL.Query().Get("code") if code == "" { errChan <- fmt.Errorf("no code in callback") return } w.Header().Set("Content-Type", "text/html") w.Write([]byte(`<html><body style="font-family:sans-serif;text-align:center;padding:50px;"> <h1 style="color:green;">✓ Authentication Successful</h1> <p>You can close this tab.</p></body></html>`)) codeChan <- code }) go server.ListenAndServe() defer server.Shutdown(context.Background()) // Open browser