Reference Guide

Spring Boot Database Admin v0.1.5

1. Introduction

This guide outlines how to install, configure and customize Spring Boot Database Admin panel. Refer to this document for troubleshooting and if you still encounter problems, please report it as an issue on Github.

2. Getting started

Getting started with Spring Boot Database Admin requires including it as a dependency and then performing a simple configuration step.

2.1 Installation

Since Spring Boot Database Admin is distributed on Maven, the easiest way to start is to include this dependency in your pom.xml:

<dependency>
	<groupId>tech.ailef</groupId>
	<artifactId>spring-boot-db-admin</artifactId>
	<version>0.1.5</version>
</dependency>

TIP Go to the Maven repository to retrieve the exact snippet for the latest stable release.

If you want the latest unstable release, you can clone the main branch of the Github repo and execute mvn install -D skipTests in the project's directory. This will install the library in your local repository, which you can then include using the same snippet as above, but replacing the version number with the one contained in the pom.xml file of the code you pulled from Github.

2.2 Configuration

After including the dependency, a few configuration steps are required on your end in order to integrate the library into your project.

The first one is configuring your application.properties file:

## The first-level part of the URL path: http://localhost:8080/${baseUrl}/
dbadmin.baseUrl=admin

## The package(s) that contain your @Entity classes
## accepts multiple comma separated values
dbadmin.modelsPackage=your.models.package,your.second.models.package

## At the moment, it's required to have open-in-view set to true.
# spring.jpa.open-in-view=true

## OPTIONAL PARAMETERS
## Whether to enable Spring Boot Database Admin
# dbadmin.enabled=true
#
## Set to true if you need to run the tests, as it will customize
## the database configuration for the internal DataSource
# dbadmin.testMode=false

After this, you must tell Spring to import the Spring Boot Database Admin configuration. To do this, annotate your @SpringBootApplication class containing the main method with the following:

@ImportAutoConfiguration(DbAdminAutoConfiguration.class)

This will autoconfigure the various Spring Boot Database Admin components when your application starts.

If everything is setup correctly, you will see Spring Boot Database Admin confirming it in the log messages that appear when you start your application. Keep in mind that if you specify the wrong models package, it will still work but provide you an empty interface. To check, visit http://localhost:8080/admin.

2.3 Supported features

2.3.1 Supported JPA annotations

  • Core: @Entity, @Table, @Column, @Lob, @Id
  • Relationships: @OneToMany, @ManyToOne, @ManyToMany, @OneToOne

The behaviour you specify with these annotations should be applied automatically by Spring Boot Database Admin as well. Keep in mind that using non-supported annotations will not necessarily result in an error, as they are simply ignored. Depending on what the annotation actually does, this could be just fine or result in an error if it interferes with something that Spring Boot Database Admin relies on.

2.3.2 Supported field types

  • Double, Float, Integer, Short, Byte, Character, BigDecimal, BigInteger
  • Boolean
  • String
  • Date, LocalDate, LocalDateTime, OffsetDateTime
  • byte[]

For these field types, the interface will be already customized. For example, a file upload input is provided to fill a byte[] field or a date-picker for the various date types.

Unsupported field types are handled as gracefully as possible, meaning that when such a field is detected the application will run anyway but this field will never be displayed in the web interface. This also means that it will not be possible to enter the value for this field when editing or creating, leaving it as the default NULL value. If the field is not nullable, you will thus not be able to create items.

If you think this field type should be supported, please open an issue on Github.

To check if your code contains unsupported fields:

  • In the Spring Boot Database Admin home page, a red icon is shown next to each table if problems have been detected; click this icon to get the detailed list of errors.
  • At startup, detected unsupported field types are printed in the logs (you should see some message if you grep DbAdmin).

3. Customization

There are two ways to customize the appearance and behaviour of Spring Boot Database Admin:

  1. Applying annotations on your @Entity classes, fields and methods
  2. Using the Settings panel through the web interface

Annotations are used primarily to customize behaviour and add custom logic to your classes. If, instead, you're looking to customize appearance of the web UI, it's most likley through the Settings panel.

3.1 Supported annotations

3.1.1 @DisplayName

@DisplayName
public String getFullName() {
    return firstName + " " + lastName;
}

When displaying a reference to an item, we show its primary key by default. If a class has a @DisplayName, this method will be used in addition to the primary key whenever possible, giving the user a more readable option.

3.1.2 @DisplayFormat

@DisplayFormat(format = "$%.2f")
private Double price;

Specify a format string to apply when displaying the field.

3.1.3 @ComputedColumn

Supported parameters
Name Type Required Description
name String false The name of this column in the web interface. The method's name is used if this value is not specified.
Code example
@ComputedColumn
public double totalSpent() {
	double total = 0;
	for (Order o : orders) {
		total += o.total();
	}
	return total;
}

This annotation can be used to add values computed at runtime that are shown like additional columns.

NOTE If your computed columns are computationally expensive (e.g because they use joins) they can affect the interface loading speed. In particular, the list view is the most affected, as these methods will get called for each item in the list.

3.1.4 @Filterable

Supported parameters
Name Required Type Description
type false Enum (DEFAULT, CATEGORICAL) If CATEGORICAL, this changes the filter in the UI to shows all the possible values directly instead of providing a autocomplete form.
Code example
@Filterable
private LocalDate createdAt;

@Filterable(type=FilterableType.CATEGORICAL)
@ManyToOne
private User user;

Place on one or more fields in a class to activate the faceted search feature. This will allow you to easily combine all these filters when operating on the table. Can only be placed on fields that correspond to physical columns on the table (e.g. no @ManyToMany/@OneToMany) and that are not binary (byte[]).

3.1.5 @DisplayImage

@DisplayImage
@Lob
private byte[] image;

This annotation can be placed on binary fields to declare they are storing an image and that we want it displayed when possible. The image will be shown as a small thumbnail.

3.1.6 @HiddenColumn

Code example
@HiddenColumn
private String cardNumber;

Marks a field as hidden. This column and its values will not be shown in the list and detail view for objects of this type. If the column is nullable, it will be hidden in the create and edit forms as well (and this will result in the column always being NULL when creating/editing objects). If, instead, it's not nullable column, it will be included in the create and edit forms as it would otherwise prevent the creation of items.

Please note that this is not meant as a security feature, but rather to hide uninformative columns that clutter the interface. In fact, since the create and edit form come pre-filled with all the information, these views will show the value of the hidden column (if it's not nullable).

3.1.7 @ReadOnly

Code example
@ReadOnly
private LocalDate createdAt;

Marks a field as read-only. The field can be filled at creation time, but it will be shown as disabled during edits, making it impossible to change its value after creation.

3.1.8 @DisableCreate, @DisableEdit, @DisableDelete

Code example
@Entity
@DisableCreate
public class Product { ... }

Disables the possibility of creating/editing/deleting items for the specific table.

3.2 The Settings panel

As mentioned earlier, the Settings panel primarily provides options to customize the branding/appearance of the web interface. These settings are persistent across restarts and are stored in an embedded H2 database (file named dbadmin_internal), along with other data required by Spring Boot Database Admin.

4. Security

Spring Boot Database Admin does not implement authentication and/or authorization mechanisms. However, you can use a standard Spring security configuration in order to limit access to the web UI or specific parts of it.

All Spring Boot Database Admin routes start with the value of dbadmin.baseUrl property, and all write operations (edit, create, delete) are implemented as POST calls. The following code provides an example security configuration (assuming Spring Boot Database Admin runs at /admin):

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    return http.authorizeHttpRequests(auth -> {
        // POST methods (create, edit and delete) require ADMIN role
        auth.requestMatchers(HttpMethod.POST, "/admin/**").hasAuthority("ADMIN")
            // Read-only Spring Boot Database Admin routes require authentication (any role)
            .requestMatchers("/admin/**").authenticated()
            // The other routes are not protected (adapt to your needs)
            .requestMatchers("/**").permitAll();
    })
    .formLogin(l -> l.loginPage("/login").permitAll())
    .build();
}