Dbos Golang

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

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

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

AGI Framework Integration

Adapted for @techwavedev/agi-agent-kit Original source: antigravity-awesome-skills

Memory-First Protocol

Retrieve prior API design decisions, database schema choices, and error handling patterns. Cache API response templates for consistent error formatting.

# Check for prior backend/API context before starting
python3 execution/memory_manager.py auto --query "API design patterns and architecture decisions for Dbos Golang"

Storing Results

After completing work, store backend/API decisions for future sessions:

python3 execution/memory_manager.py store \
  --content "API architecture: REST with HATEOAS, JWT auth, rate limiting at 100 req/min per tenant" \
  --type decision --project <project> \
  --tags dbos-golang backend

Multi-Agent Collaboration

Share API contract changes with frontend agents so they update their client code, and with QA agents for test coverage.

python3 execution/cross_agent_context.py store \
  --agent "<your-agent>" \
  --action "Implemented API endpoints — 5 new routes with OpenAPI spec and integration tests" \
  --project <project>

Agent Team: Code Review

After implementation, dispatch code_review_team for two-stage review (spec compliance + code quality) before merging.