Go Quick Start

WoWSQL Go SDK — Get started in minutes

Get your API key: Use the WoWSQL project dashboard to create or copy your API key. The same key works for database, auth, and storage (unified API key).

Installation

Official package: View on pkg.go.dev → · GitHub

go get github.com/wowsql/wowsql-go

Initialize Client

package main

import "github.com/wowsql/wowsql-go/WOWSQL"

func main() {
    // Initialize client with your API key (same key for database, auth, storage)
    client := WOWSQL.NewClient(
        "https://myproject.wowsql.com",
        "your_api_key_here",
    )

    // Or with project subdomain
    client2 := WOWSQL.NewClient(
        "myproject",
        "your_api_key",
    )

    // Always use Select() before Execute()
    users, err := client.Table("users").Select("*").Execute()
    if err != nil {
        panic(err)
    }
}

Query Data

Basic Queries

// Get all records
users, err := client.Table("users").Select("*").Execute()

// With filters - use Eq, Gte, or Filter
adults, err := client.Table("users").
    Select("*").
    Gte("age", 18).
    Execute()

// Or using Filter(column, operator, value)
adults2, err := client.Table("users").
    Select("*").
    Filter("age", "gte", 18).
    Execute()

// Select specific columns
names, err := client.Table("users").
    Select("id", "name").
    Execute()

Advanced Queries

// Multiple filters with sorting
activeUsers, err := client.Table("users").
    Select("*").
    Eq("status", "active").
    Gt("age", 18).
    OrderBy("created_at", WOWSQL.SortDesc).
    Limit(20).
    Offset(0).
    Execute()

fmt.Printf("Found %d users\n", activeUsers.Count)
for _, user := range activeUsers.Data {
    fmt.Println(user["name"])
}

Filter Helper Methods

// Using helper methods
users, err := client.Table("users").
    Eq("status", "active").
    Gt("age", 18).
    Like("email", "%@gmail.com").
    IsNotNull("email_verified_at").
    In("role", []interface{}{"admin", "moderator"}).
    Between("created_at", "2024-01-01", "2024-12-31").
    Execute()

// OR conditions
usersOr, err := client.Table("users").
    Eq("status", "active").
    Or("role", "eq", "admin").
    Execute()

GROUP BY and Aggregates

Basic GROUP BY

// Group by category with counts
result, err := client.Table("products").
    Select("category", "COUNT(*) as count", "AVG(price) as avg_price").
    GroupBy("category").
    Execute()

// Group by date
result2, err := client.Table("orders").
    Select("DATE(created_at) as date", "COUNT(*) as orders", "SUM(total) as revenue").
    GroupBy("DATE(created_at)").
    OrderBy("date", WOWSQL.SortDesc).
    Execute()

// Multiple GROUP BY columns
result3, err := client.Table("sales").
    Select("region", "category", "SUM(amount) as total").
    GroupBy("region", "category").
    Execute()

HAVING Clause

// Filter aggregated results
result, err := client.Table("products").
    Select("category", "COUNT(*) as count").
    GroupBy("category").
    Having("COUNT(*)", "gt", 10).
    Execute()

// Multiple HAVING conditions
result2, err := client.Table("orders").
    Select("DATE(created_at) as date", "SUM(total) as revenue").
    GroupBy("DATE(created_at)").
    Having("SUM(total)", "gt", 1000).
    Having("COUNT(*)", "gte", 5).
    Execute()

Multiple ORDER BY

// Order by multiple columns
result, err := client.Table("products").
    Select("*").
    OrderByMultiple([]WOWSQL.OrderByItem{
        {Column: "category", Direction: WOWSQL.SortAsc},
        {Column: "price", Direction: WOWSQL.SortDesc},
        {Column: "created_at", Direction: WOWSQL.SortDesc},
    }).
    Execute()

CRUD Operations

Create Record

result, err := client.Table("users").Insert(map[string]interface{}{
    "name":  "John Doe",
    "email": "john@example.com",
    "age":   30,
})
fmt.Printf("Created user with ID: %v\n", result.ID)

Update Record

res, err := client.Table("users").UpdateByID(123, map[string]interface{}{
    "email": "newemail@example.com",
})
fmt.Println("User updated successfully")

Delete Record

_, err := client.Table("users").DeleteByID(123)
fmt.Println("User deleted successfully")

Get Single Record by ID

user, err := client.Table("users").GetByID(123)
fmt.Printf("User: %v\n", user["name"])

Get First Record

user, err := client.Table("users").
    Eq("status", "active").
    First()

if user != nil {
    fmt.Printf("First active user: %v\n", (*user)["name"])
}

Filter Operators

Available operators for filtering data:

Error Handling

users, err := client.Table("users").Select("*").Execute()
if err != nil {
    var authErr *WOWSQL.AuthenticationError
    var notFoundErr *WOWSQL.NotFoundError
    switch {
    case errors.As(err, &authErr):
        fmt.Println("Authentication failed — check your API key")
    case errors.As(err, &notFoundErr):
        fmt.Println("Table or resource not found")
    default:
        fmt.Printf("Error: %v\n", err)
    }
    return
}
fmt.Printf("Success: %d users\n", users.Count)

Authentication

Use the same API key for authentication. One key works for database and auth.

Sign Up & Sign In

auth := WOWSQL.NewAuthClient(WOWSQL.AuthConfig{
    ProjectURL: "myproject",
    APIKey:     "your_api_key",
})

// Sign up
result, err := auth.SignUp("user@example.com", "SecurePassword123",
    WOWSQL.WithFullName("John Doe"))
fmt.Printf("Access token: %s\n", result.Session.AccessToken)

// Sign in
login, err := auth.SignIn("user@example.com", "SecurePassword123")
fmt.Printf("User ID: %s\n", login.User.ID)

Password Reset

auth.ForgotPassword("user@example.com")

auth.ResetPassword("reset_token_from_email", "NewSecurePassword123")

OAuth Authentication

oauthResp, err := auth.GetOAuthAuthorizationURL("github", "http://localhost:5000/auth/callback")
// Redirect user to oauthResp.AuthorizationURL

oauthResult, err := auth.ExchangeOAuthCallback("github", "authorization_code_from_callback", &redirectURI)
fmt.Printf("OAuth login successful: %s\n", oauthResult.User.Email)

Storage Operations

Initialize Storage

storage := WOWSQL.NewStorageClient(
    "myproject",
    "your_api_key",
)

File Operations

// Upload file
fileData, _ := os.ReadFile("path/to/document.pdf")
result, err := storage.Upload(fileData, "uploads/document.pdf", "application/pdf", nil)
fmt.Printf("Uploaded: %s\n", result.URL)

// Get presigned URL
url, err := storage.Download("uploads/document.pdf", 3600)
fmt.Printf("Download URL: %s\n", url)

// List files
files, err := storage.ListFiles("uploads/", 0)
for _, file := range files {
    fmt.Printf("%s: %d bytes\n", file.Key, file.Size)
}

// Delete file
err = storage.DeleteFile("uploads/document.pdf")

// Check quota
quota, err := storage.GetQuota()
fmt.Printf("Used: %.2f GB / %.2f GB\n", quota.StorageUsedGB, quota.StorageQuotaGB)

Download or View File

Via REST: use GET .../files/{file_key}/download for attachment download, or GET .../files/{file_key}/view to view inline in the browser.