Database Configuration

1. Overview

The Service API uses an external relational database to store application data, including transaction records, device information, and user credentials. The application supports MySQL and Oracle database systems, provided that the appropriate JDBC driver is included in the project dependencies (for example, com.mysql.cj.jdbc.Driver or oracle.jdbc.OracleDriver).

The application does not create this database; it relies on an existing instance configured and maintained externally or manually via SQL scripts provided with the application.

Spring Boot configuration properties are used to define the data source for application-level persistence. These properties are automatically recognized by Spring without requiring additional setup.

The database is designed to be lightweight and focused on the core functionality of the Service API.

2. Configuration

Service API now ships two dedicated Spring profiles: application-mysql.yml and application-oracle.yml. Select the profile through SPRING_PROFILES_ACTIVE (or spring.profiles.active) and Spring Boot will load one of the following configurations.

2.1. MySQL Profile

application-mysql.yml
spring:
  datasource:
    jdbc-url: ${MYSQL_JDBC_URL:jdbc:mysql://${MYSQL_HOST:${DB_HOST:localhost}}:${MYSQL_PORT:3306}/${MYSQL_SCHEMA:ftacs}?allowPublicKeyRetrieval=true&useUnicode=true&characterEncoding=UTF-8&useSSL=false&serverTimezone=UTC}
    username: ${MYSQL_USER:ftacs}
    password: ${MYSQL_PASSWORD:ftacs}
    driver-class-name: ${MYSQL_DRIVER_CLASS_NAME:com.mysql.cj.jdbc.Driver}
    hikari:
      maximum-pool-size: ${DB_MAX_POOL_SIZE:10}
      minimum-idle: ${DB_MIN_IDLE:5}
      connection-timeout: ${DB_CONNECTION_TIMEOUT_MS:30000}

2.2. Oracle Profile

application-oracle.yml
spring:
  datasource:
    jdbc-url: ${ORACLE_JDBC_URL:jdbc:oracle:thin:@//${ORACLE_HOST:${DB_HOST:localhost}}:${ORACLE_PORT:1521}/${ORACLE_SERVICE:XEPDB1}}
    username: ${ORACLE_USER:ftacs}
    password: ${ORACLE_PASSWORD:ftacs}
    driver-class-name: ${ORACLE_DRIVER_CLASS_NAME:oracle.jdbc.OracleDriver}
    hikari:
      maximum-pool-size: ${DB_MAX_POOL_SIZE:10}
      minimum-idle: ${DB_MIN_IDLE:5}
      connection-timeout: ${DB_CONNECTION_TIMEOUT_MS:30000}

2.3. Environment Variables

2.3.1. Shared pool settings

Variable Description

DB_MAX_POOL_SIZE

Upper bound for the datasource pool. Default 10.

DB_MIN_IDLE

Minimum warm connections in the pool. Default 5.

DB_CONNECTION_TIMEOUT_MS

How long to wait for a connection before failing a request. Default 30000 ms.

DB_HOST

Fallback hostname used by the profile-specific variables.

2.3.2. MySQL profile variables

Variable Description

MYSQL_JDBC_URL

Full JDBC override. Leave empty to synthesize one from host/port/schema.

MYSQL_HOST / MYSQL_PORT

Hostname and port of the MySQL server. Defaults: localhost, 3306.

MYSQL_SCHEMA

Schema name for the Service API tables. Default ftacs.

MYSQL_USER / MYSQL_PASSWORD

Credentials for the database. Default ftacs/ftacs.

MYSQL_DRIVER_CLASS_NAME

JDBC driver class (com.mysql.cj.jdbc.Driver).

2.3.3. Oracle profile variables

Variable Description

ORACLE_JDBC_URL

Full Oracle JDBC string (jdbc:oracle:thin:@//host:port/service). Overrides host/port/service variables.

ORACLE_HOST / ORACLE_PORT

Listener endpoint. Defaults: localhost, 1521.

ORACLE_SERVICE

Oracle service or SID. Default XEPDB1.

ORACLE_USER / ORACLE_PASSWORD

Credentials for the database. Default ftacs.

ORACLE_DRIVER_CLASS_NAME

JDBC driver class (oracle.jdbc.OracleDriver).

3. Defining DataSource Bean

A @Configuration class defines the datasource bean using HikariCP:

@Configuration
public class DatabaseConfig {

    @Primary
    @Bean
    @ConfigurationProperties("spring.datasource")
    public DataSource dataSource() {
        return DataSourceBuilder.create().type(HikariDataSource.class).build();
    }
}

The dataSource bean is configured with properties under spring.datasource.* and marked with @Primary to be the default data source for the application.