DB Scheduler UI

A UI extension for db-scheduler that provides a browser accessible dashboard for monitoring and basic administration of tasks.

Features

• View tasks that are Scheduled, Running or Failed.
• Re-run or Run your task directly from the User Interface
• Delete tasks
• Uses SpringBoot to launch a UI
• View the history of all tasks (optional)

Table of contents

• Getting started
• Using with Ktor (non-Spring applications)
• Prerequisites
• How it works
• Configuration

Prerequisites

• An existing Spring Boot application, with db-scheduler
• Minimum db-scheduler version 16.12.0
• Minimum Java 17 and SpringBoot 3.4 (or SpringBoot 4.0 for the Spring Boot 4 starter)

Getting started

1. Add the db-scheduler-ui spring boot starter maven dependency

   For Spring Boot 3:

   <dependency>
       <groupId>no.bekk.db-scheduler-ui</groupId>
       <artifactId>db-scheduler-ui-starter</artifactId>
       <version>4.6.0</version>
   </dependency>
   

   For Spring Boot 4:

   <dependency>
       <groupId>no.bekk.db-scheduler-ui</groupId>
       <artifactId>db-scheduler-ui-spring-boot-4-starter</artifactId>
       <version>4.6.0</version>
   </dependency>
   

2. Read the db-scheduler readme and follow the getting started guide. The most important is to create the scheduled_tasks table correctly.

3. Start your application. The db-scheduler UI can be reached at <your-app-url>/db-scheduler

Using with Ktor (non-Spring applications)

If you want to use db-scheduler-ui without Spring dependencies, you can use the Ktor plugin provided by db-scheduler-additions.

Add the dependency:

implementation("io.github.osoykan:db-scheduler-ui-ktor:$version")

Install the plugin in your Ktor application:

install(DbSchedulerUI) {
  routePath = "/db-scheduler"
  scheduler = { get<Scheduler>() } // provide your Scheduler instance
  enabled = true
  taskData = true
}

For more details and advanced configuration (including execution history support), see the db-scheduler-additions repository.

Optional: task history

Task-history support is now built into the UI starter — no extra Maven dependency is required. The execution-log writer is derived from rocketbase-io/db-scheduler-log by Marten Prieß, vendored here with permission and under the Apache License 2.0. See NOTICE for full attribution.

1. Create the scheduled_execution_logs table in your database. Pick the script for your engine from sql/log-table/: postgresql · h2 · oracle · mssql · mysql.

2. Enable history in your application.properties:

   # enable the UI-component for history
   db-scheduler-ui.history=true
   # enable the log-writer
   db-scheduler-ui.log.enabled=true
   

Migrating from io.rocketbase.extension:db-scheduler-log-spring-boot-starter: remove that dependency and rename db-scheduler-log.* properties to db-scheduler-ui.log.*.

How it works

db-scheduler-ui adds a REST-api package that has a bundled frontend application. Springboot is used to configure beans and handle dependencies within the library and your application. The user interface makes calls to the scheduler-client, where it can fetch, delete, run, and reschedule tasks. These tasks are then shown in the web application. An optional log module can also be added, making it possible to view the history of all your task executions.

Configuration

db-scheduler-ui can be configured using the following options:

history: Turns on db-scheduler-log, default value is false. You can also limit the number of logs to fetch with log-limit.

db-scheduler-ui.history=true
db-scheduler-ui.log-limit=1000

If you for some reason want to hide the task data you can set this to false. defaults to true

db-scheduler-ui.task-data=false

Or if you want a read-only mode (in which tasks cannot be manually run, deleted or scheduled) set read-only to true, defaults to false

db-scheduler-ui.read-only=true

If you want to add a prefix for the ui you can set the property below.

db-scheduler-ui.context-path=prefix

Security

In case you want to secure db-scheduler-ui you can use Spring Security, you should secure the paths /db-scheduler and /db-scheduler-api.

In a more advanced scenario, you could assign an admin role and a read-only user role. An example filter chain with basic security:

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
  return http
      .csrf(CsrfConfigurer::disable)
      .authorizeHttpRequests(
          authz ->
              authz
                  // protect the UI
                  .requestMatchers("/db-scheduler/**").hasAnyRole("ADMIN", "USER")
                  // allow read access to the API for both users and admins
                  .requestMatchers(HttpMethod.GET, "/db-scheduler-api/**").hasAnyRole("ADMIN", "USER")
                  // only admins can delete tasks, alter scheduling, ...
                  .requestMatchers(HttpMethod.POST, "/db-scheduler-api/**").hasAnyRole("ADMIN")
                  // other application specific security
                  .anyRequest().permitAll())
      .httpBasic(withDefaults())
      .build();
}

additionally you might want to hide delete, run, ... buttons in the UI. To achieve this, declare the following bean:

@Bean
ConfigController configController(DbSchedulerUiProperties properties) {
  return new ConfigController(properties.isHistory(), properties.isOverview(), readOnly(properties));
}

private Supplier<Boolean> readOnly(DbSchedulerUiProperties properties) {
  // either global readonly mode is active or user has no admin rights  
  return () -> properties.isReadOnly() || !isAdmin();
}

private boolean isAdmin() {
  Authentication auth = SecurityContextHolder.getContext().getAuthentication();
  if (auth == null) {
    return false;
  }
  return auth.getAuthorities().stream().anyMatch(a -> "ROLE_ADMIN".equals(a.getAuthority()));
}

Contributing

Feel free to create pull requests if there are features or improvements you want to add. PR's need to be approved by one of the maintainers. To publish a new version, create a release in Github and tag it with a SemVer version. A new release will then be released to maven central by a github action using JReleaser.

Before submitting a PR make sure to run mvn spotless:apply to format the code correctly. Please use the prettier config when making frontend changes

Local development

Prerequisites:

• Maven
• JDK17
• Node
• pnpm (corepack enable)

There are two ways to run the frontend locally.

1. running pnpm run dev inside the db-scheduler-ui-frontend folder
2. running mvn install will build the frontend and copy the output to the resources folder in the db-scheduler-ui module. The frontend will then be available at the same port as the example app.

To run the backend run mvn clean install and then run the example app.