DBOS Go Best Practices

dbos-golang

DBOS Go SDK for building reliable, fault-tolerant applications with durable workflows. Use this skill when writing Go code with DBOS, creating workflows and steps, using queues, using the DBOS Clie...

MudassarAbrar/SAGE__GEMINI_LIVE_AGENT_HACKATHON·0installs3stars

SKILL.md

Full skill instructions

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

Priority	Category	Impact	Prefix
1	Lifecycle	CRITICAL	`lifecycle-`
2	Workflow	CRITICAL	`workflow-`
3	Step	HIGH	`step-`
4	Queue	HIGH	`queue-`
5	Communication	MEDIUM	`comm-`
6	Pattern	MEDIUM	`pattern-`
7	Testing	LOW-MEDIUM	`test-`
8	Client	MEDIUM	`client-`
9	Advanced	LOW	`advanced-`

Critical Rules

Installation

Install the DBOS Go module:

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

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

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
}

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

References

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/MudassarAbrar/SAGE__GEMINI_LIVE_AGENT_HACKATHON --skill dbos-golang

View on GitHub

skills/dbos-golang/SKILL.md

code-review-checklist
Comprehensive checklist for conducting thorough code reviews covering functionality, security, performance, and maintainability
0 installs
azure-mgmt-arizeaiobservabilityeval-dotnet
.NET SDK for managing Arize AI Observability and Evaluation resources on Azure.
0 installs
computer-vision-expert
SOTA Computer Vision Expert (2026). Specialized in YOLO26, Segment Anything 3 (SAM 3), Vision Language Models, and real-time spatial analysis.
0 installs
performance-engineer
Expert performance engineer specializing in modern observability,
0 installs