How to Setup CockroachDB Using Docker in Spring Boot with application.yml

July 07, 2025

#1

When building Spring Boot applications, managing configurations across different environments is essential. Using Docker for local development and Kubernetes for production ensures consistency and scalability. Spring Boot's profile-based configuration with application.yml allows for clean separation of settings between environments.
This guide focuses on setting up CockroachDB in a Spring Boot application, using Docker for development and Kubernetes for production. We'll utilize separate application-dev.yml and application-prod.yml files to manage configurations effectively.

1. Add Required Dependencies

Begin by adding the necessary dependencies to 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>

CockroachDB is compatible with PostgreSQL drivers, making integration straightforward.

2. Running CockroachDB with Docker for Development

To set up CockroachDB locally using Docker, execute:

docker run -d --name=cockroachdb \
  -p 26257:26257 -p 8080:8080 \
  cockroachdb/cockroach:v22.1.0 start-single-node --insecure

This command starts a single-node CockroachDB instance accessible at localhost:26257.

3. Configure application-dev.yml

Create an application-dev.yml file in src/main/resources/:

spring:
  datasource:
    url: jdbc:postgresql://localhost:26257/defaultdb?sslmode=disable
    username: root
    password:
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: update
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQL95Dialect
    show-sql: true

To run the application with the dev profile:

SPRING_PROFILES_ACTIVE=dev ./mvnw spring-boot:run

4. Production Configuration for Kubernetes

In production, it's best to manage sensitive configurations 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-public: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 for 'produser'
  spring.datasource.password: cHJvZHBhc3M=  # base64 for 'prodpass'

5. Configure application-prod.yml

In application-prod.yml, reference environment variables:

spring:
  datasource:
    url: ${SPRING_DATASOURCE_URL}
    username: ${SPRING_DATASOURCE_USERNAME}
    password: ${SPRING_DATASOURCE_PASSWORD}
    driver-class-name: ${SPRING_DATASOURCE_DRIVER_CLASS_NAME}
  jpa:
    hibernate:
      ddl-auto: ${SPRING_JPA_HIBERNATE_DDL_AUTO}
    properties:
      hibernate:
        dialect: ${SPRING_JPA_PROPERTIES_HIBERNATE_DIALECT}

6. Deploy Spring Boot App to Kubernetes

Define your Spring Boot deployment in Kubernetes:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: springboot-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: springboot-app
  template:
    metadata:
      labels:
        app: springboot-app
    spec:
      containers:
        - name: springboot-app
          image: your-image
          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

By leveraging Docker and Kubernetes alongside Spring Boot's profile-based configuration, you can maintain clear separation between development and production environments. This approach enhances security, scalability, and maintainability of your applications.
CockroachDB's compatibility with PostgreSQL drivers simplifies integration, allowing you to use familiar tools and configurations.

Note: Ensure that your Kubernetes cluster is properly set up and that CockroachDB is deployed securely for production environments.