dbos-java

DBOS Java Best Practices

Guide for building reliable, fault-tolerant Java applications with DBOS durable workflows.

When to Apply

Reference these guidelines when:

• Adding DBOS to existing Java or Kotlin code
• Creating workflows and steps
• Using queues for concurrency control
• Implementing workflow communication (events, messages, streams)
• Configuring and launching DBOS applications, including with Spring Boot
• Using DBOSClient from external applications
• Testing DBOS applications

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Lifecycle	CRITICAL	lifecycle-
2	Workflow	CRITICAL	workflow-
3	Step	HIGH	step-
4	Queue	HIGH	queue-
5	Communication	MEDIUM	comm-
6	Pattern	MEDIUM	pattern-
7	Testing	LOW-MEDIUM	test-
8	Client	MEDIUM	client-
9	Advanced	LOW	advanced-

Critical Rules

Installation

Add the DBOS dependency (Java 17+, Gradle 8+ recommended):

dependencies {
    implementation("dev.dbos:transact:1.0.0")
    implementation("org.slf4j:slf4j-simple:2.0.17") // to see DBOS log messages
}

DBOS requires a PostgreSQL-compatible database. Connection settings are typically supplied through DBOS_SYSTEM_JDBC_URL, PGUSER, and PGPASSWORD.

DBOS Configuration and Launch

A DBOS application MUST create a DBOS instance, register its workflow classes, then launch:

import dev.dbos.transact.DBOS;
import dev.dbos.transact.config.DBOSConfig;
import dev.dbos.transact.workflow.Workflow;

interface Example {
  String workflow(String input);
}

class ExampleImpl implements Example {
  private final DBOS dbos;

  ExampleImpl(DBOS dbos) {
    this.dbos = dbos;
  }

  @Override
  @Workflow
  public String workflow(String input) {
    return dbos.runStep(() -> fetchData(input), "fetchData");
  }

  private String fetchData(String input) { /* external call */ return input; }
}

public class App {
  public static void main(String[] args) {
    DBOSConfig config = DBOSConfig.defaultsFromEnv("my-app")
        .withAppVersion("0.1.0");
    DBOS dbos = new DBOS(config);

    Example proxy = dbos.registerProxy(Example.class, new ExampleImpl(dbos));

    dbos.launch();

    proxy.workflow("input"); // durable: called through the proxy
  }
}