diff --git a/transact-spring-boot-starter/src/main/java/dev/dbos/transact/spring/DBOSAutoConfiguration.java b/transact-spring-boot-starter/src/main/java/dev/dbos/transact/spring/DBOSAutoConfiguration.java
index 935b516c..1ae1f653 100644
--- a/transact-spring-boot-starter/src/main/java/dev/dbos/transact/spring/DBOSAutoConfiguration.java
+++ b/transact-spring-boot-starter/src/main/java/dev/dbos/transact/spring/DBOSAutoConfiguration.java
@@ -103,6 +103,7 @@ public DBOSWorkflowRegistrar dbosWorkflowRegistrar(
return new DBOSWorkflowRegistrar(dbos, applicationContext);
}
+ @SuppressWarnings("removal")
private DBOSConfig buildConfig(DBOSProperties props, String springAppName) {
String appName =
props.getApplication().getName() != null ? props.getApplication().getName() : springAppName;
diff --git a/transact-spring-boot-starter/src/test/java/dev/dbos/transact/spring/DBOSAutoConfigurationTest.java b/transact-spring-boot-starter/src/test/java/dev/dbos/transact/spring/DBOSAutoConfigurationTest.java
index 7715ced3..0ea8cf49 100644
--- a/transact-spring-boot-starter/src/test/java/dev/dbos/transact/spring/DBOSAutoConfigurationTest.java
+++ b/transact-spring-boot-starter/src/test/java/dev/dbos/transact/spring/DBOSAutoConfigurationTest.java
@@ -66,6 +66,7 @@ void dbosConfigReflectsDatasourceProperties() {
}
@Test
+ @SuppressWarnings("removal")
void dbosConfigReflectsOptionalProperties() {
runner
.withPropertyValues(
diff --git a/transact/src/main/java/dev/dbos/transact/config/DBOSConfig.java b/transact/src/main/java/dev/dbos/transact/config/DBOSConfig.java
index 97f5200f..ea60715b 100644
--- a/transact/src/main/java/dev/dbos/transact/config/DBOSConfig.java
+++ b/transact/src/main/java/dev/dbos/transact/config/DBOSConfig.java
@@ -17,6 +17,49 @@
import org.jspecify.annotations.NonNull;
import org.jspecify.annotations.Nullable;
+/**
+ * Immutable configuration for a DBOS application instance.
+ *
+ * Use {@link #defaults(String)} or {@link #defaultsFromEnv(String)} to obtain a base
+ * configuration, then chain {@code with*} methods to set individual options:
+ *
+ *
{@code
+ * DBOSConfig config = DBOSConfig.defaults("my-app")
+ * .withDatabaseUrl("jdbc:postgresql://localhost:5432/mydb")
+ * .withMigrate(true);
+ * }
+ *
+ * @param appName unique name for this application; must not be null or empty
+ * @param databaseUrl JDBC URL of the PostgreSQL database; may be {@code null} when a {@link
+ * DataSource} is provided instead
+ * @param dbUser PostgreSQL username; may be {@code null} to rely on driver defaults
+ * @param dbPassword PostgreSQL password; masked in {@link #toString()}
+ * @param dataSource pre-configured {@link DataSource} to use instead of {@code databaseUrl}, {@code
+ * dbUser}, and {@code dbPassword}
+ * @param adminServer whether to start the built-in admin HTTP server; deprecated and will be
+ * removed before 1.0 — use DBOS Conductor instead
+ * @param adminServerPort port for the built-in admin HTTP server; deprecated and will be removed
+ * before 1.0 — use DBOS Conductor instead
+ * @param migrate whether to run database migrations on startup
+ * @param conductorKey API key for DBOS Conductor; must not be empty if non-null
+ * @param conductorDomain custom hostname for DBOS Conductor; must not be empty if non-null
+ * @param conductorExecutorMetadata arbitrary key-value metadata attached to this executor's
+ * registration in Conductor
+ * @param appVersion application version string used for versioned workflow routing; must not be
+ * empty if non-null
+ * @param executorId stable identifier for this executor instance; must not be empty if non-null
+ * @param databaseSchema PostgreSQL schema used for DBOS system tables; {@code null} uses the
+ * default schema
+ * @param enablePatching whether to enable workflow patching
+ * @param listenQueues names of queues this executor should dequeue work from; an empty set means
+ * listen on all queues
+ * @param serializer custom {@link DBOSSerializer} for workflow arguments and return values; {@code
+ * null} uses the default JSON serializer
+ * @param schedulerPollingInterval how often the cron scheduler polls for due tasks; {@code null}
+ * uses the system default
+ * @param useListenNotify whether to use PostgreSQL {@code LISTEN}/{@code NOTIFY} for real-time
+ * workflow wake-ups instead of polling
+ */
public record DBOSConfig(
@NonNull String appName,
@Nullable String databaseUrl,
@@ -59,6 +102,24 @@ public record DBOSConfig(
listenQueues = (listenQueues == null) ? Set.of() : Set.copyOf(listenQueues);
}
+ /**
+ * @deprecated The built-in admin server will be removed before 1.0. Use DBOS Conductor instead.
+ */
+ @Deprecated(since = "0.9", forRemoval = true)
+ @Override
+ public boolean adminServer() {
+ return adminServer;
+ }
+
+ /**
+ * @deprecated The built-in admin server will be removed before 1.0. Use DBOS Conductor instead.
+ */
+ @Deprecated(since = "0.9", forRemoval = true)
+ @Override
+ public int adminServerPort() {
+ return adminServerPort;
+ }
+
// Copy constructor
public DBOSConfig(DBOSConfig other) {
this(
@@ -85,6 +146,16 @@ public DBOSConfig(DBOSConfig other) {
other.useListenNotify);
}
+ /**
+ * Returns a {@link DBOSConfig} with sensible defaults for the given application name.
+ *
+ * Migrations are enabled and {@code LISTEN}/{@code NOTIFY} is used for workflow wake-ups. No
+ * database connection details are pre-filled; supply them with {@link #withDatabaseUrl}, {@link
+ * #withDbUser}/{@link #withDbPassword}, or {@link #withDataSource}.
+ *
+ * @param appName unique application name; must not be null or empty
+ * @return a default {@link DBOSConfig} for the given name
+ */
public static @NonNull DBOSConfig defaults(@NonNull String appName) {
return new DBOSConfig(
appName, null, null, null, null, false, // adminServer
@@ -93,6 +164,20 @@ public DBOSConfig(DBOSConfig other) {
null, null, null, null, null, null, false, null, null, null, true); // useListenNotify
}
+ /**
+ * Returns a {@link DBOSConfig} populated from standard environment variables.
+ *
+ *
Reads the following variables:
+ *
+ *
+ * - {@code DBOS_SYSTEM_JDBC_URL} — JDBC URL for the database
+ *
- {@code PGUSER} — database username (defaults to {@code "postgres"} if absent)
+ *
- {@code PGPASSWORD} — database password
+ *
+ *
+ * @param appName unique application name; must not be null or empty
+ * @return a {@link DBOSConfig} seeded from environment variables
+ */
public static @NonNull DBOSConfig defaultsFromEnv(@NonNull String appName) {
String databaseUrl = System.getenv(Constants.SYSTEM_JDBC_URL_ENV_VAR);
String dbUser = System.getenv(Constants.POSTGRES_USER_ENV_VAR);
@@ -104,6 +189,7 @@ public DBOSConfig(DBOSConfig other) {
.withDbPassword(dbPassword);
}
+ /** Returns a copy of this config with {@code appName} set to {@code v}. */
public @NonNull DBOSConfig withAppName(@NonNull String v) {
return new DBOSConfig(
v,
@@ -127,6 +213,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code databaseUrl} set to {@code v}. */
public @NonNull DBOSConfig withDatabaseUrl(@Nullable String v) {
return new DBOSConfig(
appName,
@@ -150,6 +237,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code dbUser} set to {@code v}. */
public @NonNull DBOSConfig withDbUser(@Nullable String v) {
return new DBOSConfig(
appName,
@@ -173,6 +261,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code dbPassword} set to {@code v}. */
public @NonNull DBOSConfig withDbPassword(@Nullable String v) {
return new DBOSConfig(
appName,
@@ -196,6 +285,12 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /**
+ * Returns a copy of this config with {@code dataSource} set to {@code v}.
+ *
+ * When a {@link DataSource} is provided it takes precedence over {@code databaseUrl}, {@code
+ * dbUser}, and {@code dbPassword}.
+ */
public @NonNull DBOSConfig withDataSource(@Nullable DataSource v) {
return new DBOSConfig(
appName,
@@ -219,6 +314,12 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /**
+ * Returns a copy of this config with {@code adminServer} set to {@code v}.
+ *
+ * @deprecated The built-in admin server will be removed before 1.0. Use DBOS Conductor instead.
+ */
+ @Deprecated(since = "0.9", forRemoval = true)
public @NonNull DBOSConfig withAdminServer(boolean v) {
return new DBOSConfig(
appName,
@@ -242,6 +343,12 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /**
+ * Returns a copy of this config with {@code adminServerPort} set to {@code v}.
+ *
+ * @deprecated The built-in admin server will be removed before 1.0. Use DBOS Conductor instead.
+ */
+ @Deprecated(since = "0.9", forRemoval = true)
public @NonNull DBOSConfig withAdminServerPort(int v) {
return new DBOSConfig(
appName,
@@ -265,6 +372,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code migrate} set to {@code v}. */
public @NonNull DBOSConfig withMigrate(boolean v) {
return new DBOSConfig(
appName,
@@ -288,6 +396,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code conductorKey} set to {@code v}. */
public @NonNull DBOSConfig withConductorKey(@Nullable String v) {
return new DBOSConfig(
appName,
@@ -311,6 +420,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code conductorDomain} set to {@code v}. */
public @NonNull DBOSConfig withConductorDomain(@Nullable String v) {
return new DBOSConfig(
appName,
@@ -334,6 +444,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code conductorExecutorMetadata} set to {@code v}. */
public @NonNull DBOSConfig withConductorExecutorMetadata(@Nullable Map v) {
return new DBOSConfig(
appName,
@@ -357,6 +468,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code appVersion} set to {@code v}. */
public @NonNull DBOSConfig withAppVersion(@Nullable String v) {
return new DBOSConfig(
appName,
@@ -380,6 +492,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code executorId} set to {@code v}. */
public @NonNull DBOSConfig withExecutorId(@Nullable String v) {
return new DBOSConfig(
appName,
@@ -403,6 +516,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code databaseSchema} set to {@code v}. */
public @NonNull DBOSConfig withDatabaseSchema(@Nullable String v) {
return new DBOSConfig(
appName,
@@ -426,14 +540,17 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code enablePatching} set to {@code true}. */
public @NonNull DBOSConfig withEnablePatching() {
return this.withEnablePatching(true);
}
+ /** Returns a copy of this config with {@code enablePatching} set to {@code false}. */
public @NonNull DBOSConfig withDisablePatching() {
return this.withEnablePatching(false);
}
+ /** Returns a copy of this config with {@code enablePatching} set to {@code v}. */
public @NonNull DBOSConfig withEnablePatching(boolean v) {
return new DBOSConfig(
appName,
@@ -457,22 +574,52 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /**
+ * Returns a copy of this config with the built-in admin server enabled.
+ *
+ * @deprecated The built-in admin server will be removed before 1.0. Use DBOS Conductor instead.
+ */
+ @Deprecated(since = "0.9", forRemoval = true)
public @NonNull DBOSConfig enableAdminServer() {
return withAdminServer(true);
}
+ /**
+ * Returns a copy of this config with the built-in admin server disabled.
+ *
+ * @deprecated The built-in admin server will be removed before 1.0. Use DBOS Conductor instead.
+ */
+ @Deprecated(since = "0.9", forRemoval = true)
public @NonNull DBOSConfig disableAdminServer() {
return withAdminServer(false);
}
+ /**
+ * Returns a copy of this config with {@code queue} added to the set of listened queues. Removes
+ * the listen-on-all-queues default if this is the first queue specified.
+ *
+ * @param queue the queue to add; must not be null
+ */
public @NonNull DBOSConfig withListenQueue(@NonNull Queue queue) {
return withListenQueues(new String[] {queue.name()});
}
+ /**
+ * Returns a copy of this config with {@code queueName} added to the set of listened queues.
+ * Removes the listen-on-all-queues default if this is the first queue specified.
+ *
+ * @param queueName the queue name to add; must not be null
+ */
public @NonNull DBOSConfig withListenQueue(@NonNull String queueName) {
return withListenQueues(new String[] {queueName});
}
+ /**
+ * Returns a copy of this config with each queue in {@code queues} added to the listened set.
+ * Removes the listen-on-all-queues default if this is the first queue specified.
+ *
+ * @param queues the queues to add; {@code null} entries are ignored
+ */
public @NonNull DBOSConfig withListenQueues(@Nullable Queue... queues) {
var names =
Arrays.stream(Objects.requireNonNullElseGet(queues, () -> new Queue[0]))
@@ -481,6 +628,12 @@ public DBOSConfig(DBOSConfig other) {
return withListenQueues(names.toArray(String[]::new));
}
+ /**
+ * Returns a copy of this config with each name in {@code queueNames} added to the listened set.
+ * Removes the listen-on-all-queues default if this is the first queue specified.
+ *
+ * @param queueNames the queue names to add; {@code null} entries are ignored
+ */
public @NonNull DBOSConfig withListenQueues(@Nullable String... queueNames) {
var v =
Stream.concat(
@@ -510,6 +663,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code serializer} set to {@code v}. */
public @NonNull DBOSConfig withSerializer(@Nullable DBOSSerializer v) {
return new DBOSConfig(
appName,
@@ -533,6 +687,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code schedulerPollingInterval} set to {@code v}. */
public @NonNull DBOSConfig withSchedulerPollingInterval(@Nullable Duration v) {
return new DBOSConfig(
appName,
@@ -556,6 +711,7 @@ public DBOSConfig(DBOSConfig other) {
useListenNotify);
}
+ /** Returns a copy of this config with {@code useListenNotify} set to {@code v}. */
public @NonNull DBOSConfig withUseListenNotify(boolean v) {
return new DBOSConfig(
appName,
diff --git a/transact/src/main/java/dev/dbos/transact/execution/DBOSExecutor.java b/transact/src/main/java/dev/dbos/transact/execution/DBOSExecutor.java
index 92149f72..95e66d92 100644
--- a/transact/src/main/java/dev/dbos/transact/execution/DBOSExecutor.java
+++ b/transact/src/main/java/dev/dbos/transact/execution/DBOSExecutor.java
@@ -157,6 +157,7 @@ public DBOSExecutor(DBOSConfig config) {
}
}
+ @SuppressWarnings("removal")
public void start(
DBOS dbos,
Set listenerSet,