Reference Guide

-

Spring Boot Database Admin v0.1.8

+

SnapAdmin v0.1.8

1. Introduction

-

Spring Boot Database Admin is a tool to easily build customizable database management interfaces with CRUD operations (and more!) for Spring Boot+JPA apps.

+

SnapAdmin is a tool to easily build customizable database management interfaces with CRUD operations (and more!) for Spring Boot+JPA apps.

It does so by scanning your JPA-annotated @Entity classes and building the required functionality at runtime. Since it won't generate actual code you won't have to change your existing code base, and this makes it easy to integrate. Moreover, every time you update your classes, all changes will be reflected automatically on the web UI.

On the other hand, this approach requires to interact correctly with all JPA annotations and adapt our behaviour accordingly. This is not an easy task given the large surface area of possible behaviours introduced with annotations and can sometimes introduce bugs. If you encounter problems, please report it as an issue on Github.

-

The rest of this guide outlines how to install, configure and customize Spring Boot Database Admin and, where applicable, it documents known interactions with JPA annotations.

+

The rest of this guide outlines how to install, configure and customize SnapAdmin and, where applicable, it documents known interactions with JPA annotations.

2. Getting started

-

Getting started with Spring Boot Database Admin requires including it as a dependency and minimal configuration.

+

Getting started with SnapAdmin requires including it as a dependency and minimal configuration.

2.1 Installation

-

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

+

Since SnapAdmin is distributed on Maven, the easiest way to start is to include it in your pom.xml:

 <dependency>
@@ -106,7 +106,7 @@ dbadmin.modelsPackage=your.models.package,your.second.models.package
 # spring.jpa.open-in-view=true
 
 ## OPTIONAL PARAMETERS
-## Whether to enable Spring Boot Database Admin
+## Whether to enable SnapAdmin
 # dbadmin.enabled=true
 #
 ## Set to true if you need to run the tests, as it will customize
@@ -118,15 +118,15 @@ dbadmin.modelsPackage=your.models.package,your.second.models.package
-

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:

+

After this, you must tell Spring to import the SnapAdmin 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. Visit http://localhost:8080/admin (replace the correct port and base path with your settings) to check if everything is working correctly.

+

This will autoconfigure the various SnapAdmin components when your application starts.

+

If everything is setup correctly, you will see SnapAdmin 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. Visit http://localhost:8080/admin (replace the correct port and base path with your settings) to check if everything is working correctly.

2.2.1 Known issues

    @@ -141,9 +141,9 @@ dbadmin.modelsPackage=your.models.package,your.second.models.package
  • Relationships: @OneToMany, @ManyToOne, @ManyToMany, @OneToOne
  • Validation: all JPA validation annotations (jakarta.validation.constraints.*)
-

The behaviours specified with these annotations should be applied automatically by Spring Boot Database Admin. 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.

+

The behaviours specified with these annotations should be applied automatically by SnapAdmin. 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 SnapAdmin relies on.

-

The following list documents the most significant interactions between the JPA annotations and Spring Boot Database Admin.

+

The following list documents the most significant interactions between the JPA annotations and SnapAdmin.

@Entity

Used to detect the candidate classes to scan.

@Column
@@ -169,13 +169,13 @@ dbadmin.modelsPackage=your.models.package,your.second.models.package

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.
    • +
  • In the SnapAdmin 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, unsupported field types are printed in the logs (you should see them if you grep DbAdmin).

3. Customization

-

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

+

There are two ways to customize the appearance and behaviour of SnapAdmin:

  1. Applying annotations on your @Entity classes, fields and methods
  2. Using the Settings panel through the web interface
    3. @@ -336,7 +336,7 @@ public class User { ... } public class Payment { ... } -

    Disables Spring Boot Database Admin on this table, by ignoring it during the initialization phase.

    +

    Disables SnapAdmin on this table, by ignoring it during the initialization phase.

    @@ -344,11 +344,11 @@ public class Payment { ... }

    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.

    +

    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 SnapAdmin.

    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):

    +

    SnapAdmin 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 SnapAdmin 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 SnapAdmin runs at /admin):

    @@ -357,7 +357,7 @@ 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)
+            // Read-only SnapAdmin routes require authentication (any role)
             .requestMatchers("/admin/**").authenticated()
             // The other routes are not protected (adapt to your needs)
             .requestMatchers("/**").permitAll();
@@ -369,7 +369,7 @@ public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 
    
 
    5. Troubleshooting
    
 
-
    When setting up Spring Boot Database Admin for the first time, problems most commonly occur at startup, causing the application to stop. If this is the case, first check that you have correctly configured your application.properties file. If everything is correct here, the problem might be related to one or more of your @Entity classes (or the rest of your code in general) which might be using some unsupported feature and/or annotation. 
    
+
    When setting up SnapAdmin for the first time, problems most commonly occur at startup, causing the application to stop. If this is the case, first check that you have correctly configured your application.properties file. If everything is correct here, the problem might be related to one or more of your @Entity classes (or the rest of your code in general) which might be using some unsupported feature and/or annotation. 
    
 
    
 You can enable DEBUG-level logs (e.g. with logging.level.root=DEBUG) to pinpoint the cause error. Looking at those in combination with the stack trace should provide enough information to understand what is going wrong. Keep in mind that if the application doesn't start at all, it's probably a bug: you can open an issue on Github, providing the stacktrace, the debug logs and all other relevant information.