Documentation

Quick Start Guide

Get up and running in 5 minutes

Step 1: Start the OJP Server

The easiest way to get started is using Docker:

docker run --rm -d --network host rrobetti/ojp:0.4.2-beta

For production deployments, you can also run as a standalone JAR or deploy to Kubernetes.

Step 2: Add the OJP JDBC Driver

For Maven projects, add this dependency to your pom.xml:

                    <dependency>

    <groupId>org.openjproxy</groupId>

    <artifactId>ojp-jdbc-driver</artifactId>

    <version>0.4.2-beta</version>

</dependency>

For Gradle projects:

implementation 'org.openjproxy:ojp-jdbc-driver:0.4.2-beta'

Spring Boot users: use spring-boot-starter-ojp instead — it includes the driver and auto-configures the datasource. See the Spring Boot integration guide; steps 3 and 4 below are not required.

Step 3: Update Your JDBC Configuration

Update your database driver class:

org.openjproxy.jdbc.Driver

Update your JDBC URL by prefixing it with OJP connection info:

                    // PostgreSQL

jdbc:ojp[localhost:1059]_postgresql://user@localhost:5432/mydb

// MySQL

jdbc:ojp[localhost:1059]_mysql://localhost:3306/mydb

// Oracle

jdbc:ojp[localhost:1059]_oracle:thin:@localhost:1521/XEPDB1

// SQL Server

jdbc:ojp[localhost:1059]_sqlserver://localhost:1433;databaseName=mydb

Step 4: Run Your Application

That's it! Your application now benefits from:

Central connection pooling
Protection from connection storms
Circuit breakers and backpressure
Query monitoring and observability
Elastic scaling support

Configuration

Customize OJP for your environment

Server Configuration

Configure the OJP server with environment variables or configuration files:

OJP_PORT: Server port (default: 1059)
OJP_MAX_CONNECTIONS: Max pool size
OJP_CONNECTION_TIMEOUT: Timeout in ms
OJP_IDLE_TIMEOUT: Idle timeout
OJP_LOG_LEVEL: Logging level

Connection Pool Tuning

Fine-tune HikariCP pool settings for optimal performance:

Maximum pool size
Minimum idle connections
Connection timeout
Idle timeout
Max lifetime
Leak detection threshold

Security Settings

Configure security and authentication:

TLS/SSL encryption
Client authentication
Database credentials
Network security
Access control

Framework Integration

Works seamlessly with popular Java frameworks

Spring Boot

Use the OJP Spring Boot Starter (recommended) for zero-configuration setup. Replace spring-boot-starter-jdbc in your pom.xml:

                        <dependency>

    <groupId>org.openjproxy</groupId>

    <artifactId>spring-boot-starter-ojp</artifactId>

    <version>0.4.2-beta</version>

</dependency>

Then set your connection URL in application.properties:

                        spring.datasource.url=jdbc:ojp[localhost:1059]_postgresql://localhost/mydb

spring.datasource.username=user

spring.datasource.password=secret

The starter automatically configures the driver class and SimpleDriverDataSource. For projects that cannot use the starter, see the Spring Boot integration guide.

Jakarta EE / Java EE

Configure data source in your application server:

                        <data-source>

  <driver>org.openjproxy.jdbc.Driver</driver>

  <url>jdbc:ojp[localhost:1059]_...</url>

</data-source>

Quarkus

Add OJP configuration to application.properties:

                        quarkus.datasource.db-kind=postgresql

quarkus.datasource.jdbc.driver=org.openjproxy.jdbc.Driver

quarkus.datasource.jdbc.url=jdbc:ojp[localhost:1059]_...

Micronaut

Configure OJP in application.yml:

                        datasources:

  default:

    driver-class-name: org.openjproxy.jdbc.Driver

    url: jdbc:ojp[localhost:1059]_...

Advanced Topics

Distributed Transactions

OJP supports XA distributed transactions for coordinating across multiple resources. Configure XA data sources and use standard JTA transaction managers.

Monitoring & Observability

Built-in metrics, query tracking, and performance monitoring. Integrate with Prometheus, Grafana, or your monitoring stack.

High Availability

Deploy multiple OJP server instances for high availability. Load balance connections and handle failover automatically.

Multi-Language Support

Use the gRPC API to access OJP from non-Java languages. Protocol Buffers definitions available on GitHub.

Performance Tuning

Optimize connection pool sizes, query timeouts, and resource allocation based on your workload patterns.

Additional Resources

📚 GitHub Repository

Access source code, examples, and contribute to the project

View on GitHub

🎥 Video Tutorial

Watch the founder explain OJP architecture and benefits

Watch on YouTube

📝 JAVARO Posts

Deep dive articles about OJP features and use cases

Read Blog

💬 Community Support

Get help from the community and contribute your knowledge

Join Discussion