If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/brettwooldridge/HikariCP shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 6mo ago
• 18 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 6mo ago
• ⚠ Single-maintainer risk — top contributor 81% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live brettwooldridge/HikariCP repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/brettwooldridge/HikariCP.

What it runs against: a local clone of brettwooldridge/HikariCP — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in brettwooldridge/HikariCP | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch dev exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 215 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of brettwooldridge/HikariCP. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/brettwooldridge/HikariCP.git
#   cd HikariCP
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of brettwooldridge/HikariCP and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "brettwooldridge/HikariCP(\\.git)?\\b" \\
  && ok "origin remote is brettwooldridge/HikariCP" \\
  || miss "origin remote is not brettwooldridge/HikariCP (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify dev >/dev/null 2>&1 \\
  && ok "default branch dev exists" \\
  || miss "default branch dev no longer exists"

# 4. Critical files exist
test -f "src/main/java/com/zaxxer/hikari/pool/HikariPool.java" \\
  && ok "src/main/java/com/zaxxer/hikari/pool/HikariPool.java" \\
  || miss "missing critical file: src/main/java/com/zaxxer/hikari/pool/HikariPool.java"
test -f "src/main/java/com/zaxxer/hikari/HikariDataSource.java" \\
  && ok "src/main/java/com/zaxxer/hikari/HikariDataSource.java" \\
  || miss "missing critical file: src/main/java/com/zaxxer/hikari/HikariDataSource.java"
test -f "src/main/java/com/zaxxer/hikari/HikariConfig.java" \\
  && ok "src/main/java/com/zaxxer/hikari/HikariConfig.java" \\
  || miss "missing critical file: src/main/java/com/zaxxer/hikari/HikariConfig.java"
test -f "src/main/java/com/zaxxer/hikari/pool/PoolEntry.java" \\
  && ok "src/main/java/com/zaxxer/hikari/pool/PoolEntry.java" \\
  || miss "missing critical file: src/main/java/com/zaxxer/hikari/pool/PoolEntry.java"
test -f "src/main/java/com/zaxxer/hikari/util/ConcurrentBag.java" \\
  && ok "src/main/java/com/zaxxer/hikari/util/ConcurrentBag.java" \\
  || miss "missing critical file: src/main/java/com/zaxxer/hikari/util/ConcurrentBag.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 215 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~185d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/brettwooldridge/HikariCP"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

HikariCP is a high-performance, zero-overhead JDBC connection pool library (~165KB) written in pure Java that manages database connections with minimal latency and memory overhead. It replaces default connection pools in production systems by providing fast connection acquisition, intelligent pool sizing, and failure recovery—critical for any application that makes frequent database requests. Monolithic JAR structure under src/main/java/com/zaxxer/hikari/: core pool logic in HikariDataSource.java and HikariConfig.java, pluggable metrics via src/main/java/com/zaxxer/hikari/metrics/ (supporting Dropwizard, Micrometer, Prometheus), and optional Hibernate integration in src/main/java/com/zaxxer/hikari/hibernate/. All code is in a single Maven module defined by pom.xml.

Backend engineers and DevOps teams deploying Java applications (Spring Boot apps, microservices, enterprise systems) that need to squeeze performance out of database connectivity without tuning dozens of pool parameters. Particularly valuable for teams running high-throughput systems where connection overhead directly impacts latency.

Highly mature and production-ready: the project is actively maintained with continuous CI/CD via CircleCI and GitHub Actions, comprehensive test coverage, and incremental minor releases (currently at v7.0.2 for Java 11+, v4.0.3 for Java 8). The codebase is stable with a focus on reliability over feature churn, making it the de facto standard connection pool in Spring Boot and enterprise Java.

Very low risk: single maintainer (Brett Wooldridge) is a known issue for long-term sustainability, but the library has been battle-tested in production at scale for years with minimal breaking changes. Dependencies are minimal (primarily metrics libraries like Dropwizard and Micrometer which are optional), and the tight, focused scope reduces surface area for bugs. Main risk is adoption lag if Java major versions change significantly.

Active maintenance with focus on Java 11+ modernization (deprecated Java 8 at v4.0.3, Java 7 at v2.4.13), metrics framework integrations, and operational reliability. CI is running on CircleCI and GitHub Actions per .circleci/config.yml and .github/workflows/ci.yml. Recent work includes Prometheus and Micrometer metric tracker factories to support modern observability stacks.

Clone and build with Maven: git clone https://github.com/brettwooldridge/HikariCP.git && cd HikariCP && mvn clean install. Tests run via Maven's standard test phase: mvn test. No external services required for local development; the project bundles H2 database (v2.3.232 in pom.xml) for testing.

Daily commands: This is a library, not an application. To use: add HikariCP as a Maven dependency (shown in pom.xml example), then instantiate HikariDataSource with a HikariConfig object. For local development/testing: mvn clean test runs the test suite. Use .editorconfig for IDE formatting consistency.

• src/main/java/com/zaxxer/hikari/pool/HikariPool.java — Core connection pool implementation managing connection lifecycle, borrowing, and eviction—the heart of HikariCP.
• src/main/java/com/zaxxer/hikari/HikariDataSource.java — Public API entry point implementing DataSource; all users interact with the pool through this class.
• src/main/java/com/zaxxer/hikari/HikariConfig.java — Configuration container with validation; all pool behavior is governed by settings defined here.
• src/main/java/com/zaxxer/hikari/pool/PoolEntry.java — Wrapper around individual database connections tracking state, timestamps, and proxy references.
• src/main/java/com/zaxxer/hikari/util/ConcurrentBag.java — Lock-free concurrent collection using ThreadLocal—critical for high-performance connection hand-off without contention.
• src/main/java/com/zaxxer/hikari/pool/ProxyConnection.java — Dynamic proxy wrapping real connections to intercept close() and detect resource leaks.
• src/main/java/com/zaxxer/hikari/pool/PoolBase.java — Shared base class for pool initialization, connection creation, and database-specific configuration.

Add a new metrics backend

1. Implement the IMetricsTracker interface to collect custom metrics (src/main/java/com/zaxxer/hikari/metrics/IMetricsTracker.java)
2. Create a factory class extending MetricsTrackerFactory to instantiate your tracker (src/main/java/com/zaxxer/hikari/metrics/MetricsTrackerFactory.java)
3. Set the factory class in HikariConfig via setMetricsTrackerFactory() at pool creation time (src/main/java/com/zaxxer/hikari/HikariConfig.java)

Add custom connection initialization logic

1. Set a custom connectionInitSql in HikariConfig for SQL run on every new connection (src/main/java/com/zaxxer/hikari/HikariConfig.java)
2. Or implement HikariCredentialsProvider and set via setCredentialsProvider() for custom username/password logic (src/main/java/com/zaxxer/hikari/HikariCredentialsProvider.java)
3. Pool executes init SQL in PoolBase.newConnection() before adding to pool (src/main/java/com/zaxxer/hikari/pool/PoolBase.java)

Add a new proxy type (e.g., for custom connection validation)

1. Create a new Proxy* class mirroring ProxyConnection structure, intercepting relevant JDBC methods (src/main/java/com/zaxxer/hikari/pool/ProxyConnection.java)
2. Register the new proxy type in ProxyFactory.getProxyClass() method (src/main/java/com/zaxxer/hikari/pool/ProxyFactory.java)
3. If using Javassist bytecode generation, update JavassistProxyFactory to emit your proxy class (src/main/java/com/zaxxer/hikari/util/JavassistProxyFactory.java)

Implement custom pool eviction strategy

1. Modify HikariPool.evictConnection() and HikariPool.houseKeeper() methods to apply custom eviction logic (src/main/java/com/zaxxer/hikari/pool/HikariPool.java)
2. Tune maxLifetime, idleTimeout, and leakDetectionThreshold in HikariConfig for desired eviction behavior (src/main/java/com/zaxxer/hikari/HikariConfig.java)

• Javassist bytecode generation — Eliminates reflection overhead in proxy method interception; generates optimized bytecode for each JDBC interface at pool startup
• C — undefined

No external services required, but note: (1) the library requires JVM TCP keepalive configuration to prevent pool starvation during network idle (documented in README as critical), (2) Maven's surefire plugin requires --add-modules=ALL-MODULE-PATH for Java 11+ (configured in pom.xml property sureFireOptions11), (3) metrics implementations are optional—if using Prometheus tracker, Prometheus client JAR must be on classpath, (4) HikariJNDIFactory.java for JNDI binding may conflict with application server configuration if not careful.

• Connection pooling — HikariCP's entire purpose is managing a pool of reusable database connections to avoid the overhead of creating/destroying connections per request; understanding pooling theory is essential to configuring it correctly
• Zero-copy/overhead minimization — HikariCP is designed around reducing GC pressure and CPU overhead through careful object reuse and lock-free data structures; the README references this as core design philosophy
• JDBC API — HikariCP wraps JDBC DataSource and Connection interfaces; you must understand JDBC basics to use this library correctly
• Thread-safe concurrent data structures — HikariCP's pool uses ConcurrentHashMap and atomics to manage connections across multiple threads without explicit locks; understanding concurrent programming is essential for contributing
• JMX (Java Management Extensions) — HikariCP exposes MXBeans (HikariPoolMXBean, HikariConfigMXBean) for runtime monitoring and management via JConsole or other JMX tools
• Pluggable metrics/observability interfaces — HikariCP abstracts metrics collection via IMetricsTracker, allowing it to integrate with Dropwizard, Micrometer, or Prometheus without tight coupling; this pattern is important for modern Java architecture
• TCP keepalive — The README warns that TCP keepalive configuration is critical to prevent pool starvation during idle periods; understanding network-level connection management is essential for production deployment

• apache/commons-dbcp — Apache's older connection pool—direct competitor; HikariCP was built to be faster and simpler
• spring-projects/spring-boot — Spring Boot auto-configures HikariCP as the default connection pool when on classpath; tight integration ecosystem
• hibernate/hibernate-orm — HikariCP provides Hibernate dialect integration; Hibernate ORM is a primary consumer of this library
• micrometer-metrics/micrometer — Modern observability library that HikariCP integrates with via MicrometerMetricsTracker.java for app monitoring
• prometheus/client_java — Prometheus metrics client that HikariCP supports as a metrics backend via PrometheusHistogramMetricsTracker.java

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for HikariPool connection lifecycle and edge cases

The HikariPool.java file is the core of the connection pooling mechanism, but based on the file structure, there's no visible dedicated test file for connection lifecycle scenarios (connection eviction, timeout handling, concurrent access patterns). Adding tests for edge cases like: rapid acquire/release cycles, connection validation failures, idle timeout expiration, and concurrent max-pool-size boundary conditions would significantly improve reliability and prevent regressions.

• [ ] Create src/test/java/com/zaxxer/hikari/pool/HikariPoolLifecycleTest.java
• [ ] Add tests for connection eviction under various timeout scenarios in HikariPool
• [ ] Add stress tests for concurrent connection acquisition at pool capacity limits
• [ ] Add tests for PoolEntry state transitions and connection validation failures
• [ ] Verify test coverage includes ProxyConnection leak detection scenarios

Add metrics integration tests for all tracker implementations (Dropwizard, Micrometer, Prometheus)

HikariCP supports multiple metrics backends (Dropwizard, Micrometer, Prometheus) with separate implementations in src/main/java/com/zaxxer/hikari/metrics/. There's no visible unified test suite validating that all implementations correctly report the same core metrics (active connections, pending requests, connection timeout counts). This would catch cross-implementation metric reporting bugs and ensure parity.

• [ ] Create src/test/java/com/zaxxer/hikari/metrics/MetricsTrackerIntegrationTest.java
• [ ] Create parameterized tests validating CodaHaleMetricsTracker, Dropwizard5MetricsTracker, MicrometerMetricsTracker, and PrometheusMetricsTracker report identical core metrics
• [ ] Add tests verifying metric values during connection pool lifecycle events (acquire, release, timeout)
• [ ] Add tests for PrometheusHistogramMetricsTracker percentile calculation accuracy
• [ ] Validate metrics behave correctly under pool stress and edge cases

Add GitHub Actions CI workflow for testing against multiple Java versions and database drivers

While .circleci/config.yml and .github/workflows/ci.yml exist, the workflows may not comprehensively test against multiple Java versions (Java 11, 17, 21) and popular JDBC drivers (PostgreSQL, MySQL, MariaDB, H2). Given HikariCP's critical role in production systems, expanding CI to validate driver compatibility would prevent subtle regressions. The pom.xml shows h2.version and other dependencies but CI coverage isn't explicit in the file structure.

• [ ] Review current .github/workflows/ci.yml to identify tested Java versions
• [ ] Extend ci.yml with matrix strategy testing against Java 11, 17, 21, and 23 (LTS + latest)
• [ ] Add separate matrix job testing against PostgreSQL, MySQL, and MariaDB drivers in addition to H2
• [ ] Add JDK Early-Access build testing to catch future Java compatibility issues early
• [ ] Document tested configurations in CONTRIBUTING.md or README.md

• Add comprehensive JavaDoc examples to HikariConfig.java for the ~30 configuration options—currently some lack clear use-case guidance
• Create a metrics integration example in documents/ showing how to wire up Prometheus metrics with a Spring Boot application, filling the gap between IMetricsTracker interface and actual production setup
• Expand test coverage for src/main/java/com/zaxxer/hikari/metrics/micrometer/ package—Micrometer integration exists but test file paths suggest incomplete test scenarios

• High · Potential SQL Injection in Connection Pool — src/main/java/com/zaxxer/hikari/pool/ProxyStatement.java, src/main/java/com/zaxxer/hikari/pool/ProxyPreparedStatement.java. HikariCP is a JDBC connection pool that handles database connections. While the library itself is well-designed, applications using it may be vulnerable to SQL injection if they construct SQL queries dynamically without proper parameterized statements. The proxy classes (ProxyStatement, ProxyPreparedStatement) intercept database operations but don't validate SQL content. Fix: Ensure applications using HikariCP always use PreparedStatements with parameterized queries. Document security best practices in README. Consider adding optional query validation/logging features.
• Medium · Credentials Management in Configuration — src/main/java/com/zaxxer/hikari/HikariConfig.java, src/main/java/com/zaxxer/hikari/HikariCredentialsProvider.java, src/main/java/com/zaxxer/hikari/util/Credentials.java. The HikariConfig class handles database credentials (username/password). While HikariCredentialsProvider exists for external credential management, sensitive data could be logged or exposed if configuration is not properly handled. No evidence of credential encryption at rest. Fix: Implement credential masking in logging/toString() methods. Recommend using HikariCredentialsProvider for external secret management. Consider supporting encrypted configuration properties.
• Medium · Dynamic Class Loading via Javassist — src/main/java/com/zaxxer/hikari/util/JavassistProxyFactory.java. The JavassistProxyFactory uses dynamic bytecode generation to create proxy classes. If user-supplied class names or property values are used in proxy generation without validation, this could potentially be exploited. Fix: Validate all inputs to proxy factory methods. Ensure Javassist library is kept updated. Review proxy generation logic for injection possibilities.
• Medium · Reflection-based Configuration Property Setting — src/main/java/com/zaxxer/hikari/util/PropertyElf.java. PropertyElf likely uses reflection to set configuration properties dynamically. Without proper validation, this could allow setting unexpected or dangerous properties if configuration sources are untrusted. Fix: Implement strict whitelist of allowed configuration properties. Validate property types and values before reflection-based assignment. Log all property modifications.
• Medium · Connection Leak Detection via ProxyLeakTask — src/main/java/com/zaxxer/hikari/pool/ProxyLeakTask.java, src/main/java/com/zaxxer/hikari/pool/ProxyLeakTaskFactory.java. The ProxyLeakTask handles connection leak detection and may expose sensitive stack traces or connection details in debug output. Excessive logging of connection state could leak sensitive information. Fix: Ensure sensitive information is not logged in leak detection messages. Implement configurable verbosity levels. Sanitize stack traces in production environments.
• Low · JNDI Factory Potential Injection Point — src/main/java/com/zaxxer/hikari/HikariJNDIFactory.java. HikariJNDIFactory uses JNDI for configuration lookup. JNDI injection (Java object deserialization) is a known attack vector if JNDI sources are untrusted. Fix: Validate JNDI data sources carefully. Use trusted JNDI providers only. Consider restricting JNDI usage in favor of direct configuration. Document JNDI security implications.
• Low · Metrics Exposure via Multiple Providers — src/main/java/com/zaxxer/hikari/metrics/. Multiple metrics providers (Prometheus, Micrometer, Dropwizard) expose pool statistics. Pool statistics may indirectly expose operational information that could be useful for attackers during reconnaissance. Fix: Ensure metrics endpoints are properly protected with authentication/authorization. Document which metrics are safe to expose publicly. Consider sensitive metric filtering options.
• Low · Incomplete Module Declaration — undefined. The module-info.java file exists but may have incomplete module definitions, potentially allowing unintended access to internal packages or missing security-related module exports. Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.