Databricks Isv Go SQL Driver

Databricks SQL Driver for Go (ISV)

Use this skill when implementing or testing Databricks SQL Driver for Go (databricks-sql-go) integrations for PWAF-compliant SQL query execution via a Databricks SQL warehouse.

PWAF Documentation Links

Requirements

• Driver: github.com/databricks/databricks-sql-go v1.5.2+
• Go: 1.20+
• SQL Warehouse: Required (DATABRICKS_HTTP_PATH)
• Install: go get github.com/databricks/databricks-sql-go@latest

Authentication Comparison

ISV Note: For user-interactive flows, use U2M Custom OAuth with your registered OAuth app (Account Console → App connections). This provides custom branding, audit trails, and scoped permissions. The driver's built-in U2M browser auth uses a generic databricks-sql-connector app which is not appropriate for ISV applications.

Host Normalization Helper

The driver's WithServerHostname expects a bare hostname (no https://):

import "strings"

func serverHostname(host string) string {
    s := strings.TrimPrefix(host, "https://")
    s = strings.TrimPrefix(s, "http://")
    if idx := strings.Index(s, "/"); idx >= 0 {
        s = s[:idx]
    }
    return s
}

Environment Variables Reference

Important: Do not mix M2M and U2M environment variables. Use env -i for clean test environments.

Complete Examples

PAT Authentication (Testing Only)

package main

import (
    "database/sql"
    "fmt"
    "os"
    "strings"

    dbsql "github.com/databricks/databricks-sql-go"
)

func main() {
    host := os.Getenv("DATABRICKS_HOST")
    httpPath := os.Getenv("DATABRICKS_HTTP_PATH")
    token := os.Getenv("DATABRICKS_TOKEN")

    connector, err := dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAccessToken(token),
        dbsql.WithUserAgentEntry("YourCompany_YourProduct/1.0.0"),
    )
    if err != nil {
        panic(err)
    }

    db := sql.OpenDB(connector)
    defer db.Close()

    rows, err := db.Query("SELECT COUNT(*) FROM samples.nyctaxi.trips")
    if err != nil {
        panic(err)
    }
    defer rows.Close()

    var count int64
    rows.Next()
    rows.Scan(&count)
    fmt.Printf("PAT OK: %d trips\n", count)
}

func serverHostname(host string) string {
    s := strings.TrimPrefix(host, "https://")
    s = strings.TrimPrefix(s, "http://")
    if idx := strings.Index(s, "/"); idx >= 0 {
        s = s[:idx]
    }
    return s
}

Env vars: DATABRICKS_HOST, DATABRICKS_HTTP_PATH, DATABRICKS_TOKEN

OAuth M2M Authentication (Production Recommended)

Uses the driver's built-in M2M authenticator that handles token fetch and refresh:

package main

import (
    "database/sql"
    "fmt"
    "os"
    "strings"

    dbsql "github.com/databricks/databricks-sql-go"
    "github.com/databricks/databricks-sql-go/auth/oauth/m2m"
)

func main() {
    host := os.Getenv("DATABRICKS_HOST")
    httpPath := os.Getenv("DATABRICKS_HTTP_PATH")
    clientID := os.Getenv("DATABRICKS_CLIENT_ID")
    clientSecret := os.Getenv("DATABRICKS_CLIENT_SECRET")

    authenticator := m2m.NewAuthenticator(clientID, clientSecret, serverHostname(host))

    connector, err := dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAuthenticator(authenticator),
        dbsql.WithUserAgentEntry("YourCompany_YourProduct/1.0.0"),
    )
    if err != nil {
        panic(err)
    }

    db := sql.OpenDB(connector)
    defer db.Close()

    rows, err := db.Query("SELECT COUNT(*) FROM samples.nyctaxi.trips")
    if err != nil {
        panic(err)
    }
    defer rows.Close()

    var count int64
    rows.Next()
    rows.Scan(&count)
    fmt.Printf("OAuth M2M OK: %d trips\n", count)
}

func serverHostname(host string) string {
    s := strings.TrimPrefix(host, "https://")
    s = strings.TrimPrefix(s, "http://")
    if idx := strings.Index(s, "/"); idx >= 0 {
        s = s[:idx]
    }
    return s
}

Env vars: DATABRICKS_HOST, DATABRICKS_HTTP_PATH, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET

Setup: Create service principal in Account Console → Settings → Service principals. Generate OAuth secret. Grant CAN_USE on the SQL warehouse.

U2M Browser Authentication (Driver-Native)

Uses the driver's built-in U2M authenticator that opens the user's default browser:

package main

import (
    "database/sql"
    "fmt"
    "os"
    "strings"
    "time"

    dbsql "github.com/databricks/databricks-sql-go"
    "github.com/databricks/databricks-sql-go/auth/oauth/u2m"
)

func main() {
    host := os.Getenv("DATABRICKS_HOST")
    httpPath := os.Getenv("DATABRICKS_HTTP_PATH")

    authenticator, err := u2m.NewAuthenticator(serverHostname(host), 2*time.Minute)
    if err != nil {
        panic(err)
    }

    connector, err := dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAuthenticator(authenticator),
        dbsql.WithUserAgentEntry("YourCompany_YourProduct/1.0.0"),
    )
    if err != nil {
        panic(err)
    }

    db := sql.OpenDB(connector)
    defer db.Close()

    rows, err := db.Query("SELECT COUNT(*) FROM samples.nyctaxi.trips")
    if err != nil {
        panic(err)
    }
    defer rows.Close()

    var count int64
    rows.Next()
    rows.Scan(&count)
    fmt.Printf("U2M Browser OK: %d trips\n", count)
}

func serverHostname(host string) string {
    s := strings.TrimPrefix(host, "https://")
    s = strings.TrimPrefix(s, "http://")
    if idx := strings.Index(s, "/"); idx >= 0 {
        s = s[:idx]
    }
    return s
}

Env vars: DATABRICKS_HOST, DATABRICKS_HTTP_PATH

Notes:

• Uses Databricks' built-in OAuth app (client_id=databricks-sql-connector)
• Do NOT set DATABRICKS_CLIENT_ID or DATABRICKS_TOKEN
• Driver picks an available localhost port at runtime

U2M Token-Env Authentication (Headless/CI)

Pass a pre-obtained OAuth access token:

package main

import (
    "database/sql"
    "fmt"
    "os"
    "strings"

    dbsql "github.com/databricks/databricks-sql-go"
)

func main() {
    host := os.Getenv("DATABRICKS_HOST")
    httpPath := os.Getenv("DATABRICKS_HTTP_PATH")
    
    token := os.Getenv("DATABRICKS_ACCESS_TOKEN")
    if token == "" {
        token = os.Getenv("DATABRICKS_TOKEN")
    }

    connector, err := dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAccessToken(token),
        dbsql.WithUserAgentEntry("YourCompany_YourProduct/1.0.0"),
    )
    if err != nil {
        panic(err)
    }

    db := sql.OpenDB(connector)
    defer db.Close()

    rows, err := db.Query("SELECT COUNT(*) FROM samples.nyctaxi.trips")
    if err != nil {
        panic(err)
    }
    defer rows.Close()

    var count int64
    rows.Next()
    rows.Scan(&count)
    fmt.Printf("U2M Token-Env OK: %d trips\n", count)
}

func serverHostname(host string) string {
    s := strings.TrimPrefix(host, "https://")
    s = strings.TrimPrefix(s, "http://")
    if idx := strings.Index(s, "/"); idx >= 0 {
        s = s[:idx]
    }
    return s
}

Env vars: DATABRICKS_HOST, DATABRICKS_HTTP_PATH, DATABRICKS_ACCESS_TOKEN (or DATABRICKS_TOKEN)

U2M Custom OAuth App (PKCE) - Interactive

For user-interactive flows with a custom OAuth app:

package main

import (
    "context"
    "crypto/rand"
    "crypto/sha256"
    "database/sql"
    "encoding/base64"
    "encoding/json"
    "fmt"
    "net/http"
    "net/url"
    "os"
    "os/exec"
    "runtime"
    "strings"

    dbsql "github.com/databricks/databricks-sql-go"
)

func main() {
    host := os.Getenv("DATABRICKS_HOST")
    httpPath := os.Getenv("DATABRICKS_HTTP_PATH")
    clientID := os.Getenv("DATABRICKS_U2M_CLIENT_ID")
    clientSecret := os.Getenv("DATABRICKS_U2M_CLIENT_SECRET")
    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)
    }

    connector, err := dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAccessToken(token),
        dbsql.WithUserAgentEntry("YourCompany_YourProduct/1.0.0"),
    )
    if err != nil {
        panic(err)
    }

    db := sql.OpenDB(connector)
    defer db.Close()

    rows, err := db.Query("SELECT COUNT(*) FROM samples.nyctaxi.trips")
    if err != nil {
        panic(err)
    }
    defer rows.Close()

    var count int64
    rows.Next()
    rows.Scan(&count)
    fmt.Printf("U2M Custom OAuth OK: %d trips\n", count)
}

func runPKCEFlow(host, clientID, clientSecret, redirectURI string) (string, error) {
    verifierBytes := make([]byte, 32)
    rand.Read(verifierBytes)
    codeVerifier := base64.RawURLEncoding.EncodeToString(verifierBytes)
    
    hash := sha256.Sum256([]byte(codeVerifier))
    codeChallenge := base64.RawURLEncoding.EncodeToString(hash[:])
    
    stateBytes := make([]byte, 32)
    rand.Read(stateBytes)
    state := base64.RawURLEncoding.EncodeToString(stateBytes)

    redirectURL, _ := url.Parse(redirectURI)
    port := redirectURL.Port()
    if port == "" {
        port = "8040"
    }

    hostNorm := serverHostname(host)
    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)

    codeChan := make(chan string, 1)
    errChan := make(chan error, 1)

    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())

    openBrowser(authURL)
    fmt.Println("Waiting for authentication in browser...")

    var code string
    select {
    case code = <-codeChan:
    case err := <-errChan:
        return "", err
    }

    tokenURL := fmt.Sprintf("https://%s/oidc/v1/token", hostNorm)
    data := url.Values{
        "grant_type":    {"authorization_code"},
        "code":          {code},
        "redirect_uri":  {redirectURI},
        "code_verifier": {codeVerifier},
        "client_id":     {clientID},
    }
    if clientSecret != "" {
        data.Set("client_secret", clientSecret)
    }

    resp, err := http.PostForm(tokenURL, data)
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var result struct {
        AccessToken string `json:"access_token"`
        Error       string `json:"error"`
    }
    json.NewDecoder(resp.Body).Decode(&result)
    if result.Error != "" {
        return "", fmt.Errorf("token error: %s", result.Error)
    }
    return result.AccessToken, nil
}

func serverHostname(host string) string {
    s := strings.TrimPrefix(host, "https://")
    s = strings.TrimPrefix(s, "http://")
    if idx := strings.Index(s, "/"); idx >= 0 {
        s = s[:idx]
    }
    return s
}

func openBrowser(url string) {
    switch runtime.GOOS {
    case "darwin":
        exec.Command("open", url).Start()
    case "linux":
        exec.Command("xdg-open", url).Start()
    case "windows":
        exec.Command("rundll32", "url.dll,FileProtocolHandler", url).Start()
    }
}

Env vars: DATABRICKS_HOST, DATABRICKS_HTTP_PATH, DATABRICKS_U2M_CLIENT_ID, optional DATABRICKS_U2M_CLIENT_SECRET, DATABRICKS_REDIRECT_URI

Setup: Create OAuth app in Account Console → Settings → App connections. Add redirect URI http://localhost:8040/callback.

Environment Variables Reference

Auth Isolation

Run tests with a clean environment using env -i:

env -i PATH=$PATH HOME=$HOME \
  DATABRICKS_HOST=$DATABRICKS_HOST \
  DATABRICKS_HTTP_PATH=$DATABRICKS_HTTP_PATH \
  DATABRICKS_CLIENT_ID=$DATABRICKS_CLIENT_ID \
  DATABRICKS_CLIENT_SECRET=$DATABRICKS_CLIENT_SECRET \
  ./your_binary

Validation Query

Verify User-Agent telemetry is being recorded correctly:

SELECT event_time, user_agent, action_name, request_params
FROM system.access.audit
WHERE event_time > current_timestamp() - INTERVAL 1 HOUR
  AND lower(user_agent) LIKE '%yourcompany%'
ORDER BY event_time DESC
LIMIT 10;

Required Imports

Quick reference for imports by auth type:

// All examples
import (
    "database/sql"
    "fmt"
    "os"
    "strings"
    
    dbsql "github.com/databricks/databricks-sql-go"
)

// OAuth M2M - add:
import "github.com/databricks/databricks-sql-go/auth/oauth/m2m"

// U2M Browser - add:
import (
    "time"
    "github.com/databricks/databricks-sql-go/auth/oauth/u2m"
)

// U2M Custom OAuth App (PKCE) - add:
import (
    "context"
    "crypto/rand"
    "crypto/sha256"
    "encoding/base64"
    "encoding/json"
    "net/http"
    "net/url"
    "os/exec"
    "runtime"
)

// Multi-auth - add:
import "database/sql/driver"

Error Handling Patterns

Basic Error Handling

import (
    "database/sql"
    "errors"
    "strings"
)

func executeQuery(db *sql.DB, query string) error {
    rows, err := db.Query(query)
    if err != nil {
        return handleSQLError(err)
    }
    defer rows.Close()
    // process rows...
    return nil
}

func handleSQLError(err error) error {
    errMsg := err.Error()
    
    switch {
    case strings.Contains(errMsg, "401"):
        return fmt.Errorf("authentication failed: check credentials")
    case strings.Contains(errMsg, "403"):
        return fmt.Errorf("permission denied: check service principal access")
    case strings.Contains(errMsg, "503"):
        return fmt.Errorf("warehouse unavailable: may be starting up")
    case strings.Contains(errMsg, "429"):
        return fmt.Errorf("rate limited: implement backoff")
    case strings.Contains(errMsg, "invalid httpPath"):
        return fmt.Errorf("invalid HTTP path: check DATABRICKS_HTTP_PATH")
    default:
        return err
    }
}

Retry Pattern with Exponential Backoff

import (
    "context"
    "database/sql"
    "strings"
    "time"
)

// RetryConfig holds retry behavior settings
type RetryConfig struct {
    MaxRetries     int
    InitialBackoff time.Duration
    MaxBackoff     time.Duration
    Multiplier     float64
}

// DefaultRetryConfig returns production-recommended settings
func DefaultRetryConfig() RetryConfig {
    return RetryConfig{
        MaxRetries:     3,
        InitialBackoff: 2 * time.Second,
        MaxBackoff:     30 * time.Second,
        Multiplier:     2.0,
    }
}

func QueryWithRetry(ctx context.Context, db *sql.DB, cfg RetryConfig, query string) (*sql.Rows, error) {
    var lastErr error
    backoff := cfg.InitialBackoff
    
    for attempt := 0; attempt <= cfg.MaxRetries; attempt++ {
        rows, err := db.QueryContext(ctx, query)
        if err == nil {
            return rows, nil
        }
        lastErr = err
        
        if !isRetryable(err) || attempt >= cfg.MaxRetries {
            return nil, err
        }
        
        fmt.Printf("[Retry %d/%d] Waiting %v. Error: %v\n", attempt+1, cfg.MaxRetries, backoff, err)
        select {
        case <-ctx.Done():
            return nil, ctx.Err()
        case <-time.After(backoff):
            backoff = time.Duration(float64(backoff) * cfg.Multiplier)
            if backoff > cfg.MaxBackoff {
                backoff = cfg.MaxBackoff
            }
        }
    }
    return nil, lastErr
}

func isRetryable(err error) bool {
    msg := err.Error()
    // Retryable: server errors, rate limits, transient failures
    if strings.Contains(msg, "503") || strings.Contains(msg, "429") ||
       strings.Contains(msg, "500") || strings.Contains(msg, "502") ||
       strings.Contains(msg, "connection reset") ||
       strings.Contains(msg, "TEMPORARILY_UNAVAILABLE") {
        return true
    }
    // Non-retryable: auth, permissions, syntax errors
    if strings.Contains(msg, "401") || strings.Contains(msg, "403") ||
       strings.Contains(msg, "AnalysisException") || strings.Contains(msg, "ParseException") {
        return false
    }
    return false
}

// Usage:
// cfg := DefaultRetryConfig()
// rows, err := QueryWithRetry(ctx, db, cfg, "SELECT * FROM table")

Troubleshooting

Common Errors

OAuth-Specific Errors

U2M Browser Issues

Host Normalization Issues

Multi-Auth Pattern

Support multiple auth types in a single binary using DATABRICKS_AUTH_TYPE:

authType := os.Getenv("DATABRICKS_AUTH_TYPE")
if authType == "" {
    authType = "pat"
}

var connector driver.Connector
var err error

switch authType {
case "pat":
    connector, err = dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAccessToken(os.Getenv("DATABRICKS_TOKEN")),
        dbsql.WithUserAgentEntry(userAgent),
    )
case "oauth_m2m", "m2m":
    auth := m2m.NewAuthenticator(
        os.Getenv("DATABRICKS_CLIENT_ID"),
        os.Getenv("DATABRICKS_CLIENT_SECRET"),
        serverHostname(host),
    )
    connector, err = dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAuthenticator(auth),
        dbsql.WithUserAgentEntry(userAgent),
    )
case "u2m_browser", "u2m":
    auth, err := u2m.NewAuthenticator(serverHostname(host), 2*time.Minute)
    if err != nil {
        panic(err)
    }
    connector, err = dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAuthenticator(auth),
        dbsql.WithUserAgentEntry(userAgent),
    )
case "u2m_token_env":
    token := os.Getenv("DATABRICKS_ACCESS_TOKEN")
    if token == "" {
        token = os.Getenv("DATABRICKS_TOKEN")
    }
    connector, err = dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAccessToken(token),
        dbsql.WithUserAgentEntry(userAgent),
    )
case "u2m_custom_oauth_app":
    token, err := runPKCEFlow(host, clientID, clientSecret, redirectURI)
    if err != nil {
        panic(err)
    }
    connector, err = dbsql.NewConnector(
        dbsql.WithServerHostname(serverHostname(host)),
        dbsql.WithPort(443),
        dbsql.WithHTTPPath(httpPath),
        dbsql.WithAccessToken(token),
        dbsql.WithUserAgentEntry(userAgent),
    )
}

Note: Unlike the Databricks SDK for Go, the SQL driver does NOT read DATABRICKS_AUTH_TYPE internally, so you can safely use it as your app-level auth selector.

U2M Browser Environment Requirements

For U2M browser flows to work, pass these environment variables when running with env -i:

env -i PATH=$PATH HOME=$HOME USER=$USER DISPLAY=$DISPLAY \
  DATABRICKS_HOST=$DATABRICKS_HOST \
  DATABRICKS_HTTP_PATH=$DATABRICKS_HTTP_PATH \
  ./your_binary

• HOME - Required for browser profile access
• USER - Required by some browsers
• DISPLAY - Required on Linux for GUI browser

Testing with Auth Isolation

Test each auth type with a clean environment to avoid "more than one authorization method" conflicts:

# PAT test
env -i PATH=$PATH HOME=$HOME \
  DATABRICKS_HOST=$DATABRICKS_HOST \
  DATABRICKS_HTTP_PATH=$DATABRICKS_HTTP_PATH \
  DATABRICKS_TOKEN=$DATABRICKS_TOKEN \
  DATABRICKS_AUTH_TYPE=pat \
  ./go_sql_all_auth

# OAuth M2M test
env -i PATH=$PATH HOME=$HOME \
  DATABRICKS_HOST=$DATABRICKS_HOST \
  DATABRICKS_HTTP_PATH=$DATABRICKS_HTTP_PATH \
  DATABRICKS_CLIENT_ID=$DATABRICKS_CLIENT_ID \
  DATABRICKS_CLIENT_SECRET=$DATABRICKS_CLIENT_SECRET \
  DATABRICKS_AUTH_TYPE=oauth_m2m \
  ./go_sql_all_auth

# U2M Browser test (needs DISPLAY, USER for browser)
env -i PATH=$PATH HOME=$HOME USER=$USER DISPLAY=$DISPLAY \
  DATABRICKS_HOST=$DATABRICKS_HOST \
  DATABRICKS_HTTP_PATH=$DATABRICKS_HTTP_PATH \
  DATABRICKS_AUTH_TYPE=u2m_browser \
  ./go_sql_all_auth

# U2M Custom OAuth App test
env -i PATH=$PATH HOME=$HOME USER=$USER DISPLAY=$DISPLAY \
  DATABRICKS_HOST=$DATABRICKS_HOST \
  DATABRICKS_HTTP_PATH=$DATABRICKS_HTTP_PATH \
  DATABRICKS_U2M_CLIENT_ID=$DATABRICKS_U2M_CLIENT_ID \
  DATABRICKS_AUTH_TYPE=u2m_custom_oauth_app \
  ./go_sql_all_auth

PKCE Flow with Timeout

Add timeout handling to the PKCE flow for better UX:

func runPKCEFlow(host, clientID, clientSecret, redirectURI string) (string, error) {
    // ... setup code_verifier, code_challenge, state ...

    codeChan := make(chan string, 1)
    errChan := make(chan error, 1)

    server := &http.Server{Addr: ":" + port}
    // ... setup handler ...

    go server.ListenAndServe()
    defer server.Shutdown(context.Background())

    openBrowser(authURL)

    // Timeout for user to complete browser auth
    select {
    case code := <-codeChan:
        return exchangeCodeForToken(code, codeVerifier, clientID, clientSecret, redirectURI, host)
    case err := <-errChan:
        return "", err
    case <-time.After(2 * time.Minute):
        return "", fmt.Errorf("authentication timed out after 2 minutes")
    }
}

Key Differences from Databricks SDK for Go

Build Tags for Multiple Examples

When organizing multiple Go example files in the same package, use build tags to compile each example separately. This prevents "main redeclared" errors.

Adding Build Tags

Each example file should have a build tag at the top (before package declaration):

//go:build pat_example

package main
// ... rest of file

Example File Tags

Shared Helper Files

For shared helpers (like PKCE helper) that are used by multiple examples, use OR conditions:

//go:build go_all_auth_example || u2m_custom_oauth_app_example || u2m_builtin_oauth_example

package main
// ... shared helper code

Building with Tags

# Build specific example
go build -tags=pat_example -o pat_example_bin .
go build -tags=oauth_m2m_example -o oauth_m2m_bin .
go build -tags=go_all_auth_example -o all_auth_bin .

# Build and run
go build -tags=u2m_custom_oauth_app_example -o u2m_bin . && ./u2m_bin

Why Build Tags?

Without build tags, Go tries to compile all .go files in a package together, causing conflicts when multiple files define func main() or the same constants/variables. Build tags solve this by selectively including files during compilation.

Implementation Learnings

1. Host normalization is critical: Always use serverHostname() helper to strip https:// before passing to WithServerHostname()
2. Port 443 required: Always include WithPort(443) for HTTPS connections
3. User-Agent per connector: Unlike SDK's global setting, each connector needs WithUserAgentEntry()
4. U2M browser requires env vars: Pass HOME, USER, DISPLAY via env -i for browser to launch
5. M2M auto-refreshes: The m2m.NewAuthenticator() handles token refresh automatically
6. Build tags prevent conflicts: When multiple example files exist in same package, use build tags to compile individually
7. PKCE helper is shared: The PKCE helper file needs conditional build tags to be included with relevant examples