DBOS Transact for Java

DBOS queues allow you to durably run distributed tasks using Postgres as the backend (no separate broker required). You can enqueue tasks from a durable workflow, and DBOS guarantees task completion and result retrieval even if the application is interrupted.

Key features include:

• Flow control (concurrency limits per queue or process)
• Task timeouts
• Rate limiting
• Task deduplication
• Task prioritization

To use queues, you must first register the queue in your main application and then use StartWorkflowOptions to associate a workflow with that queue.

// In your main
var queue = new Queue("exampleQueue");
DBOS.registerQueue(queue);

// Enqueuing a task
public void queuedTasks() {
    for (int i = 0; i < 3; i++) {
        String workflowId = "child" + i;
        var options = new StartWorkflowOptions(workflowId).withQueue(q);
        List<WorkflowHandle<String>> handles = new ArrayList<>();
        handles.add(DBOS.startWorkflow(()->simpleService.childWorkflow(workflowId), options));
    }

    for (int i = 0 ; i < 3 ; i++) {
        String workflowId = "child"+i;
        var h = DBOS.retrieveWorkflow(workflowId);
        System.out.println(h.getResult());
    }
}

The @TransactionalStep annotation marks a Spring-managed method as an idempotent transactional step within a DBOS workflow.

Key behaviors:

• Each annotated method runs in a REQUIRES_NEW Spring transaction.
• The method's return value is written to a tx_step_outputs table atomically with the database work performed inside the method.
• On workflow retry, DBOS checks the tx_step_outputs table; if a result exists, it is replayed without re-executing the method body.

Requirement: The annotated method must be called through a Spring proxy. You should inject the bean containing the @TransactionalStep method into a @Workflow-annotated method in a different Spring bean.

@Service
public class OrderStepService {
    @Autowired JdbcTemplate jdbc;

    @TransactionalStep
    public Order saveOrder(Order order) {
        jdbc.update("INSERT INTO orders(id, item, qty) VALUES (?, ?, ?)",
            order.id(), order.item(), order.qty());
        return order;
    }
}

@Service
public class OrderWorkflowService {
    @Autowired OrderStepService steps;

    @Workflow
    public Order processOrder(Order order) {
        return steps.saveOrder(order);
    }
}

DBOS provides lightweight durable workflows built on top of Postgres. It allows you to write long-lived, reliable code that can survive crashes, restarts, and failures without losing state or duplicating work.

As workflows run, DBOS checkpoints each step in a Postgres database. If a process stops (due to failure, intentional suspension, or machine death), the program can recover from these checkpoints to restore its exact state and continue from where it left off. This is achieved by registering ordinary functions as workflows and steps using the @Workflow annotation and DBOS.runStep() method.

interface Example {
    public void workflow();
}

class ExampleImpl implements Example {

    private void stepOne() {
        System.out.println("Step one completed!");
    }

    private void stepTwo() {
        System.out.println("Step two completed!");
    }

    @Workflow
    public void workflow() {
        DBOS.runStep(() -> stepOne(), "stepOne");
        DBOS.runStep(() -> stepTwo(), "stepTwo");
    }
}

The transact-spring-txstep-starter integrates with common Spring data access technologies. Because it uses Spring's transaction management, these tools will automatically participate in the REQUIRES_NEW transaction started by the @TransactionalStep aspect.

Spring JDBC / JdbcTemplate

Works out-of-the-box. JdbcTemplate uses DataSourceUtils internally to join the active transaction.

JDBI

Requires jdbi3-spring so that SpringTransactionHandler reuses the active Spring transaction.

jOOQ

Add spring-boot-starter-jooq and set spring.jooq.sql-dialect=POSTGRES. The starter wraps the DataSource in a TransactionAwareDataSourceProxy so jOOQ queries execute on the transaction-bound connection.

JPA / Hibernate

Works with spring-boot-starter-data-jpa. Both Spring Data JPA repositories and direct EntityManager access (via EntityManagerFactoryUtils.getTransactionalEntityManager(emf)) are supported.

MyBatis

Works with mybatis-spring-boot-starter. MyBatis mappers participate in Spring transactions automatically via SqlSessionTemplate.

### JDBI Example
```java
@Configuration
public class JdbiConfig {
    @Bean
    public Jdbi jdbi(DataSource dataSource) throws Exception {
        var factory = new JdbiFactoryBean(dataSource);
        factory.afterPropertiesSet();
        return factory.getObject();
    }
}

@Service
public class OrderStepService {
    @Autowired Jdbi jdbi;

    @TransactionalStep
    public Order saveOrder(Order order) {
        jdbi.withHandle(h ->
            h.execute("INSERT INTO orders(id, item, qty) VALUES (?, ?, ?)",
                order.id(), order.item(), order.qty()));
        return order;
    }
}

jOOQ Example

@Service
public class OrderStepService {
    @Autowired DSLContext dsl;

    @TransactionalStep
    public Order saveOrder(Order order) {
        dsl.execute("INSERT INTO orders(id, item, qty) VALUES (?, ?, ?)",
                order.id(), order.item(), order.qty());
        return order;
    }
}

JPA Example

@Service
public class OrderStepService {
    @Autowired OrderRepository repo;

    @TransactionalStep
    public Order saveOrder(Order order) {
        return repo.save(order);
    }
}

MyBatis Example

@Mapper
public interface OrderMapper {
    @Insert("INSERT INTO orders(id, item, qty) VALUES(#{id}, #{item}, #{qty})")
    void insert(@Param("id") String id, @Param("item") String item, @Param("qty") int qty);
}

@Service
public class OrderStepService {
    @Autowired OrderMapper orderMapper;

    @TransactionalStep
    public Order saveOrder(Order order) {
        orderMapper.insert(order.id(), order.item(), order.qty());
        return order;
    }
}