Spring Boot Meets Kingbase: Layered Configs, Startup Checks, and the Errors That Kill Prod

Spring Boot Connecting to Kingbase Database: Configuration Layering, Startup Self-Check, and Common Errors

A JDBC single-file program is suitable for verifying the link, but real business systems are mostly Spring Boot applications. Connecting to a database in Spring Boot seems like just writing a few lines in application.yml, but in reality, the most problems after going live come from these very configurations: wrong URLs, mixed-up accounts, unsuitable default connection pool values, environment configurations getting crossed, and no database self-check at startup.

This article, based on a Windows 11 local development environment and a CentOS 7.6 database server, demonstrates how a Spring Boot project connects to a Kingbase database and splits the configuration into a maintainable way. The kb_app, shop, app_user, and shop.t_connection_check mentioned in the text reuse the objects created in the first article.

@[toc]

I. Experiment Objectives

This article accomplishes the following objectives:

Configure a Kingbase database connection in Spring Boot.
Use independent environment configurations to distinguish development, testing, and production.
Add a startup self-check to confirm database availability when the application starts.
Sort out the troubleshooting sequence for common connection errors.

Example environment (the IPs in the table are only examples; replace them with your own server addresses when using):

Windows 11 Local Development Machine
    |
    | JDBC
    v
CentOS 7.6 Database Server: 192.168.10.101:54321
Database: kb_app
Account: app_user
Schema: shop

II. Preparing Project Dependencies

If the driver has already been added to the enterprise internal Maven repository, you can directly import it using the internal coordinates. If not yet, you can first install the driver jar to the local repository. This article continues using the kingbase8-9.0.0.jar found in the first article:

mvn install:install-file `
  -Dfile=D:\Tools\Kingbase\KESV9R2C13\KES\KESRealPro\V009R002C013\Interface\jdbc\kingbase8-9.0.0.jar `
  -DgroupId=com.kingbase `
  -DartifactId=kingbase8 `
  -Dversion=9.0.0 `
  -Dpackaging=jar

Import in pom.xml:

<dependency>
    <groupId>com.kingbase</groupId>
    <artifactId>kingbase8</artifactId>
    <version>9.0.0</version>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jdbc</artifactId>
</dependency>

If your project uses MyBatis, JPA, or other data access frameworks, the underlying layer still relies on DataSource and JDBC connections, so the configuration approach in this article is still applicable.

III. Basic Connection Configuration

Configure the development environment connection in application-dev.yml:

spring:
  datasource:
    url: jdbc:kingbase8://192.168.10.101:54321/kb_app
    username: app_user
    password: App_user_123
    driver-class-name: com.kingbase8.Driver

A few points to note:

The IP in the url is the CentOS 7.6 database server address.
The driver class for the kingbase8-9.0.0.jar used in this article is com.kingbase8.Driver; if the driver package is changed later, refer to the actual driver documentation.
Do not write passwords in plain text in production configurations; they should be handed over to environment variables, configuration centers, or key management tools later.

Specify the development configuration at startup:

mvn spring-boot:run -Dspring-boot.run.profiles=dev

Run after packaging:

java -jar kb-app-demo.jar --spring.profiles.active=dev

IV. Writing a Minimal Query Endpoint

To verify that the application can actually access the database, you can write a simple Repository:

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Repository;

@Repository
public class ConnectionCheckRepository {

    private final JdbcTemplate jdbcTemplate;

    public ConnectionCheckRepository(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    public String findCheckName(Integer id) {
        return jdbcTemplate.queryForObject(
                "select check_name from shop.t_connection_check where id = ?",
                String.class,
                id
        );
    }
}

Then write a Controller:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ConnectionCheckController {

    private final ConnectionCheckRepository repository;

    public ConnectionCheckController(ConnectionCheckRepository repository) {
        this.repository = repository;
    }

    @GetMapping("/db/check")
    public String check(@RequestParam(defaultValue = "1") Integer id) {
        return repository.findCheckName(id);
    }
}

After starting the application, visit:

http://localhost:8080/db/check?id=1

If it returns jdbc_check_ready, it means Spring Boot has successfully accessed the remote Kingbase database via JDBC.

V. Adding a Startup Self-Check

Many systems consider the service normal as long as the port is up at startup. But in reality, if the database connection fails, even if the application starts successfully, the first business request will expose the problem. It is recommended to add a startup self-check to bring the risk forward to the startup phase.

import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;

@Component
public class DatabaseStartupChecker implements ApplicationRunner {

    private final JdbcTemplate jdbcTemplate;

    public DatabaseStartupChecker(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    @Override
    public void run(ApplicationArguments args) {
        String result = jdbcTemplate.queryForObject(
                "select current_database() || ',' || current_user",
                String.class
        );
        System.out.println("database startup check: " + result);
    }
}

This self-check does not require complex SQL; just getting the current database name and username is sufficient. In a production environment, it is recommended to hand over the output to a logging framework, and if the self-check fails, the application should exit directly rather than starting up in a faulty state.

VI. Splitting Configuration by Environment

Do not pile connection strings for all environments into one file. It is recommended to split them like this:

application.yml
application-dev.yml
application-test.yml
application-prod.yml

application.yml only keeps common configurations:

spring:
  application:
    name: kb-app-demo

application-dev.yml:

spring:
  datasource:
    url: jdbc:kingbase8://192.168.10.101:54321/kb_app
    username: app_user
    password: App_user_123

application-prod.yml:

spring:
  datasource:
    url: ${KB_DB_URL}
    username: ${KB_DB_USER}
    password: ${KB_DB_PASSWORD}

Inject environment variables at production runtime:

export KB_DB_URL='jdbc:kingbase8://10.10.20.15:54321/kb_app'
export KB_DB_USER='app_user'
export KB_DB_PASSWORD='your_production_password'
java -jar kb-app-demo.jar --spring.profiles.active=prod

This reduces the risk of writing production passwords into the code repository.

VII. Don't Ignore the Default Schema Issue

Many applications run fine locally but report that a table does not exist after switching environments. The actual reason is often simply that the SQL did not write the Schema.

It is recommended to explicitly write it in SQL:

select * from shop.t_connection_check where id = ?

Instead of:

select * from t_connection_check where id = ?

If the team really needs to rely on the default Schema, explicit verification must be done at application startup to avoid inconsistent behavior across different environments.

VIII. Common Error Troubleshooting

1. Failed to configure a DataSource

Check whether the JDBC dependency is imported, whether spring.datasource.url is configured, and whether the correct profile is specified.

2. No suitable driver

Check whether the JDBC driver is on the classpath and whether the connection string prefix matches the driver.

3. Connection refused

Go back to the environment baseline check. Focus on the CentOS firewall, database listening address, port, and security group.

4. FATAL or authentication failure

Check the account password, target database, and access control rules. Do not bypass by directly switching to a high-privilege account.

5. Table does not exist at SQL runtime

Prioritize checking the Schema. Application SQL is recommended to explicitly write the shop. prefix.

IX. Logs Recommended to Keep Before Going Live

At least output the following information during the application startup phase:

The currently active profile.
Desensitized information of the database connection address.
The current database name.
The current connected user.
The maximum number of connections in the connection pool.
Whether the startup self-check passed.

Passwords must never be printed in the logs.

X. Summary

The key to connecting Spring Boot to a Kingbase database is not just writing the URL in, but making the configuration layerable, the connection verifiable, and the problems traceable. In the development environment, first establish the link from Windows 11 to CentOS 7.6, and in the production environment, use profiles, environment variables, and startup self-checks to bring risks forward to the startup phase.

In the next article, we will enter connection pool governance, focusing on how to configure HikariCP's maximum connections, idle connections, timeouts, and leak detection.