Spring Boot Starter

The transact-spring-boot-starter provides Spring Boot auto-configuration for DBOS Transact.

Auto-Configured Beans​

All beans are @ConditionalOnMissingBean — declare your own to replace any of them.

Configuration Properties​

All properties are in the dbos.* namespace.

Application​

Datasource​

DBOS Conductor​

Admin Server​

Other​

DBOSConfigCustomizer​

@FunctionalInterface
public interface DBOSConfigCustomizer {
    DBOSConfig customize(DBOSConfig config);
}

Declare one or more DBOSConfigCustomizer beans to modify the auto-configured DBOSConfig without replacing it. Customizers run in @Order / Ordered sequence after the base config is assembled from dbos.* properties.

@Bean
@Order(1)
public DBOSConfigCustomizer myCustomizer() {
    return config -> config.withAdminServer(true).withAdminServerPort(8081);
}

DBOSWorkflowRegistrar​

Implements SmartInitializingSingleton. After all singletons are created, it scans every bean for methods annotated with @Workflow or @Step. Beans containing @Workflow methods are registered with DBOS for durable execution and recovery. @Step methods are not registered directly — they are intercepted at runtime by DBOSAspect.

Requirements:

• Beans with @Workflow or @Step methods must be singletons. Prototype-scoped beans throw IllegalStateException.
• DBOS registers the raw (unwrapped) bean target. Calls made via this inside a workflow body bypass the Spring proxy and are not intercepted by DBOSAspect. Use a self-injected proxy instead (see Spring Boot Integration tutorial)

Multiple beans of the same class:

@TransactionalStep​

Module: dev.dbos:transact-spring-txstep-starter (separate from transact-spring-boot-starter). Package: dev.dbos.transact.spring.txstep.

public @interface TransactionalStep {
  String name() default "";
}

Marks a Spring-managed method as a step factory step.

The behaviour depends on calling context:

The annotated method must be called through a Spring proxy — calls via this bypass the aspect.

Parameters:

• name: Stable name for this step within the workflow. Defaults to the method name.

Supported stacks: Spring JDBC / JdbcTemplate, JDBI (jdbi3-spring), jOOQ (spring-boot-starter-jooq), JPA / Hibernate.

Installation​

implementation("dev.dbos:transact-spring-boot-starter:<version>")
implementation("dev.dbos:transact-spring-txstep-starter:<version>")

<dependency>
  <groupId>dev.dbos</groupId>
  <artifactId>transact-spring-boot-starter</artifactId>
  <version>VERSION</version>
</dependency>
<dependency>
  <groupId>dev.dbos</groupId>
  <artifactId>transact-spring-txstep-starter</artifactId>
  <version>VERSION</version>
</dependency>

Auto-Configured Beans​

All beans are @ConditionalOnMissingBean.

Configuration​

How it works​

1. TransactionalStepAspect intercepts every @TransactionalStep call and delegates to TransactionalStepFactory.
2. The factory calls DBOS.runStep(), which checks tx_step_outputs for a prior result. If one exists, it is returned immediately (idempotent replay).
3. Otherwise, a REQUIRES_NEW Spring transaction is started. The method body runs, and the result is written to tx_step_outputs using DataSourceUtils.getConnection() — the same connection the transaction holds.
4. The transaction commits, making the user's write and the step output record atomic. If the method throws, the transaction rolls back and the error is recorded separately so retries can replay it.

See the Step Factory tutorial for per-stack examples (JDBC, JDBI, jOOQ, JPA).

DBOSAspect​

An @Aspect that intercepts:

• @Workflow methods — routes the call through dbos.integration().runWorkflow(...) for durable execution and recovery.
• @Step methods — delegates to dbos.runStep(...) when called inside a workflow context; executes directly otherwise.

Spring AOP intercepts only calls that go through the Spring proxy. this.someStep() calls inside a workflow body are not intercepted. Inject a self-reference to ensure step calls are durable:

@Service
public class MyService {
    @Autowired MyService self;

    @Workflow
    public String myWorkflow() {
        return self.myStep();  // intercepted — durable
        // this.myStep();      // NOT intercepted — runs outside DBOS
    }

    @Step
    public String myStep() { return "result"; }
}