Dbos Golang

1---
2name: dbos-golang
3description: 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 Client from external applications, or building Go applications that need to be resilient to failures.
4risk: safe
5source: https://docs.dbos.dev/
6license: MIT
7metadata:
8  author: dbos
9  version: "1.0.0"
10  organization: DBOS
11  date: February 2026
12  abstract: Comprehensive guide for building fault-tolerant Go applications with DBOS. Covers workflows, steps, queues, communication patterns, and best practices for durable execution.
13---
14 
15# DBOS Go Best Practices
16 
17Guide for building reliable, fault-tolerant Go applications with DBOS durable workflows.
18 
19## When to Use
20 
21Reference these guidelines when:
22- Adding DBOS to existing Go code
23- Creating workflows and steps
24- Using queues for concurrency control
25- Implementing workflow communication (events, messages, streams)
26- Configuring and launching DBOS applications
27- Using the DBOS Client from external applications
28- Testing DBOS applications
29 
30## Rule Categories by Priority
31 
32| Priority | Category | Impact | Prefix |
33|----------|----------|--------|--------|
34| 1 | Lifecycle | CRITICAL | `lifecycle-` |
35| 2 | Workflow | CRITICAL | `workflow-` |
36| 3 | Step | HIGH | `step-` |
37| 4 | Queue | HIGH | `queue-` |
38| 5 | Communication | MEDIUM | `comm-` |
39| 6 | Pattern | MEDIUM | `pattern-` |
40| 7 | Testing | LOW-MEDIUM | `test-` |
41| 8 | Client | MEDIUM | `client-` |
42| 9 | Advanced | LOW | `advanced-` |
43 
44## Critical Rules
45 
46### Installation
47 
48Install the DBOS Go module:
49 
50```bash
51go get github.com/dbos-inc/dbos-transact-golang/dbos@latest
52```
53 
54### DBOS Configuration and Launch
55 
56A DBOS application MUST create a context, register workflows, and launch before running any workflows:
57 
58```go
59package main
60 
61import (
62	"context"
63	"log"
64	"os"
65	"time"
66 
67	"github.com/dbos-inc/dbos-transact-golang/dbos"
68)
69 
70func main() {
71	ctx, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
72		AppName:     "my-app",
73		DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
74	})
75	if err != nil {
76		log.Fatal(err)
77	}
78	defer dbos.Shutdown(ctx, 30*time.Second)
79 
80	dbos.RegisterWorkflow(ctx, myWorkflow)
81 
82	if err := dbos.Launch(ctx); err != nil {
83		log.Fatal(err)
84	}
85}
86```
87 
88### Workflow and Step Structure
89 
90Workflows are comprised of steps. Any function performing complex operations or accessing external services must be run as a step using `dbos.RunAsStep`:
91 
92```go
93func fetchData(ctx context.Context) (string, error) {
94	resp, err := http.Get("https://api.example.com/data")
95	if err != nil {
96		return "", err
97	}
98	defer resp.Body.Close()
99	body, _ := io.ReadAll(resp.Body)
100	return string(body), nil
101}
102 
103func myWorkflow(ctx dbos.DBOSContext, input string) (string, error) {
104	result, err := dbos.RunAsStep(ctx, fetchData, dbos.WithStepName("fetchData"))
105	if err != nil {
106		return "", err
107	}
108	return result, nil
109}
110```
111 
112### Key Constraints
113 
114- Do NOT start or enqueue workflows from within steps
115- Do NOT use uncontrolled goroutines to start workflows - use `dbos.RunWorkflow` with queues or `dbos.Go`/`dbos.Select` for concurrent steps
116- Workflows MUST be deterministic - non-deterministic operations go in steps
117- Do NOT modify global variables from workflows or steps
118- All workflows and queues MUST be registered before calling `Launch()`
119 
120## How to Use
121 
122Read individual rule files for detailed explanations and examples:
123 
124```
125references/lifecycle-config.md
126references/workflow-determinism.md
127references/queue-concurrency.md
128```
129 
130## References
131 
132- https://docs.dbos.dev/
133- https://github.com/dbos-inc/dbos-transact-golang
134