Repository navigation
DBOS Transact for Java 1.3.0
// Gradle
implementation("dev.dbos:transact:1.3.0")<!-- Maven -->
<dependency>
<groupId>dev.dbos</groupId>
<artifactId>transact</artifactId>
<version>1.3.0</version>
</dependency>1.3 adds workflow rewind, a workflow ID reuse policy and queue pausing. The Conductor client moves to a separate artifact, dev.dbos:transact-enterprise. Workflow deadlines are now enforced by a database-side sweep on the database's clock, and only the execution that owns a workflow can write its checkpoints. The system database migrates to version 125.
Important
Conductor users must add dev.dbos:transact-enterprise:1.3.0, or launch fails. See Conductor needs dev.dbos:transact-enterprise.
Important
With withMigrate(false), apply migrations 115–125 before upgrading. A 1.3 DBOSClient needs them too. See System database migrations.
Warning
The Conductor client now verifies Conductor's TLS certificate. A self-hosted Conductor with a certificate the JVM doesn't trust stops connecting. See Conductor needs dev.dbos:transact-enterprise.
Warning
A schedule without cronTimezone now fires in UTC. If your hosts aren't in UTC, see Schedules without a time zone run in UTC.
New features
- Workflow rewind (#608).
DBOS.rewindWorkflow(workflowId, startStep[, RewindOptions])andDBOSClient.rewindWorkflowre-run a finished workflow in place, under the same ID, fromstartStep. Later steps are discarded, events roll back, and closed streams reopen. Conductor can rewind workflows too. A client rewind can't reach the application database, so it leaves transactional step checkpoints in place. Most workflows that finished on 1.3 have none left, since they're deleted when a workflow finishes, but a cancelled workflow, or one that finished before the upgrade, replays those steps' recorded results. A message consumed before migration 121, or by a 1.2 executor, stays consumed. - Workflow ID reuse policy (#650). With
withWorkflowIdReusePolicy(WorkflowIdReusePolicy.REJECT)onStartWorkflowOptions,EnqueueOptionsorWorkflowOptions, a taken ID throwsDBOSWorkflowIdInUseExceptioninstead of returning the existing workflow. - Pausing a queue (#651). A
concurrencyorworkerConcurrencyof 0 holds a queue's workflows until an update raises it, for exampleupdateQueue(name, new QueueOptions().withWorkerConcurrency(0)). Don't pause queues while 1.2 executors are running; see Running 1.2 and 1.3 together. - Deduplication on partitioned queues (#655). An enqueue can set both a partition key and a deduplication ID. The ID is deduplicated across the whole queue; to deduplicate per partition, put the partition key in the ID.
- Conductor metadata-only mode (#647):
withConductorMetadataOnlyMode(true), ordbos.conductor.metadata-only-modein Spring Boot. - System database idle-transaction timeout (#616). Connections DBOS creates set
idle_in_transaction_session_timeout, one minute by default. Change it withwithSystemDatabaseIdleTransactionTimeout(Duration). ADataSourceyou supply is left alone. new JdbiStepFactory(dbos, jdbi, dataSource)(#622). Pass theDataSourceyourJdbiinstance was created from when it's the same connection pool DBOS uses for its system database, as with the Spring Boot starter's defaultDataSourcebean.
Upgrading from 1.2
Conductor needs dev.dbos:transact-enterprise
The Conductor client moved out of dev.dbos:transact into dev.dbos:transact-enterprise (#626, #632), licensed under the DBOS Conductor Software License. If your application sets a Conductor key (withConductorKey, or dbos.conductor.key in Spring Boot), add it at exactly the same version as dev.dbos:transact:
// Gradle
implementation("dev.dbos:transact-enterprise:1.3.0")<!-- Maven -->
<dependency>
<groupId>dev.dbos</groupId>
<artifactId>transact-enterprise</artifactId>
<version>1.3.0</version>
</dependency>Without it, DBOS.launch() throws IllegalStateException ("Connecting to DBOS Conductor requires dev.dbos:transact-enterprise on the class path…"). With a different version, launch fails naming both. The Conductor-only operations, such as export and import, fork from the failed step, retention and metrics, moved with the client (#646), and still work from Conductor.
The client now verifies Conductor's TLS certificate. In 1.2 it accepted any certificate on wss:// connections. A self-hosted Conductor whose certificate the JVM doesn't trust, such as a self-signed or private-CA one, no longer connects: the client logs the failure and keeps retrying. Add the certificate to a trust store and pass it with the standard javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword system properties.
System database migrations
At launch, 1.3 migrates the system database from 114 to 125. The index builds don't block writes on Postgres, but take a while on a large database.
With withMigrate(false) (dbos.datasource.migrate=false in Spring Boot), run dbosctl sysdb migrate from dbosctl v0.12.0 or later first; otherwise launch throws IllegalStateException. A 1.3 DBOSClient never migrates and also requires version 125.
Schedules without a time zone run in UTC
A schedule without cronTimezone is now read in UTC (#624); 1.2 read it in the host's zone. To keep a zone, use withCronTimezone(...).
On a host not in UTC, such schedules also get new workflow IDs for their ticks, even when their firing times don't move. So:
- don't run 1.2 and 1.3 executors together, or every tick runs twice;
- don't backfill across the upgrade, or ticks 1.2 already fired run again;
- the first automatic backfill after the upgrade may enqueue a tick that was never due.
Running 1.2 and 1.3 together
- Keep the application version. A computed version includes the DBOS version. If it changes, 1.3 won't recover or dequeue work 1.2 left behind, and resuming that work doesn't change its version. Keep 1.2's
appVersionvalue, or set 1.3's to the version 1.2 computed (seelistApplicationVersions()), or fork the work withForkOptions.withApplicationVersion(...). - Don't pause queues. 1.2 can't read a queue with a limit of 0. Its queue discovery fails, and it keeps dequeuing with the limits it last read.
- Expect
DBOSStepNondeterminismExceptionon stale runs. 1.2 doesn't fence its writes, so it can write a step for a run a 1.3 executor has taken over. - Schedules on hosts not in UTC run twice (see above).
Rolling back to 1.2
1.2 runs against a schema migrated to 125. Before rolling back:
- remove
dev.dbos:transact-enterprise, which requires core 1.3.0; - raise any queue limit of 0 to at least 1;
- keep the application version, as on the way up.
After rolling back:
- 1.2 can't read back
DBOSStepNondeterminismException,DBOSWorkflowIdInUseExceptionorDBOSDelayPastLatestInstantException. A workflow that recorded one fails on replay. - Schedules without a time zone change tick IDs again on hosts not in UTC.
- Deadlines follow 1.2's rules: with no sweep, a queued or delayed workflow past its deadline waits until it is dequeued.
Source changes
The DBOS and DBOSClient methods are unchanged. However:
- Record components.
StartWorkflowOptions,EnqueueOptions,WorkflowOptionsand the deprecatedDBOSClient.EnqueueOptionsgainworkflowIdReusePolicy.DBOSConfiggainssystemDatabaseIdleTransactionTimeoutandconductorMetadataOnlyMode. Code calling their canonical constructors must pass the new values. Recompile against 1.3: 1.2-compiled code fails withNoSuchMethodError. - Transactional step factories must be created before
DBOS.launch()(#607); afterwards they throwIllegalStateException. - Removed Conductor types.
dev.dbos.transact.conductor.Conductor, theconductor.protocolpackage, and the types used only by Conductor-only operations, such asExportedWorkflowandMetricData, are gone (#632, #646). None were part of theDBOSorDBOSClientAPI. Queueconstructors no longer validate limits (#651). Registering or updating the queue does.
Behavior changes
Workflows
- A workflow can't cancel, resume or delete itself (#661). From inside a workflow or its steps, these calls throw
IllegalArgumentExceptionwhen their targets include the caller, before anything is written. The refusal is recorded, so a replay throws it again.DBOSClientis unaffected, and so is acancelChildrenordeleteChildrencascade from an ancestor. - DBOS's own steps record errors in the native format (#661), whatever serializer is configured, so a replay rethrows the same type. Errors from
getResultand your own steps still use your serializer. - A
WorkflowOptionsblock's ID is used once (#650). After a nested block, the next workflow in the outer block gets a new ID instead of reusing the one already taken. - Lifecycle listeners hear of a failed launch (#662).
dbosShutDown()is called whenlaunch()fails, even ifdbosLaunched()never ran. A later launch callsdbosLaunched()again.
Timeouts and clocks
- A database-side sweep enforces deadlines (#612). Every executor cancels its application's
ENQUEUED,PENDINGandDELAYEDworkflows past their deadline, once a second, including ones no process is running. - Deadlines and delayed releases use the database's clock (#612, #613), not the JVM's.
- Durations too long to store are refused with
IllegalArgumentException(#645). A delay past the largest storable instant throwsDBOSDelayPastLatestInstantException. schedulerPollingIntervalmust be between 1 ms andLong.MAX_VALUEms (#653), checked when the config is built.getResult()after a deadline reports what the database records (#635): a resumed run's result, orDBOSNonExistentWorkflowExceptionif the workflow was deleted.
Execution ownership
Each checkpoint write now checks that its execution still owns the workflow (#615, #616), as in the other DBOS SDKs. An execution that lost its workflow stops at its next write.
- Recording a different result at an already-recorded step throws
DBOSStepNondeterminismException. - A duplicate start no longer re-stamps the existing row.
- A child's start commits with its parent's step, and a child enqueue's deduplication collision is recorded there too (#625).
Queues
- Queue limits are checked on write, not read (#651), so a stored row that breaks Java's rules no longer stops queue discovery. Negative limits are refused with "must not be negative".
- The deprecated partition flag is refused beside a per-partition limit (#652).
Transactional steps
- A workflow's
tx_step_outputsrows are deleted when it finishes (#621). Rows from cancelled workflows remain. JdbiStepFactorysteps no longer go through theJdbiTransactionHandler(#618).
Patching
patchtakes the old path across a gap in the step history (#660).
Fixes
- A
launch()that throws no longer leaves a half-launchedDBOS. A retry now launches again, instead of returning with nothing running (#662). - A
recvthat timed out with no message replays asnull, instead of receiving again on recovery (#615). - A losing execution notices another recorded a step first, instead of running on (#615).
JdbiStepFactorysteps andTxStepSchema.createTablecommit on a pool without autocommit (#607, #618).tx_step_outputs.step_idis created asINT4on CockroachDB (#611).- The transactional-step retry backs off, up to 2 s (#620).
- A tick fired by the loop and by backfill under a named time zone gets one ID, so it no longer runs twice (#624).
- A timeout near
Long.MAX_VALUEms no longer blocks its queue or fails to start (#612, #645). - A finished run's timeout timer no longer holds its result until the deadline (#635).
- A partitioned queue's sweep stops once a queue-wide limit is spent (#654).
backfillScheduledocuments its window as (start, end] (#637).- Conductor client, in
dev.dbos:transact-enterprise:- A streamed import could be corrupted by frames the WebSocket reused, or wait forever when the connection dropped mid-import.
- Another response could be merged into a streamed export.
- A long import blocked the JVM's common thread pool. Conductor's handlers now run on threads of their own.
- A response split into fragments could break a multi-byte UTF-8 character.
- A fast pong could race the ping timeout and force a needless reconnect.
Build and release
- Milestones and release candidates are published only to GitHub Packages (
https://maven.pkg.github.com/dbos-inc/dbos-transact-java), which needs a GitHub token (#630). Full releases still go to Maven Central.
Full Changelog: 1.2.0...1.3.0