How to Configure CockroachDB in Struts

August 11, 2025

If you're building a Java web application with Struts and need a resilient, scalable SQL solution, CockroachDB is an excellent choice. Its distributed architecture means you get high availability and strong consistency. In this guide, we'll see how to integrate CockroachDB into a Struts project—using Docker for local dev, Kubernetes for production, and environment-driven configuration to keep things clean.

1. Add Dependencies in `pom.xml`

To get started, include Struts, the PostgreSQL-compatible JDBC driver (CockroachDB uses the same driver), and optional Kubernetes support:

<dependencies>
  <!-- Struts framework -->
  <dependency>
    <groupId>org.apache.struts</groupId>
    <artifactId>struts2-core</artifactId>
    <version>${struts.version}</version>
  </dependency>

  <!-- PostgreSQL driver (compatible with CockroachDB) -->
  <dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>${postgresql.version}</version>
  </dependency>

  <!-- Kubernetes client (optional for production) -->
  <dependency>
    <groupId>io.fabric8</groupId>
    <artifactId>kubernetes-client</artifactId>
    <version>${fabric8.version}</version>
  </dependency>
</dependencies>

This setup gives your Struts app JDBC connectivity with CockroachDB and the ability to support Kubernetes deployment.

2. Run CockroachDB Locally with Docker

Use Docker Compose to spin up a CockroachDB cluster for local testing:

version: '3'
services:
  cockroach:
    image: cockroachdb/cockroach:v23.2.6
    command: start-single-node --insecure --listen-addr=0.0.0.0
    ports:
      - "26257:26257"
      - "8080:8080" # Web UI

Then run

docker-compose up -d

CockroachDB will be ready at localhost:26257, and its admin UI at http://localhost:8080.

3. Create Dev Configuration: `cockroach-dev.properties`

Add this in src/main/resources:

db.driver=org.postgresql.Driver
db.url=jdbc:postgresql://localhost:26257/defaultdb?sslmode=disable
db.user=root
db.password=
db.validationQuery=SELECT 1

Load it in Struts helper or DAO:

Properties props = new Properties();
props.load(getClass().getResourceAsStream("/cockroach-dev.properties"));

Class.forName(props.getProperty("db.driver"));
Connection conn = DriverManager.getConnection(
    props.getProperty("db.url"),
    props.getProperty("db.user"),
    props.getProperty("db.password")
);
conn.createStatement().executeQuery(props.getProperty("db.validationQuery"));

You're now connected and ready to develop.

4. Prepare Kubernetes Config for Production

To configure CockroachDB in Kubernetes securely:

kubectl create configmap cockroach-config \
  --from-literal=DB_URL=jdbc:postgresql://cockroach-service:26257/proddb?sslmode=disable \
  --from-literal=DB_DRIVER=org.postgresql.Driver \
  --from-literal=DB_VALIDATION_QUERY=SELECT 1

kubectl create secret generic cockroach-secret \
  --from-literal=DB_USER=produser \
  --from-literal=DB_PASSWORD=prodPass123

These store connection settings outside of your application code.

5. Create Production Configuration: `cockroach-prod.properties`

Add the file to your JAR:

db.driver=${DB_DRIVER}
db.url=${DB_URL}
db.user=${DB_USER}
db.password=${DB_PASSWORD}
db.validationQuery=${DB_VALIDATION_QUERY}

At runtime, Struts helper or DAO will load environment variables.

6. Kubernetes Deployment Example

Ensure your application Container spec includes:

env:
  - name: DB_DRIVER
    valueFrom:
      configMapKeyRef:
        name: cockroach-config
        key: DB_DRIVER
  - name: DB_URL
    valueFrom:
      configMapKeyRef:
        name: cockroach-config
        key: DB_URL
  - name: DB_VALIDATION_QUERY
    valueFrom:
      configMapKeyRef:
        name: cockroach-config
        key: DB_VALIDATION_QUERY
  - name: DB_USER
    valueFrom:
      secretKeyRef:
        name: cockroach-secret
        key: DB_USER
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: cockroach-secret
        key: DB_PASSWORD

Add the cockroach-prod.properties to your deployment JAR. The Struts app then reads settings at runtime.

7. Sample Struts Action for Health Check

public class DbHealthAction extends ActionSupport {
  public String execute() {
    try (Connection conn = DriverManager.getConnection(
            System.getenv("DB_URL"),
            System.getenv("DB_USER"),
            System.getenv("DB_PASSWORD"));
         Statement stmt = conn.createStatement()) {
      stmt.executeQuery(System.getenv("DB_VALIDATION_QUERY"));
      addActionMessage("Connected to CockroachDB successfully!");
      return SUCCESS;
    } catch (Exception e) {
      addActionError("Connection failed: " + e.getMessage());
      return ERROR;
    }
  }
}

No code changes are needed for dev vs production—just switch .properties.

Why This Setup Works

Docker for dev: Quick local testing with self-hosted CockroachDB.
Kubernetes for prod: Secure config management with ConfigMaps and Secrets.
One codebase: Consistent connectivity logic across environments.
Clear separation: cockroach-dev.properties vs cockroach-prod.properties.

With Docker-powered local testing and Kubernetes-managed production configuration, your Struts application is perfectly set up to work with CockroachDB—bringing you the benefits of distributed SQL without configuration headaches. It’s time to build web applications that are resilient, scalable, and ready for real world deployment.

1. Add Dependencies in pom.xml