dbos.core

Liking cljdoc? Tell your friends :D

Clojure only.

->enqueue-options^clj

(->enqueue-options x)

Build DBOSClient$EnqueueOptions (for enqueuing via the client) from a map (or pass a pre-built DBOSClient$EnqueueOptions straight through unchanged):

:workflow-name (required),
:class-name (required - the DBOS className the worker registered under),
:queue (name) - optional here at the builder, but REQUIRED by enqueue-workflow!,
:workflow-id - The id for the workflow instance,
:timeout (Duration),
:deduplication-id (optional) - ID used to deduplicate the workflow. Separate than :workflow-id,
:priority (int, lower runs first),
:delay (Duration),
:app-version (String) - pin the workflow to a specific application version,
:deadline (Instant),
:queue-partition-key (String).

The (:workflow-name, :class-name) pair typically comes from workflow-identity, so enqueue targets the exact (workflowName, className) the worker registered under.

Build DBOSClient$EnqueueOptions (for enqueuing via the client) from a map (or
pass a pre-built DBOSClient$EnqueueOptions straight through unchanged):
- `:workflow-name` (required),
- `:class-name` (required - the DBOS className the worker registered under),
- `:queue` (name) - optional here at the builder, but REQUIRED by
  `enqueue-workflow!`,
- `:workflow-id` - The id for the workflow instance,
- `:timeout` (Duration),
- `:deduplication-id` (optional) - ID used to deduplicate the workflow. Separate than `:workflow-id`,
- `:priority` (int, lower runs first),
- `:delay` (Duration),
- `:app-version` (String) - pin the workflow to a specific application version,
- `:deadline` (Instant),
- `:queue-partition-key` (String).

The (:workflow-name, :class-name) pair typically comes from
`workflow-identity`, so enqueue targets the exact (workflowName, className)
the worker registered under.

source raw docstring

->start-options^clj

(->start-options x)

Build StartWorkflowOptions from a map (or pass a pre-built StartWorkflowOptions straight through unchanged):

:workflow-id - The id for the workflow instance,
:queue (name, optional),
:timeout (Duration),
:deduplication-id (optional) - ID used to deduplicate the workflow. Separate than :workflow-id,
:priority (int, lower runs first),
:delay (Duration),
:app-version (String) - pin the workflow to a specific application version,
:deadline (Instant),
:queue-partition-key (String).

Build StartWorkflowOptions from a map (or pass a pre-built
StartWorkflowOptions straight through unchanged):
- `:workflow-id` - The id for the workflow instance,
- `:queue` (name, optional),
- `:timeout` (Duration),
- `:deduplication-id` (optional) - ID used to deduplicate the workflow. Separate than `:workflow-id`,
- `:priority` (int, lower runs first),
- `:delay` (Duration),
- `:app-version` (String) - pin the workflow to a specific application version,
- `:deadline` (Instant),
- `:queue-partition-key` (String).

source raw docstring

->step-options^clj

(->step-options x)

Build a StepOptions from a step-name string, an options map, or a pre-built StepOptions (passed through). Map keys: :name (required), :max-attempts, :retry-interval (Duration), :backoff-rate (double), :retry? (predicate fn of Throwable -> boolean).

Build a StepOptions from a step-name string, an options map, or a pre-built
StepOptions (passed through). Map keys: :name (required), :max-attempts,
:retry-interval (Duration), :backoff-rate (double), :retry? (predicate fn of
Throwable -> boolean).

source raw docstring

->workflow-opts^clj

(->workflow-opts id-or-opts)

Normalize the id-or-opts arg accepted by start-workflow! / enqueue-workflow! into the internal options map the builders take. Accepts:

a bare workflow-id string,
a pre-built StartWorkflowOptions or DBOSClient$EnqueueOptions (returned wrapped as {:dbos.core/built <obj>} so callers can forward it verbatim), or
a map keyed with :workflow/id, :workflow/queue (name string or Queue instance), :workflow/timeout, :workflow/deduplication-id, :workflow/priority, :workflow/delay, :workflow/app-version (a String or the keyword sentinel :latest, passed through unresolved), :workflow/deadline (Instant), :workflow/queue-partition-key.

Blank string values become nil (absent) rather than reaching the option record ctors, which throw on empty strings.

A pre-built options object is forwarded VERBATIM: :workflow/app-version :latest resolution and the blank-string guards do NOT apply to it — bake in withAppVersion yourself. Omitting the id (nil or {}) autogenerates a random UUID (loses idempotent de-dup).

Normalize the id-or-opts arg accepted by `start-workflow!` /
`enqueue-workflow!` into the internal options map the builders take. Accepts:
- a bare workflow-id string,
- a pre-built StartWorkflowOptions or DBOSClient$EnqueueOptions (returned
  wrapped as `{:dbos.core/built <obj>}` so callers can forward it verbatim), or
- a map keyed with :workflow/id, :workflow/queue (name string or Queue
  instance), :workflow/timeout, :workflow/deduplication-id,
  :workflow/priority, :workflow/delay, :workflow/app-version (a String or the
  keyword sentinel :latest, passed through unresolved), :workflow/deadline
  (Instant), :workflow/queue-partition-key.

Blank string values become nil (absent) rather than reaching the option
record ctors, which throw on empty strings.

A pre-built options object is forwarded VERBATIM: :workflow/app-version
:latest resolution and the blank-string guards do NOT apply to it — bake in
`withAppVersion` yourself. Omitting the id (nil or {}) autogenerates a random
UUID (loses idempotent de-dup).

source raw docstring

add-derefable^clj

(add-derefable handle)

Wrap a WorkflowHandle so @handle blocks and returns the (deserialized) result.

Wrap a WorkflowHandle so @handle blocks and returns the (deserialized)
result.

source raw docstring

apply-schedules!^clj

(apply-schedules! dbos definitions)

Install a WorkflowSchedule for every definition carrying a :workflow/schedule. Call AFTER launch; no-op when none are scheduled. With a queue (:queue in the schedule) run it only on executor(s) listening on that queue; without one the schedule fires on the registering executor.

Install a WorkflowSchedule for every definition carrying a :workflow/schedule.
Call AFTER launch; no-op when none are scheduled. With a queue (:queue in the
schedule) run it only on executor(s) listening on that queue; without one the
schedule fires on the registering executor.

source raw docstring

AppVersioned^cljprotocol

App-version accessors for both a DBOS instance and a DBOSClient.

App-version accessors for both a DBOS instance and a DBOSClient.

-get-latest-app-version^clj

(-get-latest-app-version this)

-list-app-versions^clj

(-list-app-versions this)

-set-latest-app-version!^clj

(-set-latest-app-version! this version-id)

source raw docstring

cancel-workflow!^clj

(cancel-workflow! dbos-or-client workflow-id)

Cancel a workflow by id. dbos-or-client is a DBOS or a DBOSClient. Returns the id.

Cancel a workflow by id. `dbos-or-client` is a DBOS or a DBOSClient. Returns the id.

source raw docstring

create^clj

(create {:keys [config queues workflows]})

Construct the DBOS instance, register queues and workflows. Does NOT launch — the caller controls when the executor goes live via launch!.

:config a map for dbos-config (see its docstring)
:queues a seq of dev.dbos.transact.workflow.Queue to register
:workflows a seq of workflow definition maps to register

Returns the raw DBOS instance — pass it directly to launch!, start-workflow!, apply-schedules! and shutdown!.

Construct the DBOS instance, register queues and workflows. Does NOT
launch — the caller controls when the executor goes live via `launch!`.

- :config    a map for `dbos-config` (see its docstring)
- :queues    a seq of `dev.dbos.transact.workflow.Queue` to register
- :workflows a seq of workflow definition maps to register

Returns the raw DBOS instance — pass it directly to `launch!`,
`start-workflow!`, `apply-schedules!` and `shutdown!`.

source raw docstring

dbos-config^clj

(dbos-config {:keys [datasource database-url db-user db-password migrate?
                     app-name app-version executor-id serializer schema
                     listen-queues admin-server? admin-server-port
                     scheduler-polling-interval use-listen-notify?
                     enable-patching? conductor]})

Build a DBOSConfig from a plain map. :app-name plus a database source are required; everything else is optional and generalizes both consumers.

Provide the database either as a ready DataSource, or as a JDBC url that DBOS opens itself:

:datasource any javax.sql.DataSource DBOS persists to (e.g. a HikariCP pool)
:database-url a JDBC url (alternative to :datasource)
:db-user optional db user, paired with :database-url
:db-password optional db password, paired with :database-url
:migrate? optional; let DBOS create/upgrade its system schema

Everything else:

:app-name DBOS application name (required)
:serializer a DBOSSerializer; defaults to the transit serializer with no injected handlers (see dbos.serializer). Pass one built with your app-wide transit handlers for java.time fidelity.
:app-version optional app version string
:executor-id optional executor id (defaults to DBOS's own)
:schema optional database schema name
:listen-queues optional seq of queue names this executor listens to

Admin HTTP server (independent knobs, mirroring DBOS's own config):

:admin-server? optional; enable the DBOS admin HTTP server
:admin-server-port optional int; the admin server port (only applies when the admin server is enabled; DBOS defaults it otherwise)

Other runtime knobs (all optional):

:scheduler-polling-interval a java.time.Duration for how often the scheduler polls for due scheduled workflows
:use-listen-notify? boolean; use Postgres LISTEN/NOTIFY for queue wakeups (DBOS enables this by default)
:enable-patching? boolean; toggle DBOS workflow patching support
:conductor optional {:domain .. :api-key .. :executor-metadata {..}} for DBOS Conductor

Build a DBOSConfig from a plain map. :app-name plus a database source are
required; everything else is optional and generalizes both consumers.

Provide the database either as a ready DataSource, or as a JDBC url that
DBOS opens itself:

- :datasource     any `javax.sql.DataSource` DBOS persists to (e.g. a
                  HikariCP pool)
- :database-url   a JDBC url (alternative to :datasource)
- :db-user        optional db user, paired with :database-url
- :db-password    optional db password, paired with :database-url
- :migrate?       optional; let DBOS create/upgrade its system schema

Everything else:
- :app-name       DBOS application name (required)
- :serializer     a DBOSSerializer; defaults to the transit serializer with
                  no injected handlers (see dbos.serializer). Pass one built
                  with your app-wide transit handlers for java.time fidelity.
- :app-version    optional app version string
- :executor-id    optional executor id (defaults to DBOS's own)
- :schema         optional database schema name
- :listen-queues  optional seq of queue names this executor listens to

Admin HTTP server (independent knobs, mirroring DBOS's own config):
- :admin-server?      optional; enable the DBOS admin HTTP server
- :admin-server-port  optional int; the admin server port (only applies when
                      the admin server is enabled; DBOS defaults it otherwise)

Other runtime knobs (all optional):
- :scheduler-polling-interval  a `java.time.Duration` for how often the
                               scheduler polls for due scheduled workflows
- :use-listen-notify?          boolean; use Postgres LISTEN/NOTIFY for queue
                               wakeups (DBOS enables this by default)
- :enable-patching?            boolean; toggle DBOS workflow patching support
- :conductor                   optional {:domain .. :api-key ..
                               :executor-metadata {..}} for DBOS Conductor

source raw docstring

do-step!^cljmacro

(do-step! dbos step & body)

Run a workflow step for SIDE-EFFECTS only; result NOT persisted. step is a name string, or an options map for retries (see ->step-options), or a pre-built StepOptions.

Run a workflow step for SIDE-EFFECTS only; result NOT persisted.
`step` is a name string, or an options map for retries (see `->step-options`),
or a pre-built StepOptions.

source raw docstring

execute-do-step!^clj

(execute-do-step! dbos step thunk)

Run a side-effect-only step via DBOS (result NOT persisted). Redef seam for tests.

Run a side-effect-only step via DBOS (result NOT persisted). Redef seam for tests.

source raw docstring

execute-step^clj

(execute-step dbos step thunk)

Run a value-returning step via DBOS (result persisted). Redef seam for tests.

Run a value-returning step via DBOS (result persisted). Redef seam for tests.

source raw docstring

get-event^clj

(get-event dbos-or-client workflow-id event-key)

Read the latest value under event-key for workflow-id, or nil. Call from OUTSIDE a workflow; non-blocking. dbos-or-client is a DBOS or a DBOSClient.

Read the latest value under `event-key` for `workflow-id`, or nil. Call from
OUTSIDE a workflow; non-blocking. `dbos-or-client` is a DBOS or a DBOSClient.

source raw docstring

get-latest-app-version^clj

(get-latest-app-version dbos-or-client)

Latest application version as a map (or nil). dbos-or-client is a DBOS or a DBOSClient.

Latest application version as a map (or nil). `dbos-or-client` is a DBOS or a
DBOSClient.

source raw docstring

launch!^clj

(launch! dbos)

Launch the DBOS executor. Call after workflows are registered on the instance.

Launch the DBOS executor. Call after workflows are registered on the instance.

source raw docstring

list-app-versions^clj

(list-app-versions dbos-or-client)

Vector of known application-version maps. dbos-or-client is a DBOS or a DBOSClient.

Vector of known application-version maps. `dbos-or-client` is a DBOS or a
DBOSClient.

source raw docstring

register-workflow!^clj

(register-workflow! instance
                    {wf-key :workflow/key
                     wf-fn :workflow/fn
                     schedule :workflow/schedule
                     max-recovery-attempts :workflow/max-recovery-attempts
                     :as workflow})

Register a Clojure fn as a named DBOS workflow (before launch). Returns the definition with :workflow/registered attached.

Register a Clojure fn as a named DBOS workflow (before launch). Returns the
definition with :workflow/registered attached.

source raw docstring

register-workflows!^clj

(register-workflows! instance workflows)

Register all definitions (before launch), returning a
:workflow/key -> definition registry.

source raw docstring

resolve-app-version^clj

(resolve-app-version dbos-or-client v)

source

resume-workflow!^clj

(resume-workflow! dbos-or-client workflow-id)

Resume a previously-cancelled/paused workflow by id, returning a deref-able WorkflowHandle. dbos-or-client is a DBOS or a DBOSClient.

Resume a previously-cancelled/paused workflow by id, returning a deref-able
WorkflowHandle. `dbos-or-client` is a DBOS or a DBOSClient.

source raw docstring

run-step^cljmacro

(run-step dbos step & body)

Run a workflow step that RETURNS a value (persisted for durable replay). step is a name string, or an options map for retries (see ->step-options), or a pre-built StepOptions.

Run a workflow step that RETURNS a value (persisted for durable replay).
`step` is a name string, or an options map for retries (see `->step-options`),
or a pre-built StepOptions.

source raw docstring

scheduled-workflow-target^clj

(scheduled-workflow-target instance wf-fn)

source

set-event!^clj

(set-event! dbos event-key value)

Publish value under event-key on the running workflow (generic key/value channel). Body-only. Last write wins; durable and idempotent under replay.

Publish `value` under `event-key` on the running workflow (generic key/value
channel). Body-only. Last write wins; durable and idempotent under replay.

source raw docstring

set-latest-app-version!^clj

(set-latest-app-version! dbos-or-client version-id)

Pin version-id as the latest application version, returning it. Overrides DBOS's normal version pinning.

Pin `version-id` as the latest application version, returning it. Overrides
DBOS's normal version pinning.

source raw docstring

shutdown!^clj

(shutdown! dbos)

Shut down the DBOS executor, draining in-flight workflows.

Shut down the DBOS executor, draining in-flight workflows.

source raw docstring

start-workflow!^clj

(start-workflow! dbos wf-key id-or-opts input)

Start a registered workflow, returning a deref-able WorkflowHandle (@handle blocks for the result).

Called from INSIDE another workflow's body it starts a child (parent linkage is recorded by DBOS via ambient context); do so on the workflow thread in deterministic order (mapv, never pmap/future) — replay depends on it.

dbos the DBOS instance returned by create
wf-key keyword the workflow was registered under
id-or-opts a workflow-id string, an options map (see ->workflow-opts), or a pre-built StartWorkflowOptions — pass a stable id for idempotent starts. Omitting the id (pass nil or {}) autogenerates a random UUID: no idempotent de-dup, but the id is still readable via (workflow-id) in the body or off the handle.
input the single serializable workflow argument

The workflow id is available inside the body via (workflow-id) and on the returned handle — it is NOT injected into input.

Start a registered workflow, returning a deref-able WorkflowHandle
(@handle blocks for the result).

Called from INSIDE another workflow's body it starts a child (parent linkage
is recorded by DBOS via ambient context); do so on the workflow thread in
deterministic order (mapv, never pmap/future) — replay depends on it.

- `dbos`       the DBOS instance returned by `create`
- `wf-key`     keyword the workflow was registered under
- `id-or-opts` a workflow-id string, an options map (see `->workflow-opts`),
               or a pre-built StartWorkflowOptions — pass a stable id for
               idempotent starts. Omitting the id (pass `nil` or `{}`)
               autogenerates a random UUID: no idempotent de-dup, but the id
               is still readable via `(workflow-id)` in the body or off the
               handle.
- `input`      the single serializable workflow argument

The workflow id is available inside the body via `(workflow-id)` and on the
returned handle — it is NOT injected into `input`.

source raw docstring

validate-workflow!^clj

(validate-workflow! definition)

Throws ex-info with the collected errors when definition is invalid; returns it unchanged when valid.

Throws ex-info with the collected errors when `definition` is invalid;
returns it unchanged when valid.

source raw docstring

version-info->map^clj

(version-info->map vi)

source

workflow-definition-errors^clj

(workflow-definition-errors {wf-key :workflow/key
                             wf-fn :workflow/fn
                             max-attempts :workflow/max-recovery-attempts
                             schedule :workflow/schedule
                             :as definition})

Return a vector of human-readable problems with a workflow definition, or nil when it's valid. Pure Clojure — no schema library.

A workflow definition is a map:

:workflow/key namespaced keyword (required)
:workflow/fn fn of [dbos input] (required)
:workflow/max-recovery-attempts optional integer
:workflow/schedule optional {:cron string} with an optional :queue string

Return a vector of human-readable problems with a workflow definition,
or nil when it's valid. Pure Clojure — no schema library.

A workflow definition is a map:
- :workflow/key                  namespaced keyword (required)
- :workflow/fn                   fn of [dbos input] (required)
- :workflow/max-recovery-attempts optional integer
- :workflow/schedule             optional {:cron string} with an optional
                                 :queue string

source raw docstring

workflow-id^clj

(workflow-id)

Id of the currently executing workflow (ambient thread-local); nil outside a workflow body.

Id of the currently executing workflow (ambient thread-local); nil outside a
workflow body.

source raw docstring

workflow-identity^clj

(workflow-identity wf-key)

Split a workflow keyword into {:wf-name <name> :class-name <namespace>} — the (workflowName, className) DBOS registers and looks up by. Shared by registration and lookup so the two can't drift.

Split a workflow keyword into {:wf-name <name> :class-name <namespace>} — the
(workflowName, className) DBOS registers and looks up by. Shared by
registration and lookup so the two can't drift.

source raw docstring

workflow-sleep^clj

(workflow-sleep dbos duration)

Durably sleep the current workflow — the wake-up time is persisted, not the thread, so it survives restarts.

Durably sleep the current workflow — the wake-up time is persisted, not the
thread, so it survives restarts.

source raw docstring

WorkflowControl^cljprotocol

cancel/resume, satisfied by both DBOS and DBOSClient.

cancel/resume, satisfied by both DBOS and DBOSClient.

-cancel-workflow!^clj

(-cancel-workflow! this workflow-id)

-resume-workflow!^clj

(-resume-workflow! this workflow-id)

source raw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts

`Ctrl`+`k`	Jump to recent docs
`←`	Move to previous article
`→`	Move to next article
`Ctrl`+`/`	Jump to the search field

Raise an issue Browse cljdoc source Chat on Slack

× close

dbos.core

->enqueue-optionsclj

->start-optionsclj

->step-optionsclj

->workflow-optsclj

add-derefableclj

apply-schedules!clj

AppVersionedcljprotocol

-get-latest-app-versionclj

-list-app-versionsclj

-set-latest-app-version!clj

cancel-workflow!clj

createclj

dbos-configclj

do-step!cljmacro

execute-do-step!clj

execute-stepclj

get-eventclj

get-latest-app-versionclj

launch!clj

list-app-versionsclj

register-workflow!clj

register-workflows!clj

resolve-app-versionclj

resume-workflow!clj

run-stepcljmacro

scheduled-workflow-targetclj

set-event!clj

set-latest-app-version!clj

shutdown!clj

start-workflow!clj

validate-workflow!clj

version-info->mapclj

workflow-definition-errorsclj

workflow-idclj

workflow-identityclj

workflow-sleepclj

WorkflowControlcljprotocol

-cancel-workflow!clj

-resume-workflow!clj

->enqueue-options^clj

->start-options^clj

->step-options^clj

->workflow-opts^clj

add-derefable^clj

apply-schedules!^clj

AppVersioned^cljprotocol

-get-latest-app-version^clj

-list-app-versions^clj

-set-latest-app-version!^clj

cancel-workflow!^clj

create^clj

dbos-config^clj

do-step!^cljmacro

execute-do-step!^clj

execute-step^clj

get-event^clj

get-latest-app-version^clj

launch!^clj

list-app-versions^clj

register-workflow!^clj

register-workflows!^clj

resolve-app-version^clj

resume-workflow!^clj

run-step^cljmacro

scheduled-workflow-target^clj

set-event!^clj

set-latest-app-version!^clj

shutdown!^clj

start-workflow!^clj

validate-workflow!^clj

version-info->map^clj

workflow-definition-errors^clj

workflow-id^clj

workflow-identity^clj

workflow-sleep^clj

WorkflowControl^cljprotocol

-cancel-workflow!^clj

-resume-workflow!^clj