Skip to main content

Go SDK

The official Go SDK for Sparbz Cloud.

Installation​

go get github.com/sparbz-cloud/sdk-go

Requires Go 1.21 or later.

Quick Start​

package main

import (
    "context"
    "fmt"
    "log"

    szc "github.com/sparbz-cloud/sdk-go"
)

func main() {
    // Create client with API key
    client := szc.NewClient(szc.WithAPIKey("szc_prod_..."))

    // List all databases
    databases, err := client.Databases.List(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    for _, db := range databases {
        fmt.Printf("Database: %s (%s)\n", db.Name, db.Status)
    }
}

Configuration​

API Key Authentication​

client := szc.NewClient(szc.WithAPIKey("szc_prod_..."))

JWT Token Authentication​

client := szc.NewClient(szc.WithToken("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."))

Custom Options​

client := szc.NewClient(
    szc.WithAPIKey("szc_prod_..."),
    szc.WithBaseURL("https://api.sparbz.cloud"),
    szc.WithTimeout(30 * time.Second),
    szc.WithRetries(3),
    szc.WithLogger(logger),
)

Environment Variables​

The SDK reads these environment variables:

export SPARBZ_API_KEY="szc_prod_..."
export SPARBZ_API_URL="https://api.sparbz.cloud"
// Uses environment variables automatically
client := szc.NewClient()

Databases​

List Databases​

databases, err := client.Databases.List(ctx)
if err != nil {
    log.Fatal(err)
}

// With filters
databases, err := client.Databases.List(ctx, &szc.DatabaseListOptions{
    Engine: szc.EnginePostgres,
    Status: szc.StatusActive,
})

Create Database​

db, err := client.Databases.Create(ctx, &szc.DatabaseCreateRequest{
    Name:   "my-database",
    Engine: szc.EnginePostgres,
    Tier:   szc.TierPro,
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Created database: %s\n", db.ID)

Get Database​

db, err := client.Databases.Get(ctx, "db_abc123")
if err != nil {
    log.Fatal(err)
}

Delete Database​

err := client.Databases.Delete(ctx, "db_abc123", &szc.DatabaseDeleteOptions{
    SkipFinalBackup: false,
})

Get Credentials​

creds, err := client.Databases.GetCredentials(ctx, "db_abc123")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Connection string: %s\n", creds.ConnectionString)

Namespaces​

List Namespaces​

namespaces, err := client.Namespaces.List(ctx)

Create Namespace​

ns, err := client.Namespaces.Create(ctx, &szc.NamespaceCreateRequest{
    Name: "my-app",
    Tier: szc.TierStarter,
})

Get Kubeconfig​

kubeconfig, err := client.Namespaces.GetKubeconfig(ctx, "ns_abc123")
if err != nil {
    log.Fatal(err)
}

// Write to file
os.WriteFile("kubeconfig.yaml", []byte(kubeconfig), 0600)

Apply Manifest​

manifest := `
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
`

result, err := client.Namespaces.Apply(ctx, "ns_abc123", manifest)
if err != nil {
    log.Fatal(err)
}

for _, resource := range result.Applied {
    fmt.Printf("Applied: %s/%s\n", resource.Kind, resource.Name)
}

Storage​

List Buckets​

buckets, err := client.Storage.List(ctx)

Create Bucket​

bucket, err := client.Storage.Create(ctx, &szc.BucketCreateRequest{
    Name:   "my-bucket",
    Region: "us-east",
})

Get Credentials​

creds, err := client.Storage.GetCredentials(ctx, "bucket_abc123")
fmt.Printf("Access Key: %s\n", creds.AccessKeyID)
fmt.Printf("Secret Key: %s\n", creds.SecretAccessKey)
fmt.Printf("Endpoint: %s\n", creds.Endpoint)

Generate Presigned URL​

url, err := client.Storage.PresignedURL(ctx, "bucket_abc123", &szc.PresignedURLRequest{
    Key:       "uploads/file.pdf",
    Method:    "PUT",
    ExpiresIn: 3600,
})

Kafka​

List Clusters​

clusters, err := client.Kafka.List(ctx)

Create Cluster​

cluster, err := client.Kafka.Create(ctx, &szc.KafkaCreateRequest{
    Name: "my-kafka",
    Tier: szc.TierPro,
})

// Wait for cluster to be ready
cluster, err = client.Kafka.WaitReady(ctx, cluster.ID, 10*time.Minute)

Manage Topics​

// Create topic
topic, err := client.Kafka.CreateTopic(ctx, "cluster_id", &szc.KafkaTopicRequest{
    Name:       "orders",
    Partitions: 6,
    Replicas:   3,
})

// List topics
topics, err := client.Kafka.ListTopics(ctx, "cluster_id")

// Delete topic
err = client.Kafka.DeleteTopic(ctx, "cluster_id", "orders")

Manage Users​

// Create user
user, err := client.Kafka.CreateUser(ctx, "cluster_id", &szc.KafkaUserRequest{
    Name: "my-app",
})

// Get credentials
creds, err := client.Kafka.GetUserCredentials(ctx, "cluster_id", user.ID)
fmt.Printf("Username: %s\n", creds.Username)
fmt.Printf("Password: %s\n", creds.Password)

Vault​

List Secrets​

secrets, err := client.Vault.List(ctx, "secret/data/my-app")

Write Secret​

err := client.Vault.Write(ctx, "secret/data/my-app/config", map[string]interface{}{
    "api_key":      "sk_live_...",
    "database_url": "postgres://...",
})

Read Secret​

secret, err := client.Vault.Read(ctx, "secret/data/my-app/config")
if err != nil {
    log.Fatal(err)
}

apiKey := secret.Data["api_key"].(string)

Delete Secret​

err := client.Vault.Delete(ctx, "secret/data/my-app/config")

Stacks​

Create Stack​

stack, err := client.Stacks.Create(ctx, &szc.StackCreateRequest{
    Name:   "my-app",
    Tenant: "acme-corp",
    Template: szc.StackTemplate{
        Version: "1",
        Name:    "my-app",
        Resources: map[string]szc.StackResource{
            "database": {
                Type: "database",
                Properties: map[string]interface{}{
                    "engine":  "postgres",
                    "version": "15",
                },
            },
        },
    },
})

Apply Stack​

execution, err := client.Stacks.Apply(ctx, stack.ID, &szc.StackApplyOptions{
    DryRun: false,
})

// Wait for completion
execution, err = client.Stacks.WaitExecution(ctx, stack.ID, execution.ID, 30*time.Minute)
if execution.Status == "completed" {
    fmt.Println("Stack deployed successfully!")
}

Get Outputs​

outputs, err := client.Stacks.GetOutputs(ctx, stack.ID)
for name, output := range outputs {
    if !output.Sensitive {
        fmt.Printf("%s = %s\n", name, output.Value)
    }
}

Error Handling​

db, err := client.Databases.Get(ctx, "db_abc123")
if err != nil {
    var apiErr *szc.APIError
    if errors.As(err, &apiErr) {
        switch apiErr.Code {
        case "not_found":
            fmt.Println("Database not found")
        case "unauthorized":
            fmt.Println("Invalid API key")
        case "rate_limited":
            fmt.Printf("Rate limited, retry after %d seconds\n", apiErr.RetryAfter)
        default:
            fmt.Printf("API error: %s\n", apiErr.Message)
        }
    } else {
        log.Fatal(err)
    }
}

Pagination​

// Manual pagination
page := 1
for {
    databases, err := client.Databases.List(ctx, &szc.DatabaseListOptions{
        Page:    page,
        PerPage: 20,
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, db := range databases.Data {
        fmt.Printf("Database: %s\n", db.Name)
    }

    if page >= databases.Meta.TotalPages {
        break
    }
    page++
}

// Iterator pattern
iter := client.Databases.ListAll(ctx, nil)
for iter.Next() {
    db := iter.Current()
    fmt.Printf("Database: %s\n", db.Name)
}
if err := iter.Err(); err != nil {
    log.Fatal(err)
}

Context and Timeouts​

// With timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

db, err := client.Databases.Create(ctx, &szc.DatabaseCreateRequest{
    Name: "my-database",
})

// With cancellation
ctx, cancel := context.WithCancel(context.Background())
go func() {
    <-sigChan
    cancel()
}()

err := client.Stacks.Apply(ctx, stackID, nil)
if errors.Is(err, context.Canceled) {
    fmt.Println("Operation cancelled")
}

Logging​

import "log/slog"

logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelDebug,
}))

client := szc.NewClient(
    szc.WithAPIKey("szc_prod_..."),
    szc.WithLogger(logger),
)

Testing​

Use the mock client for testing:

import "github.com/sparbz-cloud/sdk-go/mock"

func TestCreateDatabase(t *testing.T) {
    mockClient := mock.NewClient()
    mockClient.Databases.On("Create", mock.Anything, mock.Anything).Return(&szc.Database{
        ID:     "db_test123",
        Name:   "test-db",
        Status: szc.StatusActive,
    }, nil)

    // Use mockClient in your test
    db, err := mockClient.Databases.Create(ctx, &szc.DatabaseCreateRequest{
        Name: "test-db",
    })

    assert.NoError(t, err)
    assert.Equal(t, "db_test123", db.ID)
}

Complete Example​

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    szc "github.com/sparbz-cloud/sdk-go"
)

func main() {
    ctx := context.Background()
    client := szc.NewClient()

    // Create a database
    db, err := client.Databases.Create(ctx, &szc.DatabaseCreateRequest{
        Name:   "my-app-db",
        Engine: szc.EnginePostgres,
        Tier:   szc.TierStarter,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created database: %s\n", db.ID)

    // Wait for it to be ready
    db, err = client.Databases.WaitReady(ctx, db.ID, 10*time.Minute)
    if err != nil {
        log.Fatal(err)
    }

    // Get connection credentials
    creds, err := client.Databases.GetCredentials(ctx, db.ID)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Connection string: %s\n", creds.ConnectionString)

    // Store credentials in Vault
    err = client.Vault.Write(ctx, "secret/data/my-app/database", map[string]interface{}{
        "connection_string": creds.ConnectionString,
    })
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("Credentials stored in Vault")
}