DBOS Go Best Practices

Guide for building reliable, fault-tolerant Go applications with DBOS durable workflows.

When to Use

Reference these guidelines when: - Adding DBOS to existing Go code - Creating workflows and steps - Using queues for concurrency control - Implementing workflow communication (events, messages, streams) - Configuring and launching DBOS applications - Using the DBOS Client from external applications - Testing DBOS applications

Rule Categories by Priority

Critical Rules

Installation

Install the DBOS Go module:

go get github.com/dbos-inc/dbos-transact-golang/dbos@latest
Copy

DBOS Configuration and Launch

A DBOS application MUST create a context, register workflows, and launch before running any workflows:

package main

import (
    "context"
    "log"
    "os"
    "time"

    "github.com/dbos-inc/dbos-transact-golang/dbos"
)

func main() {
    ctx, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
        AppName:     "my-app",
        DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
    })
    if err != nil {
        log.Fatal(err)
    }
    defer dbos.Shutdown(ctx, 30*time.Second)

    dbos.RegisterWorkflow(ctx, myWorkflow)

    if err := dbos.Launch(ctx); err != nil {
        log.Fatal(err)
    }
}
Copy

Workflow and Step Structure

Workflows are comprised of steps. Any function performing complex operations or accessing external services must be run as a step using dbos.RunAsStep:

func fetchData(ctx context.Context) (string, error) {
    resp, err := http.Get("https://api.example.com/data")
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    return string(body), nil
}

func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
    result, err := dbos.RunAsStep(ctx, fetchData, dbos.WithStepName("fetchData"))
    if err != nil {
        return "", err
    }
    return result, nil
}
Copy

Key Constraints

• Do NOT start or enqueue workflows from within steps
• Do NOT use uncontrolled goroutines to start workflows - use dbos.RunWorkflow with queues or dbos.Go/dbos.Select for concurrent steps
• Workflows MUST be deterministic - non-deterministic operations go in steps
• Do NOT modify global variables from workflows or steps
• All workflows and queues MUST be registered before calling Launch()

How to Use

Read individual rule files for detailed explanations and examples:

references/lifecycle-config.md
references/workflow-determinism.md
references/queue-concurrency.md
Copy

References

• https://docs.dbos.dev/
• https://github.com/dbos-inc/dbos-transact-golang

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.