Spring Cloud Config’s JDBC backend stores application properties in your database, providing a simple method to serve configuration properties to all your Spring Boot apps.
Client → Config Server → Oracle DBThis article walks through using the JDBC backend for Oracle Database. You’ll learn how JDBC-based configuration works, how to set up the required table and database objects, and how to get your Spring Config server/clients reading properties directly from the database.
If you’d prefer to skip the article and head straight to the code, click here.
Prerequisites
- Java 21+
- Maven
- Docker-compatible environment
Clone the project code
Clone the sample project here: https://github.com/anders-swanson/oracle-database-code-samples/tree/main/spring-cloud-config.
This project contains client/server modules for Spring Cloud Config, and a docker-compose script that sets up an Oracle AI Database server to use a JDBC backend.
Directory Structure
- client/: The Spring Boot client application that fetches configurations from the server.
- server/: The Spring Cloud Config Server application with JDBC backend.
- oracle/: Initialization scripts for the database (e.g., grant_permissions.sql to create user and PROPERTIES table).
- docker-compose.yml: Docker Compose file to spin up an Oracle Database instance.
- crud-properties.md: Additional documentation on using the CRUD API for managing properties.
Start the database container
We’ll use an Oracle AI Database Free container for the Spring Cloud Config JDBC backend. From the spring-cloud-config directory, run the docker-compose file to start a database container :
docker-compose up -dThis starts the configdb database container on localhost:1527 with PDB freepdb1. The init script in oracle/grant_permissions.sql automatically creates the testuser user (password: testpwd) and the PROPERTIES table for Spring Cloud Config.
Run the client/server example
Start the Spring Cloud Config server
Navigate to the server directory and start the Spring Cloud Config server:
mvn clean compile spring-boot:runThe server runs on http://localhost:8888 (configured in server/src/main/resources/application.yaml). It uses JDBC to connect to the database at jdbc:oracle:thin:@localhost:1527/freepdb1 with credentials testuser/testpwd.
Insert a configuration property
Use SQL or the optional CRUD API (exposed at /api/properties) to add a property to the PROPERTIES table. Example request:
curl -X POST http://localhost:8888/api/properties \
-H "Content-Type: application/json" \
-d '{
"application": "myapp",
"profile": "dev",
"label": "latest",
"propKey": "config.key",
"value": "config-value"
}'Example row inserted into the PROPERTIES table:
| ID | APPLICATION | PROFILE | LABEL | PROP_KEY | VALUE |
|---|---|---|---|---|---|
| 1 | myapp | dev | latest | config.key | config-value |
Start a client app
Navigate to the client directory and start the client application:
mvn clean compile spring-boot:runThe client is configured (in client/src/main/resources/application.yaml) to fetch from http://localhost:8888 with application name myapp and active profile dev. It injects ${config.key} in Controller.java.
Verify configuration properties
Once the client is running (default port 8080), access:
curl http://localhost:8080/valueThis should return the value from the config server, e.g., “This is my config value: config-value”.
You can also view the server properties as JSON in your browser by accessing http://localhost:8888/myapp/dev/latest:
{
"name": "myapp",
"profiles": [
"dev"
],
"label": "latest",
"version": null,
"state": null,
"propertySources": [
{
"name": "myapp-dev",
"source": {
"config.key": "config-value"
}
}
]
}You now have a working Spring Cloud Config client/server environment, backed by Oracle Database!
[Optional] Dive into the config server configuration
Spring Cloud Config servers need their own configuration! In this section, we walk through the required settings for a JDBC backend using Spring Cloud Config.
Dependencies
In the config server pom.xml, we need the spring-cloud-config-server, spring-boot-starter-data-jdbc, and oracle-spring-boot-starter-ucp dependencies. These modules set up the app as a Spring Cloud Config server, and connect over JDBC with an Oracle UCP connection pool:
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-config-server</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jdbc</artifactId>
</dependency>
<dependency>
<groupId>com.oracle.database.spring</groupId>
<artifactId>oracle-spring-boot-starter-ucp</artifactId>
<version>${oracle.starters.version}</version>
</dependency>Application Properties
Then, we have to configure our application to connect to Oracle Database. The config server properties file looks like this:
spring:
cloud:
config:
server:
jdbc:
enabled: true
sql: SELECT PROP_KEY, VALUE from PROPERTIES where APPLICATION=? and PROFILE=? and LABEL=?
enabled: true
application:
name: OracleConfigServer
datasource:
username: testuser
password: testpwd
# Docker compose Oracle Free container
url: jdbc:oracle:thin:@localhost:1527/freepdb1
# Set these to use UCP over Hikari.
driver-class-name: oracle.jdbc.OracleDriver
type: oracle.ucp.jdbc.PoolDataSource
oracleucp:
initial-pool-size: 1
min-pool-size: 1
max-pool-size: 30
connection-pool-name: ${spring.application.name}
connection-factory-class-name: oracle.jdbc.pool.OracleDataSource
profiles:
active: jdbc
server:
port: 8888
Properties Table
Spring Cloud Config’s JDBC backend uses the PROPERTIES table to store and load application settings:
create table PROPERTIES (
id number generated always as identity primary key,
application varchar2(255),
profile varchar2(255),
label varchar2(255),
-- the default is "key", but this is a reserved keyword
-- in most databases, Oracle included, so we use "prop_key" instead
prop_key varchar2(255),
value varchar2(255)
);You can customize the table as needed. For example, we use prop_key instead of key for a column name in the config server properties.
@EnableConfigServer annotation
To run the application as a Spring Cloud Config server, we just need to apply the @EnableConfigServer annotation to our main class:
@SpringBootApplication
@EnableConfigServer
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}Our sample app also provides a HTTP CRUD API for database configurations, though this is completely optional and not required for Spring Cloud Config.
You can find the HTTP operations listed here: crud_properties.md
Summary
The JDBC backend for Spring Cloud Config gives you a simple, reliable way to centralize your application settings in Oracle Database. With a table, a query, and a few config properties you gain a flexible source of truth for all your Spring apps.
Use the JDBC backend when you want dynamic updates, centralized config storage, or when your deployment environment doesn’t have access to a Git repo.
This demo uses Oracle AI Database Free, but the same configuration works with any Oracle Database edition. Oracle AI Database also provides JSON duality views and REST services, which pair naturally with Spring Cloud Config for building modern microservices.
Leave a Reply