antigravity-skills-reference/skills/dbos-golang/references/client-setup.md

title, impact, impactDescription, tags

title	impact	impactDescription	tags
Initialize Client for External Access	HIGH	Enables external applications to interact with DBOS workflows	client, external, setup, initialization

Initialize Client for External Access

Use dbos.NewClient to interact with DBOS from external applications like API servers, CLI tools, or separate services. The Client connects directly to the DBOS system database.

Incorrect (using full DBOS context from an external app):

// Full DBOS context requires Launch() - too heavy for external clients
ctx, _ := dbos.NewDBOSContext(context.Background(), config)
dbos.Launch(ctx)

Correct (using Client):

client, err := dbos.NewClient(context.Background(), dbos.ClientConfig{
	DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
})
if err != nil {
	log.Fatal(err)
}
defer client.Shutdown(10 * time.Second)

// Send a message to a workflow
err = client.Send(workflowID, "notification", "topic")

// Get an event from a workflow
event, err := client.GetEvent(workflowID, "status", 60*time.Second)

// Retrieve a workflow handle
handle, err := client.RetrieveWorkflow(workflowID)
result, err := handle.GetResult()

// List workflows
workflows, err := client.ListWorkflows(
	dbos.WithStatus([]dbos.WorkflowStatusType{dbos.WorkflowStatusError}),
)

// Workflow management
err = client.CancelWorkflow(workflowID)
handle, err = client.ResumeWorkflow(workflowID)

// Read a stream
values, closed, err := client.ClientReadStream(workflowID, "results")

// Read a stream asynchronously
ch, err := client.ClientReadStreamAsync(workflowID, "results")

ClientConfig options:

• DatabaseURL (required unless SystemDBPool is set): PostgreSQL connection string
• SystemDBPool: Custom *pgxpool.Pool
• DatabaseSchema: Schema name (default: "dbos")
• Logger: Custom *slog.Logger

Always call client.Shutdown() when done.

Reference: DBOS Client