Upgrade to v9

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

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.

Important

This release contains a number of index changes, if you have a lot of jobs this upgrade may take some time. Please consider this when making the upgrade.

This version of JobRunr is backwards compatible with v8, but only until you use a new feature such as pausing batch jobs, which saves affected jobs in a format your v8 server cannot read. You can run a v8 and a v9 server side by side on the same database. Keep in mind that v9-only features such as Analytics work only for jobs processed on a v9 server.

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.

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.

SQL security invoker on MySQL & MariaDB

By default, MySQL and MariaDB create views with SQL SECURITY DEFINER. This is a problem when you restore a database dump into another environment where the migration user does not exist. The switch to using SQL SECURITY INVOKER on the jobrunr_jobs_stats view fixes this behavior, 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. See our best practices for more information.

To make this warning more explicit, we now warn in two places when the serialized version of a job is too large: in the dashboard page for a job, and in the backend. 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

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

By default, the event transport is configured automatically via org.jobrunr.utils.events.EventTransportFactory#createEventTransport. To customize it, configure an EventTransport 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 or PostgresEventTransport when you are using PostgreSQL as your storage provider.

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

If you use the MulticastEventTransport (as with the previous multicast implementation), make sure your network supports multicast.

Pausing of Batch Jobs JobRunr Pro

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.

Note

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.

If you pause a batch job while it is still enqueuing child jobs, it will finish enqueuing the child jobs and then pause.

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 three different ways, as listed below.

Dashboard

You can use the Pause and Resume buttons in the JobRunr dashboard.

Rest Endpoints

You can call the following REST API endpoints to pause and resume a batch job respectively.

• POST /jobs/{batchJobId}/pause
• POST /jobs/{batchJobId}/resume

Using BatchJobManager

You can use the BatchJobManager to programmatically pause or resume a batch job.

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

@Autowired
private BatchJobManager batchJobManager;

batchJobManager.pauseBatchJob("batchJobId");
batchJobManager.resumeBatchJob("batchJobId");

@Inject
BatchJobManager batchJobManager;

batchJobManager.pauseBatchJob("batchJobId");
batchJobManager.resumeBatchJob("batchJobId");

@Inject
private BatchJobManager batchJobManager;

batchJobManager.pauseBatchJob("batchJobId");
batchJobManager.resumeBatchJob("batchJobId");

Analytics JobRunr Pro

JobRunr Pro 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 JobRunr Pro

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.

Usage

There are 2 ways to configure the PrefetchQueueBackgroundJobServerWorkerPolicy, either by injecting it or by configuring it in your properties.

Properties

To configure the PrefetchQueueBackgroundJobServerWorkerPolicy via your properties you need to provide the jobrunr.background-job-server.work-distribution-strategy property, the possible values for this property are basic (the default) and prefetch-queue (for the prefetch policy).

Injection

To use this new queue, provide the PrefetchQueueBackgroundJobServerWorkerPolicy in one of the following ways, depending on your configuration of choice. This policy can optionally be provided with a BackgroundJobServerThreadType and a workerCount.

By default, the BackgroundJobServerThreadType is BackgroundJobServerThreadType.getDefaultThreadType() and the worker count is threadType.getDefaultWorkerCount().

JobRunrPro
    .configure()
    .useBackgroundJobServer(
        usingStandardBackgroundJobServerConfiguration()
        .andBackgroundJobServerWorkerPolicy(new PrefetchQueueBackgroundJobServerWorkerPolicy())
    );

@Bean
public BackgroundJobServerWorkerPolicy backgroundJobServerWorkerPolicy() {
    return new PrefetchQueueBackgroundJobServerWorkerPolicy();
}

@Produces
@Singleton
public BackgroundJobServerWorkerPolicy backgroundJobServerWorkerPolicy() {
    return new PrefetchQueueBackgroundJobServerWorkerPolicy();
}

@Singleton
public BackgroundJobServerWorkerPolicy backgroundJobServerWorkerPolicy() {
    return new PrefetchQueueBackgroundJobServerWorkerPolicy();
}

Introduce SelfLearningWorkerCapacityPolicy JobRunr Pro

The new SelfLearningWorkerCapacityPolicy allows you to let JobRunr decide what the optimal number of workers for your application is. JobRunr evaluates based on the database connection acquisition time, the memory usage, the cpu usage and the health of your server overall. If any of these gets too high then JobRunr will back off and reduce the worker count, if all are healthy then we will continue to increase the worker count until we reach the limit of the deciders.

This new policy allows you to maximize the throughput of your server while making sure that it stays stable.

Usage

There are 2 ways to configure this policy, either by injecting it or by configuring it in your properties.

Properties

To configure the SelfLearningWorkerCapacityPolicy via your properties you need to provide the jobrunr.background-job-server.worker-capacity-policy property, the possible values for this property are fixed-size (the default) and self-learning (for the self learning policy).

Injection

When instantiating the policy, you can optionally provide a minimum and maximum worker count. Please note that if the minimum worker count that you provide is higher than your server can handle, this policy will not be able to keep your server stable.

JobRunrPro
    .configure()
    .useBackgroundJobServer(
        usingStandardBackgroundJobServerConfiguration()
        .andBackgroundJobServerWorkerPolicy(
            new PrefetchQueueBackgroundJobServerWorkerPolicy(new SelfLearningWorkerCapacityPolicy())
        )
    );

@Bean
public BackgroundJobServerWorkerPolicy backgroundJobServerWorkerPolicy() {
    return new PrefetchQueueBackgroundJobServerWorkerPolicy(new SelfLearningWorkerCapacityPolicy());
}

@Produces
@Singleton
public BackgroundJobServerWorkerPolicy backgroundJobServerWorkerPolicy() {
    return new PrefetchQueueBackgroundJobServerWorkerPolicy(new SelfLearningWorkerCapacityPolicy());
}

@Singleton
public BackgroundJobServerWorkerPolicy backgroundJobServerWorkerPolicy() {
    return new PrefetchQueueBackgroundJobServerWorkerPolicy(new SelfLearningWorkerCapacityPolicy());
}

Alternatively you can provide DefaultBackgroundJobServerWorkerPolicy instead of PrefetchQueueBackgroundJobServerWorkerPolicy to use the basic work distribution strategy.

Dashboard Allow creating custom views JobRunr Pro

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 JobRunr Pro

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.

Kotlin Exposed upgrade JobRunr Pro

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