CockroachDB, a resilient, distributed SQL database, works well with Spring Boot—especially because it’s compatible with the PostgreSQL JDBC driver. Whether you're working locally with Docker or deploying to production on Kubernetes, managing configurations through Spring Boot's
application.properties
files using active profiles (
dev
and
prod
) keeps your setup organized and environment-aware.
This article walks through how to configure CockroachDB with Spring Boot using
application-dev.properties
for local development and
application-prod.properties
for production, where secrets and configuration are managed via Kubernetes.
Step 1: Add the Necessary Dependencies
Include the following in your
pom.xml
:
<dependencies>
<!-- Spring Boot Starters -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<!-- PostgreSQL Driver for CockroachDB -->
<dependency>
<groupId>org.postgresql</groupId>
<artifactId>postgresql</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>
Spring Boot uses this driver to connect with CockroachDB via PostgreSQL protocol.
Step 2: Spin Up CockroachDB with Docker (Dev)
For local testing, you can quickly start CockroachDB using Docker:
docker run -d --name cockroachdb \
-p 26257:26257 -p 8080:8080 \
cockroachdb/cockroach:v22.1.0 start-single-node --insecure
This command launches a single-node, insecure cluster for development, accessible via port
26257
.
Step 3: Create application-dev.properties
Now, configure Spring Boot to use CockroachDB when the
dev
profile is active:
spring.datasource.url=jdbc:postgresql://localhost:26257/defaultdb?sslmode=disable
spring.datasource.username=root
spring.datasource.password=
spring.datasource.driver-class-name=org.postgresql.Driver
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQL95Dialect
You can launch your Spring Boot app using this configuration with:
SPRING_PROFILES_ACTIVE=dev ./mvnw spring-boot:run
Step 4: Prepare Kubernetes for Production
For production deployments, keep your configuration secure and externalized using Kubernetes ConfigMaps and Secrets.
4.1: Create a ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
name: cockroachdb-config
data:
spring.datasource.url: jdbc:postgresql://cockroachdb-service:26257/proddb?sslmode=disable
spring.datasource.driver-class-name: org.postgresql.Driver
spring.jpa.hibernate.ddl-auto: validate
spring.jpa.properties.hibernate.dialect: org.hibernate.dialect.PostgreSQL95Dialect
4.2: Create a Secret
apiVersion: v1
kind: Secret
metadata:
name: cockroachdb-secret
type: Opaque
data:
spring.datasource.username: cHJvZHVzZXI= # base64 encoded 'produser'
spring.datasource.password: cHJvZHBhc3M= # base64 encoded 'prodpass'
Step 5: Create application-prod.properties
In your
application-prod.properties
, reference the values from environment variables:
spring.datasource.url=${SPRING_DATASOURCE_URL}
spring.datasource.username=${SPRING_DATASOURCE_USERNAME}
spring.datasource.password=${SPRING_DATASOURCE_PASSWORD}
spring.datasource.driver-class-name=${SPRING_DATASOURCE_DRIVER_CLASS_NAME}
spring.jpa.hibernate.ddl-auto=${SPRING_JPA_HIBERNATE_DDL_AUTO}
spring.jpa.properties.hibernate.dialect=${SPRING_JPA_PROPERTIES_HIBERNATE_DIALECT}
Step 6: Kubernetes Deployment with Environment Variables
In your Kubernetes Deployment YAML, inject the configuration from your ConfigMap and Secret:
env:
- name: SPRING_PROFILES_ACTIVE
value: prod
- name: SPRING_DATASOURCE_URL
valueFrom:
configMapKeyRef:
name: cockroachdb-config
key: spring.datasource.url
- name: SPRING_DATASOURCE_DRIVER_CLASS_NAME
valueFrom:
configMapKeyRef:
name: cockroachdb-config
key: spring.datasource.driver-class-name
- name: SPRING_JPA_HIBERNATE_DDL_AUTO
valueFrom:
configMapKeyRef:
name: cockroachdb-config
key: spring.jpa.hibernate.ddl-auto
- name: SPRING_JPA_PROPERTIES_HIBERNATE_DIALECT
valueFrom:
configMapKeyRef:
name: cockroachdb-config
key: spring.jpa.properties.hibernate.dialect
- name: SPRING_DATASOURCE_USERNAME
valueFrom:
secretKeyRef:
name: cockroachdb-secret
key: spring.datasource.username
- name: SPRING_DATASOURCE_PASSWORD
valueFrom:
secretKeyRef:
name: cockroachdb-secret
key: spring.datasource.password
This ensures that Spring Boot automatically picks up your CockroachDB configuration in production.
Step 7: Test Your Integration
After deployment, validate your connection. You might use a basic controller like this:
@RestController
public class TestController {
@Autowired
private EntityManager entityManager;
@GetMapping("/health")
public String checkDb() {
return "DB connected: " + entityManager.isOpen();
}
}
Accessing
/health
should confirm that Spring Boot successfully connects to CockroachDB.
CockroachDB's PostgreSQL compatibility makes it an excellent fit for Spring Boot apps. By using Docker for dev and Kubernetes for prod, along with profile specific
application.properties
files, you can maintain clean, secure, and scalable configurations.
This setup helps avoid hardcoded values, eases local development, and ensures production resilience, all while keeping your Spring Boot app organized and cloud-ready.
image quote pre code