feat: support HikariCP custom settings for pg (#208)

Author: thunderz99

README.md

@@ -23,7 +23,7 @@ java-cosmos is a client for Azure CosmosDB 's SQL API (also called documentdb fo
 <dependency>
   <groupId>com.github.thunderz99</groupId>
     <artifactId>java-cosmos</artifactId>
-    <version>0.8.23</version>
+    <version>0.8.24</version>
 </dependency>
 ```
 
@@ -502,6 +502,33 @@ db.upsert("Database1", new User("id011","Tom","Banks"), "Collection1");
                 
 ```
 
+### PostgreSQL HikariCP settings
+
+```java
+import io.github.thunderz99.cosmos.impl.postgres.dto.PostgresHikariOptions;
+
+var hikariOptions = new PostgresHikariOptions()
+    .withMaximumPoolSize(30)
+    .withMinimumIdle(5)
+    .withConnectionTimeoutMs(30_000)
+    .withIdleTimeoutMs(120_000)
+    .withMaxLifetimeMs(600_000)
+    .withValidationTimeoutMs(5_000)
+    .withPoolName("java-cosmos-pool")
+    // Optional: pass raw Hikari properties for minor/future settings
+    .withHikariProperty("initializationFailTimeout", "-1")
+    .withHikariProperty("leakDetectionThreshold", "30000");
+
+var cosmos = new CosmosBuilder()
+    .withDatabaseType("postgres")
+    .withConnectionString("jdbc:postgresql://localhost:5432/postgres?user=postgres&password=postgres")
+    // quick entrypoint for common tuning
+    .withHikariMaximumPoolSize(30)
+    // optional: typed + raw custom settings
+    .withCustomHikariSettings(hikariOptions)
+    .build();
+```
+
 ### $ELEM_MATCH queries to match fields in  array type field
 
 Dealing with array types in json, we can do a query like this using rawSql to find a child whose grade greater than 5 and gender is "female".

pom.xml

@@ -4,7 +4,7 @@
     <groupId>com.github.thunderz99</groupId>
     <artifactId>java-cosmos</artifactId>
     <packaging>jar</packaging>
-    <version>0.8.23</version>
+    <version>0.8.24</version>
     <name>${project.groupId}:${project.artifactId}$</name>
     <description>A lightweight Azure CosmosDB client for Java</description>
     <url>https://github.com/thunderz99/java-cosmos</url>

src/main/java/io/github/thunderz99/cosmos/CosmosBuilder.java

@@ -5,6 +5,7 @@
 import io.github.thunderz99.cosmos.impl.cosmosdb.CosmosImpl;
 import io.github.thunderz99.cosmos.impl.mongo.MongoImpl;
 import io.github.thunderz99.cosmos.impl.postgres.PostgresImpl;
+import io.github.thunderz99.cosmos.impl.postgres.dto.PostgresHikariOptions;
 import io.github.thunderz99.cosmos.impl.postgres.util.PGSortUtil;
 import io.github.thunderz99.cosmos.util.Checker;
 import org.apache.commons.lang3.StringUtils;
@@ -49,6 +50,11 @@ public class CosmosBuilder {
 
     boolean etagEnabled = false;
 
+    /**
+     * Optional custom HikariCP settings for postgres.
+     */
+    PostgresHikariOptions postgresHikariOptions;
+
     /**
      * Specify the dbType( "cosmosdb" or "mongodb" or "postgres")
      *
@@ -138,6 +144,35 @@ public CosmosBuilder withEtagEnabled(boolean enabled) {
         return this;
     }
 
+    /**
+     * Set hikari maximum pool size for postgres.
+     *
+     * <p>
+     * This is a convenient entrypoint for the most common HikariCP tuning.
+     * </p>
+     *
+     * @param maximumPoolSize max number of connections in the pool
+     * @return this
+     */
+    public CosmosBuilder withHikariMaximumPoolSize(int maximumPoolSize) {
+        if (this.postgresHikariOptions == null) {
+            this.postgresHikariOptions = new PostgresHikariOptions();
+        }
+        this.postgresHikariOptions.withMaximumPoolSize(maximumPoolSize);
+        return this;
+    }
+
+    /**
+     * Set custom hikari settings for postgres.
+     *
+     * @param options custom hikari options
+     * @return this
+     */
+    public CosmosBuilder withCustomHikariSettings(PostgresHikariOptions options) {
+        this.postgresHikariOptions = options;
+        return this;
+    }
+
     /**
      * Build the instance representing a Cosmos instance.
      *
@@ -156,7 +191,7 @@ public Cosmos build() {
         }
 
         if (StringUtils.equals(dbType, POSTGRES)) {
-            return new PostgresImpl(connectionString, expireAtEnabled, etagEnabled, collate);
+            return new PostgresImpl(connectionString, expireAtEnabled, etagEnabled, collate, postgresHikariOptions);
         }
 
         throw new IllegalArgumentException("Not supported dbType: " + dbType);
@@ -165,4 +200,3 @@ public Cosmos build() {
 
 
 }
-

src/main/java/io/github/thunderz99/cosmos/impl/postgres/PostgresImpl.java

@@ -9,6 +9,7 @@
 import io.github.thunderz99.cosmos.CosmosException;
 import io.github.thunderz99.cosmos.dto.CosmosContainerResponse;
 import io.github.thunderz99.cosmos.dto.UniqueKeyPolicy;
+import io.github.thunderz99.cosmos.impl.postgres.dto.PostgresHikariOptions;
 import io.github.thunderz99.cosmos.impl.postgres.util.PGSortUtil;
 import io.github.thunderz99.cosmos.impl.postgres.util.TableUtil;
 import io.github.thunderz99.cosmos.util.Checker;
@@ -61,8 +62,22 @@ public PostgresImpl(String connectionString) {
     }
 
     public PostgresImpl(String connectionString, boolean expireAtEnabled, boolean etagEnabled, String collate) {
+        this(connectionString, expireAtEnabled, etagEnabled, collate, null);
+    }
+
+    /**
+     * Build postgres cosmos client with custom hikari settings.
+     *
+     * @param connectionString postgres connection string
+     * @param expireAtEnabled whether enable expireAt feature
+     * @param etagEnabled whether enable etag feature
+     * @param collate collation used for postgres sorting
+     * @param hikariOptions optional custom hikari options
+     */
+    public PostgresImpl(String connectionString, boolean expireAtEnabled, boolean etagEnabled,
+                        String collate, PostgresHikariOptions hikariOptions) {
 
-        var pair = parseToHikariConfig(connectionString);
+        var pair = parseToHikariConfig(connectionString, hikariOptions);
         var config = pair.getLeft();
         this.account = pair.getRight();
 
@@ -84,9 +99,21 @@ public PostgresImpl(String connectionString, boolean expireAtEnabled, boolean et
      * @return pair of HikariConfig and account(hostName)
      */
     public static Pair<HikariConfig, String> parseToHikariConfig(String connectionString) {
+        return parseToHikariConfig(connectionString, null);
+    }
+
+    /**
+     * parse connectionString("postgres://user:pass@localhost:5432/database1") to HikariConfig,
+     * then apply optional custom hikari settings.
+     *
+     * @param connectionString postgres connectionString
+     * @param hikariOptions optional custom hikari options
+     * @return pair of HikariConfig and account(hostName)
+     */
+    public static Pair<HikariConfig, String> parseToHikariConfig(String connectionString,
+                                                                  PostgresHikariOptions hikariOptions) {
 
         Checker.checkNotBlank(connectionString, "connectionString");
-        var config = new HikariConfig();
         URI uri;
         try {
             // use URI to parse connectionString
@@ -100,6 +127,8 @@ public static Pair<HikariConfig, String> parseToHikariConfig(String connectionSt
             throw new IllegalArgumentException("connectionString not valid for postgres: " + connectionString, e);
         }
 
+        var config = hikariOptions == null ? new HikariConfig() : new HikariConfig(hikariOptions.getHikariProperties());
+
         String jdbcUrl = String.format("jdbc:postgresql://%s:%d%s",
                 uri.getHost(), uri.getPort(), uri.getRawPath());
 
@@ -128,6 +157,10 @@ public static Pair<HikariConfig, String> parseToHikariConfig(String connectionSt
         }
         config.setDriverClassName("org.postgresql.Driver");
 
+        if (hikariOptions != null) {
+            hikariOptions.applyTo(config);
+        }
+
         var account = uri.getHost();
 
         return Pair.of(config, account);
@@ -309,4 +342,4 @@ public void closeClient() {
         this.getDataSource().close();
     }
 
-}
+}