Stop Lying to Your Schedulers

• JobRunr OSS as the background job engine

• Spring Boot application as the runtime host

• Flyway as the owner of schema changes

• A minimal application-native operator UI

• root-only access to job operations

• No migration of business jobs in the first implementation slice

That last point matters. I did not want infrastructure adoption and the first real workflow migration in the same change. That is how teams lose the ability to tell where risk actually came from.

How JobRunr Fits Into an Existing Spring Boot Application

The useful part of JobRunr is not the annotation story. It is the durable execution model.

The first step was simply wiring the engine into the existing app:

<dependency>
  <groupId>org.jobrunr</groupId>
  <artifactId>jobrunr-spring-boot-4-starter</artifactId>
  <version>8.5.2</version>
</dependency>

Then the runtime configuration:

jobrunr:
  background-job-server:
    enabled: true
    poll-interval-in-seconds: 15
    worker-count: 10
  dashboard:
    enabled: false
  jobs:
    default-number-of-retries: 5
  database:
    skip-create: true
  miscellaneous:
    allow-anonymous-data-usage: false

There are two important lines there.

The first is:

jobrunr:
  dashboard:
    enabled: false

That was deliberate. I did not want the OSS dashboard to become an accidental part of the application boundary.

The second is more important:

jobrunr:
  database:
    skip-create: true

That line is the difference between "the library owns its tables" and "the platform owns its schema."

Why Flyway Had to Own the Schema

I do not like runtime DDL in production systems once the platform matures beyond a certain point.

If the target model is:

• migration user performs DDL

• runtime application user performs DML

then a background job library should not be allowed to create or alter schema on startup. That is a convenience feature in small systems. It becomes a liability once you care about permission boundaries and predictable deployments.

So the decision was simple:

Flyway owns the JobRunr schema. JobRunr uses the schema.

Not the other way around.

That meant generating the SQL for the exact pinned JobRunr version and committing it as a normal Flyway migration:

-- V4__jobrunr_tables.sql
CREATE TABLE jobrunr_jobs (...);
CREATE TABLE jobrunr_recurring_jobs (...);
CREATE TABLE jobrunr_backgroundjobservers (...);
CREATE TABLE jobrunr_metadata (...);

The exact DDL came from the pinned JobRunr version, not from guesswork and not from a loosely matched example online. That distinction matters because schema drift caused by library upgrades is exactly the kind of problem you are trying to prevent.

This was the central architectural decision of the implementation. The real question was never "can JobRunr run?" because of course it can. The real decision was:

Will runtime code be allowed to mutate schema?

My answer was no.

Why I Did Not Use the OSS Dashboard

This is the part people tend to argue about because the built-in dashboard looks like free value. Sometimes it is. More often, it is just borrowed complexity.

In this case, the application already had:

• its own role model

• its own navigation structure

• its own session and security model

• a requirement that operational access be limited to the highest-privilege internal role

That made the decision straightforward:

• Do not expose the OSS dashboard as the primary operator surface

• Add a small internal API

• Add a minimal internal page

That is less feature-rich than a vendor dashboard. It is also cleaner.

The first backend API was intentionally small:

@RestController
@RequestMapping("/api/v1/jobs")
@PreAuthorize("hasRole('ROOT')")
class JobStatusController {

    private final JobStatusService jobStatusService;

    @GetMapping("/stats")
    JobStatsDTO stats() {
        return jobStatusService.getStats();
    }

    @GetMapping("/recurring")
    List<RecurringJobDTO> recurringJobs() {
        return jobStatusService.getRecurringJobs();
    }
}

The service layer used JobRunr's StorageProvider, but the application did not expose JobRunr types directly:

@Service
class JobStatusService {

    private final StorageProvider storageProvider;

    JobStatsDTO getStats() {
        var stats = storageProvider.getJobStats();
        return new JobStatsDTO(
            stats.getScheduled(),
            stats.getEnqueued(),
            stats.getProcessing(),
            stats.getSucceeded(),
            stats.getFailed()
        );
    }
}

That layer is not busywork. It is where the application chooses its own contract instead of inheriting a vendor contract by accident.

The UI Should Start Read-Only

I strongly prefer the first operator surface to be read-only.

Not because trigger controls are bad. Because they expand the blast radius of the first release.

The first page did only two things:

• show aggregate job counts

• show recurring jobs

The route was root-only:

beforeLoad: ({ context }) => {
  const roles = getRolesFromProfile(context.auth.user?.profile);
  if (!hasRole(roles, 'ROLE_ROOT')) {
    throw redirect({ to: '/' });
  }
}

And the frontend service was intentionally thin:

export const jobsService = {
  getStats: () =>
    apiClient.get<JobStatsDTO>('/jobs/stats').then((res) => res.data),

  getRecurring: () =>
    apiClient
      .get<Array<RecurringJobDTO>>('/jobs/recurring')
      .then((res) => res.data),
};

That was enough for a minimal page:

const { data: stats } = useQuery({
  queryKey: ['jobs-stats'],
  queryFn: jobsService.getStats,
});

const { data: recurringJobs } = useQuery({
  queryKey: ['jobs-recurring'],
  queryFn: jobsService.getRecurring,
});

This is the correct amount of UI for the first implementation slice.

Do not confuse "small" with "unfinished." A root-only read-only page is a valid operator surface when the job engine itself is the real first milestone.

Not Every Scheduled Task Should Move

This is where teams over-rotate.

Once a durable job engine exists, teams often want to move everything into it, and that is usually a category mistake.

Some tasks need:

• Retry history

• Visibility

• Durable persistence

• Operator awareness

Some tasks are just lightweight timers, and I do not treat those as the same problem.

So the strategy was mixed:

• durable, meaningful background jobs move to JobRunr

• lightweight housekeeping tasks can remain on Spring @Scheduled

That is not inconsistency. It is operational precision.

The system does not get better because one tool is used everywhere. It gets better because each behavior lives under the right model.

Why I Split Infrastructure From the First Real Job Migration

This was the other important decision. I did not migrate an existing recurring business workflow in the same ticket.

I only implemented:

• the engine

• the schema

• the security boundary

• the backend contract

• the minimal UI

The first real recurring job migration was left for the next story.

That split matters because it isolates categories of risk:

• infrastructure risk

• schema ownership risk

• security risk

• workflow migration risk

If all of that lands together, teams get one large diff and one vague answer if something goes wrong. I prefer smaller truths.

What This Looks Like in Practice

After the first implementation slice, the system had:

• JobRunr OSS running inside the Spring Boot app

• Flyway-managed JobRunr tables

• no runtime DDL by the application

• root-only job status API

• root-only job monitor page

• existing business scheduling behavior unchanged

That last point is easy to overlook because the system was better before any business workflow was migrated.

That is the signal I look for in infrastructure work. The platform got safer and more observable before the first domain job moved onto it.

Summary

• Add the job engine as infrastructure first, not as a side effect of a workflow migration

• Disable runtime schema creation and keep DDL with Flyway

• Use the exact pinned library version when generating schema

• Prefer a small application-native operator surface when security and ownership boundaries matter

• Start the UI read-only

• Restrict job operations to the highest-privilege internal role

• Do not migrate every scheduled task just because a new engine exists

Final Thoughts

This is the kind of engineering decision that matters more in the AI era, not less. AI can generate the dependency line, the YAML block, and half the controller. What it will not decide is whether the library should own schema, whether the built-in dashboard belongs inside your security model, or whether the first implementation slice should stop at infrastructure instead of reaching for workflow migration too early. Those are architectural decisions. And they are exactly where engineers still earn their keep.

If your team is about to add a job library by copying the quick-start, send them this first. More in the "Stop Lying to Your Stack" series.