'v1'

2026-07-06 18:06:28 +02:00
parent 9d189020de
commit fdbe811cdc
279 changed files with 60644 additions and 0 deletions
@@ -0,0 +1,131 @@
+---
+name: dbos-golang
+description: "Guide for building reliable, fault-tolerant Go applications with DBOS durable workflows. Use when adding DBOS to existing Go code, creating workflows and steps, or using queues for concurrency control."
+risk: safe
+source: "https://docs.dbos.dev/"
+date_added: "2026-02-27"
+---
+
+# 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:
+
+```bash
+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:
+
+```go
+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`:
+
+```go
+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
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.