Skip to main content

DBOS Context

A DBOS Context is at the center of a DBOS-enabled application. Use it to register workflows, queues and perform workflow management tasks.

DBOSContext extends Go's context.Context interface and carries essential state across workflow execution. Workflows and steps receive a new DBOSContext spun out of the root DBOSContext you manage. In addition, a DBOSContext can be used to set workflow timeouts.

Lifecycle​

Initialization​

You can create a DBOS context using NewDBOSContext, which takes a Config object where AppName and one of DatabaseURL or SystemDBPool are mandatory.

func NewDBOSContext(ctx context.Context, inputConfig Config) (DBOSContext, error)
type Config struct {
    AppName            string        // Application name for identification (required)
    DatabaseURL        string        // DatabaseURL is a PostgreSQL connection string to your system database. Either this or SystemDBPool is required.
    SystemDBPool       *pgxpool.Pool // SystemDBPool is a connection pool DBOS can use to access your system database. Optional but takes precedence over DatabaseURL if both are provided.
    DatabaseSchema     string        // Database schema name (defaults to "dbos")
    Logger             *slog.Logger  // Custom logger instance (defaults to a new slog logger)
    AdminServer        bool          // Enable Transact admin HTTP server (disabled by default)
    AdminServerPort    int           // Port for the admin HTTP server (default: 3001)
    ConductorURL       string        // DBOS conductor service URL (optional)
    ConductorAPIKey    string        // DBOS conductor API key (optional)
    ApplicationVersion string        // Application version (optional)
    ExecutorID         string        // Executor ID (optional)
}

For example:

dbosContext, err := dbos.NewDBOSContext(context.Background(), dbos.Config{
    AppName:     "dbos-starter",
    DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
})
if err != nil {
    panic(err)
}

The newly created DBOSContext must be launched with Launch() before use and should be shut down with Shutdown() at program termination.

launch​

dbos.Launch(ctx DBOSContext) error

Launch the following resources managed by a DBOSContext:

In addition, Launch() may perform workflow recovery. Launch() should be called by your program during startup before running any workflows.

Shutdown​

dbos.Shutdown(ctx DBOSContext, timeout time.Duration)

Gracefully shutdown the DBOS runtime, waiting for workflows to complete and cleaning up resources. When you shutdown a DBOSContext, the underlying context.Context will be cancelled, which signals all DBOS resources they should stop executing, including workflows and steps.

Parameters:

  • timeout: The time to wait for DBOS resources to gracefully terminate.

Context management​

WithTimeout​

func WithTimeout(ctx DBOSContext, timeout time.Duration) (DBOSContext, context.CancelFunc)

WithTimeout returns a copy of the DBOS context with a timeout. The returned context will be canceled after the specified duration. See workflow timeouts for usage.

WithoutCancel​

func WithoutCancel(ctx DBOSContext) DBOSContext

WithoutCancel returns a copy of the DBOS context that is not canceled when the parent context is canceled. This is useful to detach child workflows from their parent's timeout.

Context metadata​

GetApplicationVersion​

func GetApplicationVersion() string

GetApplicationVersion returns the application version for this context.

GetExecutorID​

func GetExecutorID() string

GetExecutorID returns the executor ID for this context.