Open J Proxy

openjproxy.com

A type 3 JDBC Driver and Layer 7 Proxy Server to decouple applications from relational database connection management.

"The only open-source JDBC Type 3 driver globally, this project introduces a transparent Quality-of-Service layer that decouples application performance from database bottlenecks. It's a must-try for any team struggling with data access contention, offering easy-to-implement back-pressure and pooling management." (Bruno Bossola - Java Champion and CTO @ Meterian.io)

---

---

Value Proposition

OJP protects your databases from overwhelming connection storms by acting as a smart backpressure mechanism. Instead of every application instance opening and holding connections, OJP orchestrates and optimizes database access through intelligent pooling, query flow control, and multi-database support. With minimal configuration changes, you replace native JDBC drivers gaining connection resilience, and safer scalability. Elastic scaling becomes simpler without putting your database at risk.

---

Requirements

• OJP JDBC Driver: Java 11 or higher
• OJP Server: Java 21 or higher

---

Quick Start

Get OJP running in under 5 minutes:

1. Start OJP Server (Docker)

⚠️ Important for v0.4.0-beta and later: JDBC drivers must be downloaded and mounted. See Chapter 4: Database Drivers for details.

# Download drivers first
mkdir -p ojp-libs
cd ojp-server
bash download-drivers.sh ../ojp-libs
cd ..

# Run with drivers mounted
docker run --rm -d \
  --network host \
  -v $(pwd)/ojp-libs:/opt/ojp/ojp-libs \
  rrobetti/ojp:0.3.1-beta

Alternative: Runnable JAR (No Docker)

# Download OJP Server JAR and open source drivers
cd ojp-server
bash download-drivers.sh  # Downloads H2, PostgreSQL, MySQL, MariaDB to ojp-libs/
java -jar ojp-server-0.3.2-snapshot-shaded.jar

📖 See Executable JAR Setup Guide for details.

2. Add OJP JDBC Driver to your project

<dependency>
    <groupId>org.openjproxy</groupId>
    <artifactId>ojp-jdbc-driver</artifactId>
    <version>0.3.1-beta</version>
</dependency>

3. Update your JDBC URL

Replace your existing connection URL by prefixing with ojp[host:port]_:

// Before (PostgreSQL example)
"jdbc:postgresql://user@localhost/mydb"

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

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

// SQL Server example
"jdbc:ojp[localhost:1059]_sqlserver://localhost:1433;databaseName=mydb"

Use the ojp driver: org.openjproxy.jdbc.Driver

That's it! Your application now uses intelligent connection pooling through OJP.

Note: For detailed driver setup including proprietary databases (Oracle, SQL Server, DB2), see Chapter 4: Database Drivers.

Alternative Setup: Executable JAR (No Docker)

If Docker is not available in your environment, you can build and run OJP Server as a standalone JAR file:

📖 Executable JAR Setup Guide - Complete instructions for building and running OJP Server as a standalone executable JAR with all dependencies included.

---

Documentation

High Level Solution

• The OJP JDBC driver is used as a replacement for the native JDBC driver(s) previously used with minimal change, the only change required being prefixing the connection URL with ojp_.
• Open Source: OJP is an open-source project that is free to use, modify, and distribute.
• The OJP server is deployed as an independent service that serves as a smart proxy between the application(s) and their respective relational database(s), controlling the number of connections open against each database.
• Smart Connection Management: The proxy ensures that database connections are allocated only when needed, improving scalability and resource utilization.
• Elastic Scalability: OJP allows client applications to scale elastically without increasing the pressure on the database.
• gRPC Protocol is used to facilitate the connection between the OJP JDBC Driver and the OJP Server, allowing for efficient data transmission over a multiplexed channel.
• OJP Server uses HikariCP connection pools to efficiently manage connections.
• OJP supports multiple relational databases - in theory it can support any relational database that provides a JDBC driver implementation.
• OJP simple setup just requires the OJP library in the classpath and the OJP prefix added to the connection URL (e.g., jdbc:ojp[host:port]_h2:~/test where host:port represents the location of the OJP server).
• Drop-In External Libraries: Add proprietary JDBC drivers (Oracle, SQL Server, DB2) and additional libraries (e.g., Oracle UCP) without recompiling - see Drop-In Driver Documentation. Simply place JARs in the ojp-libs directory.
• SQL Query Optimization: Optional SQL enhancer with Apache Calcite provides query optimization using real database schema metadata for improved performance analysis and dialect translation.

Further documents

• Drop-In External Libraries Support - Add proprietary database drivers and libraries (Oracle JDBC, Oracle UCP, SQL Server, DB2) without recompiling.
• SSL/TLS Certificate Configuration Guide - Configure SSL/TLS certificates with server-side property placeholders for PostgreSQL, MySQL, Oracle, SQL Server, and DB2.
• Architectural decision records (ADRs) - Technical decisions and rationale behind OJP's architecture.
• Get started: Spring Boot, Quarkus and Micronaut - Framework-specific integration guides and examples.
• Understanding OJP Service Provider Interfaces (SPIs) - Guide for Java developers on implementing custom connection pool providers.
• Connection Pool Configuration - OJP JDBC driver setup, connection pool settings, and environment-specific configuration (ojp-dev.properties, ojp-staging.properties, ojp-prod.properties).
• OJP Server Configuration - Server startup options, runtime configuration, and SQL enhancer with schema loading.
• Multinode Configuration - High availability and load balancing with multiple OJP servers.
• Slow query segregation feature - Feature that prevent connection starvation by slow queries (or statements).
• Telemetry and Observability - OpenTelemetry integration and monitoring setup.
• OJP Components - Core modules that define OJP’s architecture, including the server, JDBC driver, and shared gRPC contracts.
• Targeted Problem and Solution - Explanation of the problem OJP solves and how it addresses it.
• BigDecimal Wire Format - Protocol specification for language-neutral BigDecimal serialization.

---

Vision

Provide a free and open-source solution for a relational database-agnostic proxy connection pool. The project is designed to help efficiently manage database connections in microservices, event-driven architectures, or serverless environments while maintaining high scalability and performance.

---

Contributing & Developer Guide

Welcome to OJP! We appreciate your interest in contributing. This guide will help you get started with development.

• OJP Contributor Recognition Program - OJP Contributor Recognition rewards program and badges recognize more than code contributions, check it out!
• Source code developer setup and local testing - Outlines how to get started building OJP source code locally and running tests.

---

Partners

Logo	Description	Website
	Brazilian Java User Group connecting developers for knowledge sharing and professional networking.	linkedin.com/in/devsjava
	Feature management platform for managing features at scale with performance focus.	github.com/switcherapi
	Application security platform that identifies vulnerabilities across open-source dependencies and application code.	meterian.io
	YouTube channel for Java developers covering frameworks, containers, and modern JVM topics.	youtube.com/@cbrjar
	Helps developers go beyond coding, mastering Java fundamentals, building career confidence, and preparing for international opportunities.	javachallengers.com
	The team behind Eclipse GlassFish, delivering reliable opensource solutions with enterprise support.	omnifish.ee