Skip to main content

DBOS Lifecycle

The DBOS class is a singleton—it must be configured and launched exactly once in a program's lifetime, before running any DBOS workflows. Here, we document its lifecycle. Other methods and variables are documented here.

DBOS.setConfig​

DBOS.setConfig(
    config: DBOSConfig
)

Configure DBOS. Configuration is documented here.

Parameters:

DBOS.launch​

DBOS.launch(
    options?: DBOSLaunchOptions
): Promise<void>
interface DBOSLaunchOptions {
  conductorKey?: string;
  conductorURL?: string;
  conductorExecutorMetadata?: Record<string, unknown>;
}

Launch DBOS, initializing database connections and starting queues and scheduled workflows. Should be called after all workflows and steps are registered. You should not call a DBOS function until after DBOS is launched.

For example, here is one way to launch DBOS in an app:

async function main() {
  // Configure DBOS
  DBOS.setConfig({
    "name": "dbos-node-toolbox",
    "systemDatabaseUrl": process.env.DBOS_SYSTEM_DATABASE_URL,
  });
  // Launch DBOS
  await DBOS.launch();
}

main().catch(console.log);

Parameters:

  • conductorKey: An API key for DBOS Conductor. If provided, application connects to Conductor. API keys can be created from the DBOS console.
  • conductorURL: The URL of the Conductor service to connect to. Only set if you are self-hosting Conductor.
  • conductorExecutorMetadata: A JSON-serializable dictionary of metadata to associate with this executor. This metadata is sent to Conductor and displayed on the dashboard, making it easier to identify executors (e.g., by region, instance type, or deployment environment).

DBOS.shutdown​

DBOS.shutdown(
  options?: { deregister?: boolean }
): Promise<void>

Shut down DBOS, terminating all active workflows and closing database disconnections.

In a test environment, after this completes DBOS can be re-configured and launch() can be called again. If options.deregister is set, all current function, queue, instance, data source, event receiver, and any other registrations will be cleared, allowing a full set of replacement registrations to be made prior to the next launch().

DBOS.logRegisteredEndpoints​

DBOS.logRegisteredEndpoints(): void

Logs all DBOS functions that are bound to endpoints, including scheduled workflows, kafka consumers, and any other library event receivers. This can be a useful diagnostic to call at DBOS launch.