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