Upgrade to v9

This guide documents how to migrate to JobRunr v9 and JobRunr Pro v9.

This version is currently in beta and will release on September 30th. Join us for the webinar on October 1st to discover the new features!

Important

This release has a number of breaking changes. Please carefully review the breaking changes section.

Warning

JobRunr v9 will be the last major version on the open source edition to support Java 8, for continued support of Java 8 on later versions please upgrade to JobRunr Pro.

Installation

For the OSS version, the v9 release is available in the Maven Central repository.

For Pro users, the v9 release is available on our private Maven repository.

Simply replace the version you’re on with 9.0.0.

New job history view mode

JobRunr v9 introduces a new way to view your job’s history, this feature is available automatically to all users with no extra configuration necessary.

When you open a job, within the History section you can now select between the Timeline mode that you are used to, or you can select the new Chart mode which will show you a Gantt chart representation of your jobs processing.

Both the new chart and timeline now also show you how long an individual step took, and what the outcome of each step was, if you are leveraging durable executions.

Micronaut 5 support

As of v9, JobRunr OSS and JobRunr Pro require Micronaut 5. Before upgrading to JobRunr v9, you must upgrade your application from Micronaut 4 to Micronaut 5.

Support for Micronaut 4 has been removed and is no longer available in JobRunr v9.

Micronaut autoconfigure Amazon DocumentDB

In order to align with other framework supports, we have now added Amazon DocumentDB auto-configuration to the micronaut integration.

Quarkus 3.40 LTS support

JobRunr v9 supports Quarkus 3.40 LTS from day one. The LTS shipped at the end of
September 2026 and receives critical fixes and security patches for a full year

You can upgrade your application to Quarkus 3.40 LTS together with JobRunr v9 - no separate extension update or
waiting period.

jobrunr_jobs_stats with SQL SECURITY INVOKER on MySQL and MariaDB

The default behaviour of MySQL and MariaDB is to create a view with SQL SECURITY DEFINER, this is an issue when the user who runs the migrations is not in another environment if you use a database dump to restore into it. The switch to using SQL SECURITY INVOKER on the jobrunr_jobs_stats view fixes this behaviour, meaning that you should no longer have issues where your view fails to create when you restore into another environment.

Warning when job argument is too large

We recommend avoiding large job arguments as they can negatively impact JobRunr’s performance, we have more information about this in our best practices.

In order to make this warning more verbose, we have now added a warning in both the frontend page for a job and in the backend if the serialized version of the job is too large. The threshold is lower on the frontend than the backend to give you advance warning before we start logging these issues in the backend.

If you notice that your performance is reduced when you have a lot of jobs, consider looking into the size of your job arguments.

EventBus

JobRunr Pro now includes a built-in EventBus that supports multiple inter-server communication channels, such as UDP multicast and PostgreSQL LISTEN/NOTIFY.

With the EventBus, job enqueue events are propagated to all relevant servers immediately, allowing enqueued jobs to start executing almost instantly instead of waiting for the next polling cycle.

Usage

If you don’t do anything, it will be automatically configured for you using org.jobrunr.utils.events.EventTransportFactory#createEventTransport, but if you want to customize this, you can do it as follows.

To use the event bus, you must now configure an EventTransport. If you were previously using the jobrunr.multicast-group-address property, you will need to provide an EventTransport bean. Alternatively, if you were using org.jobrunr.configuration.JobRunrConfiguration#useMulticastAddress, update your setup to use org.jobrunr.configuration.JobRunrConfiguration#useEventTransport.

You can choose between a PostgresEventTransport (if you are using PostgreSQL) or a MulticastEventTransport. If you do not explicitly configure one, JobRunr will use the MulticastEventTransport by default unless you are using PostgreSQL as your storage provider, then the default will be PostgresEventTransport.

JobRunrPro
    .configure()
    .useEventTransport(new MulticastEventTransport(URI.create("udp://239.76.159.181:8379")));

@Bean
EventTransport eventTransport(StorageProvider storageProvider) {
    return new CustomEventTransport();
}

@Produces
@Singleton
EventTransport eventTransport(StorageProvider storageProvider) {
    return new CustomEventTransport();
}

@Singleton
EventTransport eventTransport(StorageProvider storageProvider) {
    return new CustomEventTransport();
}

Important

When you use the MulticastEventTransport like with the previous implementation of multicast please ensure that your network supports multicast.

Pausing of Batch Jobs

The Pause Batch Job feature allows you to temporarily stop the execution of all child jobs within a batch that have not yet started processing.

When a batch job is paused, all child jobs in the Enqueued, Scheduled, or Pending state are paused and will not execute until the batch job is resumed. Child jobs that are already Processing continue running to completion.

If you need to fetch all paused batch jobs, you can use the static JobSearchRequestBuilder method in order to create a JobSearchRequest that will fetch all the paused batch jobs.

JobSearchRequestBuilder
    .aJobSearchRequest()
    .withOnlyPausedBatchJobs()
    .build();

Usage

You can pause and resume a batch job in one of three ways:

• Use the Pause and Resume buttons in the JobRunr dashboard.
• Call the REST API endpoints:
  • POST /jobs/{batchJobId}/pause
  • POST /jobs/{batchJobId}/resume
• Use the BatchJobManager to programmatically pause or resume a batch job

  var manager = new BatchJobManager(storageProvider);
  manager.pauseBatchJob("batchJobId");
  manager.resumeBatchJob("batchJobId");
  

If you pause a batch job after all of its child jobs have entered the Processing state, the batch job will continue to completion because there are no remaining child jobs that can be paused.

Analytics

v9 brings a brand-new look to your dashboard page. The previous realtime graph has been removed and replaced with per job analytics. This analytics page allows you to view how each job type is performing but also how JobRunr is performing as a whole, both for the current hour but also for past time periods.

Usage

Analytics is enabled by default, with no action needing to be taken to enable this.

SmartQueue becomes JobPrefetchQueue

SmartQueue is now known as JobPrefetchQueue. Alongside this renaming there have been improvements to the queue.

To increase the throughput JobRunr tries to eliminate the latency to get the jobs to process. With this queuing system, a worker no longer needs to go to the database when they finish, it can pick a Job from the ones JobRunr fetched right before it finishes.

We have introduced the WorkerCapacityStrategy and FixedSizeWorkerCapacityStrategy in order to decouple worker-count decisions from the prefetch logic. And improved performance of the queue by altering WindowedJobStatistics minimum in O(1) via a monotonic dequeue.

This rework also introduces diagnostics for this session in the form of PrefetchQueueStats together with FetchResult which replace the failed counter.

Dashboard Allow creating custom views

The dashboard now allows you to create custom views, similar to bookmarks. A custom view can only be created after an initial filter. Custom views allow you to, for the first time, display jobs of multiple states on the same page.

In order to keep things consistent, custom views introduce a new view parameter in the URL, which deprecates the state parameter.

Dashboard permanently delete deleted jobs

If a user has the canDeleteJobs access rule set to true they can now permanently delete a deleted job from the dashboard. You can select jobs to permanently delete both in the individual job page and on the overview page for the deleted state.

There is no change to how permanent deletion of jobs works automatically.

DeleteFilter as a default filter

The DeleteFilter is now configured as a Bean allowing it to be available to the JobScheduler so that external jobs can be automatically cleaned up on completion. The Fluent API also sets a default filter unless you have provided one. We only ever expect a single instance of DeleteFilter to be present.

With this change, we have also deprecated the retention properties on the background-job-server, these are instead now available on the jobs. If the retention properties are not set via jobs we fallback to the background-job-server, but only until v10.

Important

The old syntax for configuring the DeleteFilter will be removed in v10

Usage

If you were previously using any of the DeleteFilter configurations using the old syntax with jobrunr.background-job-server.*, you must now switch to using jobrunr.jobs.*.

For the FluentAPI it is now preferrable to configure the deletion policies by providing an instance of DeleteFilter.

JobRunrPro
    .configure()
    .withJobFilter(new DeleteFilter(Duration.ofHours(2), null, Duration.ofDays(5)))
    // ...
    .initialize();

# Old syntax: jobrunr.background-job-server.delete-succeeded-jobs-after=PT2H
# Replaced by:
jobrunr.jobs.delete-succeeded-jobs-after=PT2H

# Old syntax: jobrunr.background-job-server.delete-failed-jobs-after=PT48H
# Replaced by:
jobrunr.jobs.delete-failed-jobs-after=PT48H

# Old syntax: jobrunr.background-job-server.permanently-delete-deleted-jobs-after=PT64H
# Replaced by:
jobrunr.jobs.permanently-delete-deleted-jobs-after=PT64H

Kotlin Exposed upgrade

The Kotlin Exposed dependency has been upgraded to v1. To continue using the Exposed Transaction Plugin, you must upgrade your application to Exposed v1.

Breaking Changes

API Changes

We removed a number of API’s that were deprecated in v8:

• The deprecated JobRunrConfiguration#useMicroMeter has been removed, use JobRunrConfiguration#useMetrics instead
• The deprecated JobBuilder#withDetails has been removed, use JobBuilder#withJobLambda instead
• The deprecated RecurringJobBuilder#withDetails has been removed, use RecurringJobBuilder#withJobLambda instead
• JobRunr Pro The deprecated JobSearchRequestBuilder#withQueue has been removed, use JobSearchRequestBuilder#withPriorityQueue instead
• JobRunr Pro The deprecated RecurringJobSearchRequestBuilder#withQueue has been removed, use RecurringJobSearchRequestBuilder#withPriorityQueue instead
• JobRunr Pro The deprecated JobServerFilter#getProgress has been removed, use JobServerFilter#getProgressAsRatio instead

Other changes:

• JobRunr Pro JobRunrDashboardWebServer has constructor changes to accept an EventTransport
• JobRunr Pro DashboardApiHandler and DashboardDbDataProvider have constructor changes to accept an EventBus
• JobRunr Pro JobScheduler and JobRequestScheduler have constructor changes to accept an EventTransport.
• JobRunr Pro StorageProvider.BatchJobWithChildStats and StorageProvider.BatchJobChildStats now also require an awaitingBatchJobChildCount
• JobRunr Pro DashboardDbDataProvider public constructor now also expects a BatchJobManager
• JobRunr Pro ConcurrentJobModificationPolicy has been dropped with no alternative
• JobRunr Pro JobSearchRequest now requires a list of UUID for awaitingOn
• JobRunr Pro Remove CronExpression#create, use constructor instead
• JobRunr Pro Several unused constructor on RoundRobinDynamicQueuePolicy had been removed
• JobRunr Pro Removed duplicate JsonMapperFactory, use the factory in package org.jobrunr.utils.mapper

Micronaut

• Dropped support for Micronaut 4, use Micronaut 5 instead

Kotlin Exposed

• JobRunr Pro Kotlin Exposed now requires v1

Multicast

• JobRunr Pro JobEnqueuedMessagePublisher has removed, you may implement an EventTransport instead.
• JobRunr Pro MulticastMessagePublisher and MulticastMessageReceiver have been removed, see MulticastEventTransport instead.

Job States

• JobRunr Pro AllowedJobStateStateChanges.isIllegalStateChange(...) now also expected a JobType
• JobRunr Pro DeletedState: the constructor DeletedState(String reason, JobRunrUserInfo user) has been removed
• JobRunr Pro EnqueuedState: the constructor EnqueuedState(String reason, JobRunrUserInfo user) has been removed

BackgroundJobServer

• JobRunr Pro org.jobrunr.server.BackgroundJobServer#publishJobEnqueuedMessage has been dropped you may use org.jobrunr.server.BackgroundJobServer#publishEvent instead.
• JobRunr Pro BackgroundJobServer has constructor changes to accept an EventTransport

Queues

• JobRunr Pro SmartQueue has been renamed to JobPrefetchQueue

Configuration

• JobRunr Pro StorageProviderClusterConfiguration has constructor changes to accept an EventBus instead of multi-cast-group-address.
• JobRunr Pro Method org.jobrunr.configuration.JobRunrConfiguration#useMulticastAddress has been dropped, you’ll need to configure a MulticastEventTransport via org.jobrunr.configuration.JobRunrConfiguration#useEventTransport.
• JobRunr Pro Property jobrunr.multicast-group-address has been dropped, you’ll need to provide configure MulticastEventTransport bean.

Multi-Cluster

• JobRunr Pro The Multi-Cluster Dashboard should be upgraded at the same time as the single cluster dashboard (this is not required if they were on 8.7 or higher)

Test Fixtures

• JobRunr test fixtures now require JDK 17 or higher