DBOS Go Best Practices Skill

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

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

Agent Skills: DBOS Go Best Practices

Install this agent skill to your local

Skill Files