Skip to main content
skill CX Codex

dbos-golang — Claude Code skill: what it does, how to install

dbos-golang is a Claude Code skill for building Go applications with DBOS workflows, steps, and queues. It covers durable execution and DBOS code review.

MIT 314 installs ★ 20 updated 2026-10-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dbos-inc/agent-skills --skill dbos-golang -a claude-code
Open on GitHub

What dbos-golang does

This skill covers the DBOS Go SDK, from creating an application context and registering workflows to launching the app and working with queues. It shows how to move external operations into dbos.RunAsStep and place writes that must happen exactly once in a datasource transaction with dbos.RunAsTransaction.

The guide calls out execution constraints: workflows must be deterministic, and a step must not start or enqueue a workflow. Register every workflow and datasource before calling Launch(). DBOS Conductor connections and automatic workflow upgrades require DBOS Enterprise for Go at the same minor version as the core module; without it, the relevant initialization fails. Install the core module with go get github.com/dbos-inc/dbos-transact-golang/dbos@latest.

What it helps with

  • configure a DBOS Go application lifecycle
  • move external calls into durable workflow steps
  • put exactly-once writes in datasource transactions
  • control workflow concurrency with queues
  • check workflow determinism and registration order

Example prompts for the agent

  • Set up this Go app with DBOS and register its workflows before Launch().
  • Review this workflow and move external operations into dbos.RunAsStep where needed.
  • Show how to perform this database write exactly once with dbos.RunAsTransaction.

How to install dbos-golang

1Skills CLI (Vercel)

npx skills add dbos-inc/agent-skills --skill dbos-golang -a claude-code

2Manually: put the files in place

~/.claude/skills/dbos-golang/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/dbos-golang/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about dbos-golang

How do I install dbos-golang in Claude Code?

Run npx skills add dbos-inc/agent-skills --skill dbos-golang -a claude-code. The skill file is installed at ~/.claude/skills/dbos-golang/SKILL.md.

What does dbos-golang do?

It guides Go development with the DBOS SDK, including workflow setup, steps, queues, and application launch. It also explains execution constraints and transaction use.

What is required to connect to DBOS Conductor?

Use DBOS Enterprise for Go at the same minor version as the core module and add a blank import of go.dbos.dev/dbos-enterprise-go. Without that, dbos.NewContext fails during initialization.

Source text

SKILL.md · MIT
---
name: dbos-golang
description: 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.
license: MIT
metadata:
  author: dbos
  version: "2.3.0"
  organization: DBOS
  date: October 2026
  abstract: Comprehensive guide for building fault-tolerant Go applications with DBOS. Covers workflows, steps, queues, communication patterns, and best practices for durable execution.
---

# DBOS Go Best Practices

Guide for building reliable, fault-tolerant Go applications with DBOS durable workflows.

## When to Apply

Reference these guidelines when:
- Adding DBOS to existing Go code
- Creating workflows and steps
- Running database transactions durably through datasources
- 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 (v1):

```bash
go get github.com/dbos-inc/dbos-transact-golang/dbos@latest
```

Connecting to DBOS Conductor (setting `ConductorAPIKey`, or running in DBOS Cloud) and auto-upgrading workflows (`AutoUpgrade` in `dbos.Config`, or `dbos.WithAutoUpgrade(true)` at registration) require DBOS Enterprise for Go, at the same minor version as the core module (`go get go.dbos.dev/[email protected]`), with a blank import anywhere in the program; otherwise `dbos.NewContext` (or `dbos.Launch`, for a workflow enrolled with `WithAutoUpgrade`) fails with an initialization error:

```go
import _ "go.dbos.dev/dbos-enterprise-go"
```

### 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.NewContext(context.Background(), dbos.Config{
		AppName:            "my-app",
		ApplicationVersion: "0.1.0",
		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)
	}
}
```

When creating a new application, set `ApplicationVersion` to `"0.1.0"`. If omitted, DBOS derives an opaque hash from the binary. When editing an existing application, leave its configured version alone — changing it is a deployment decision (see `references/advanced-application-versions.md`).

`DatabaseURL` accepts Postgres/CockroachDB URLs or SQLite URLs (`sqlite:/path/to.db`, `sqlite::memory:`; SQLite requires a blank import of `github.com/dbos-inc/dbos-transact-golang/dbos/driver/sqlite`). See `references/lifecycle-config.md` for all configuration options, including Conductor settings and running schema migrations separately from the application.

`dbos.Context` extends `dbos.Client`: management functions (`Enqueue`, `ListWorkflows`, `CancelWorkflow`, queue and schedule management, ...) take a `dbos.Client` and accept either a `Context` or a standalone client from `dbos.NewClient` (see `references/client-setup.md`).

`AppName` identifies the application and owns everything it creates. Multiple applications (in any language) can share one system database, isolated by application name (v1.2.0+, see `references/advanced-shared-database.md`).

### 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.Context, input string) (string, error) {
	result, err := dbos.RunAsStep(ctx, fetchData, dbos.WithStepName("fetchData"))
	if err != nil {
		return "", err
	}
	return result, nil
}
```

Database writes that must happen exactly once belong in a datasource transaction (`dbos.RunAsTransaction`), not a step (see `references/step-transactions.md`).

### Key Constraints

- Do NOT start or enqueue workflows from within steps
- Do NOT call `dbos.RunAsTransaction`, `handle.GetResult`, or `dbos.CloseStream` from within steps (reads, `dbos.SetEvent`, and `dbos.WriteStream` are allowed)
- 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 MUST be registered, and all datasources created with `dbos.NewDataSource`, before calling `Launch()`; queues are registered with `dbos.RegisterQueue` and persisted in the database
- Starting a workflow with an ID already in use returns the existing workflow by default; pass `dbos.WithWorkflowIDReusePolicy(dbos.WorkflowIDReusePolicyReject)` to get `dbos.ErrWorkflowIDInUse` instead (see `references/pattern-idempotency.md`)
- A panic in a workflow does not crash the process: DBOS records it as the workflow's error (`dbos.ErrWorkflowPanic`)
- Do NOT set `EnablePatching` (deprecated in v1.8.0): `dbos.Patch` and `dbos.DeprecatePatch` work without it. To let patched code recover older workflows, pin `ApplicationVersion` or use auto-upgrade (see `references/advanced-patching.md`)

## How to Use

Read individual rule files for detailed explanations and examples:

```
references/lifecycle-config.md
references/workflow-determinism.md
references/step-transactions.md
references/queue-concurrency.md
references/workflow-control.md
```

## References

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

© dbos · MIT · dbos-inc/agent-skills

Similar skills

All skills for Backend and APIs →

From the same set3

Project sponsors

Companies that keep this analytics open