val config = new HikariConfig()
config.setJdbcUrl(url)
config.setUsername(user)
config.setPassword(password)
config.setMaximumPoolSize(connectionPoolMaxSize)
config.setLeakDetectionThreshold(1000)
config.setAutoCommit(true)
sslRootCert.foreach(config.addDataSourceProperty("sslrootcert", _))

new HikariDataSource(config)

db.jdbc {
  dataSource {
    url = ${?DATASOURCE_URL}
    user = ${?DB_USER}
    password = ${?DB_PASSWD}
  }

  connectionPool {
    maxSize = 32
    maxSize = ${?DB_CONNECTION_SIZE}
  }
}

HikariCP это JDBC connection pool.

JDBC тут ключевое слово. HikariCP не привязан к одному языку или фреймворку. Это библиотека для JVM, которая управляет JDBC-соединениями. Поэтому она одинаково естественно живёт в Java, Kotlin, Scala, Groovy, Clojure и вообще в любом языке, который в итоге работает поверх JVM и JDBC.

• заранее открывает несколько соединений к базе;

• выдаёт соединение коду, когда надо выполнить запрос;

• принимает соединение обратно после close();

• следит за жизненным циклом соединений;

• ограничивает количество одновременных походов в базу;

• даёт метрики, чтобы понять, где приложение упёрлось в БД.

Без пула каждый запрос мог бы создавать новое физическое соединение. Это дорого: TCP, TLS, аутентификация, настройка сессии, иногда ещё и прокси между приложением и базой. С пулом приложение берёт уже готовое соединение, работает и возвращает его обратно.

• 3.4.5 - старая, но ещё встречается в живых проектах. Релиз 2020 года.

• 4.x - эпоха Java 8/11-перехода, появился keepaliveTime.

• 5.x - уже более современная линия для новых JVM-стеков.

• 6.x - много внутренних исправлений, включая работу с credentials и JDBC lifecycle.

• 7.x - актуальная major-линия, Java 11+, исправления вокруг reflection, credentials provider, interruption в pool filling loop.

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;

import javax.sql.DataSource;

public final class DataSourceFactory {
    public static DataSource create() {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl(System.getenv("DB_URL"));
        config.setUsername(System.getenv("DB_USER"));
        config.setPassword(System.getenv("DB_PASSWORD"));

        config.setPoolName("app-postgres");
        config.setMaximumPoolSize(16);
        config.setMinimumIdle(16);
        config.setConnectionTimeout(5_000);
        config.setValidationTimeout(2_000);
        config.setMaxLifetime(25 * 60_000);
        config.setKeepaliveTime(2 * 60_000);
        config.setAutoCommit(true);

        return new HikariDataSource(config);
    }
}

import com.zaxxer.hikari.HikariConfig
import com.zaxxer.hikari.HikariDataSource
import javax.sql.DataSource

fun dataSource(): DataSource {
    val config = HikariConfig().apply {
        jdbcUrl = System.getenv("DB_URL")
        username = System.getenv("DB_USER")
        password = System.getenv("DB_PASSWORD")

        poolName = "app-postgres"
        maximumPoolSize = 16
        minimumIdle = 16
        connectionTimeout = 5_000
        validationTimeout = 2_000
        maxLifetime = 25 * 60_000
        keepaliveTime = 2 * 60_000
        isAutoCommit = true
    }

    return HikariDataSource(config)
}

import com.zaxxer.hikari.{HikariConfig, HikariDataSource}

object DataSourceFactory {
  def create(): HikariDataSource = {
    val config = new HikariConfig()
    config.setJdbcUrl(sys.env("DB_URL"))
    config.setUsername(sys.env("DB_USER"))
    config.setPassword(sys.env("DB_PASSWORD"))

    config.setPoolName("app-postgres")
    config.setMaximumPoolSize(16)
    config.setMinimumIdle(16)
    config.setConnectionTimeout(5000)
    config.setValidationTimeout(2000)
    config.setMaxLifetime(25 * 60 * 1000)
    config.setKeepaliveTime(2 * 60 * 1000)
    config.setAutoCommit(true)

    new HikariDataSource(config)
  }
}

spring:
  datasource:
    url: jdbc:postgresql://db.example.local:5432/app
    username: ${DB_USER}
    password: ${DB_PASSWORD}
    hikari:
      pool-name: app-postgres
      maximum-pool-size: 16
      minimum-idle: 16
      connection-timeout: 5000
      validation-timeout: 2000
      max-lifetime: 1500000
      keepalive-time: 120000
      auto-commit: true
      register-mbeans: true

Если включён Spring Boot Actuator и Micrometer, метрики Hikari обычно можно получить без большого шаманства. Самые полезные:

• hikaricp.connections.active - сколько соединений сейчас занято;

• hikaricp.connections.idle - сколько свободно;

• hikaricp.connections.pending - сколько потоков ждут соединение;

• hikaricp.connections.timeout - сколько раз приложение не дождалось соединения;

• hikaricp.connections.acquire - сколько времени занимает получение соединения;

• hikaricp.connections.usage - как долго соединение держат.

Максимальное количество соединений в пуле. Включает и занятые, и свободные.

Если пул достиг этого размера, а свободных соединений нет, поток будет ждать до connectionTimeout. Потом получит ошибку.

Самая частая ошибка: ставить maximumPoolSize по количеству пользователей или HTTP-потоков. База не становится быстрее от того, что вы открыли к ней 100 соединений. Часто становится медленнее: контекстные переключения, конкуренция за CPU, locks, память, лишняя нагрузка на планировщик.

Минимальное количество свободных соединений, которое Hikari старается держать.

Если minimumIdle не задан, HikariCP по умолчанию делает его равным maximumPoolSize. Получается fixed-size pool: все соединения создаются и держатся тёплыми.

Для серверных приложений с предсказуемой нагрузкой это часто нормальный вариант. Меньше сюрпризов на всплесках. Если хотите динамический пул, задавайте minimumIdle ниже maximumPoolSize, но понимайте цену: новые соединения могут создаваться прямо во время нагрузки.

Сколько ждать свободное соединение из пула.

Дефолт HikariCP: 30 секунд. Для многих backend-сервисов это слишком долго. Если запрос 30 секунд стоит в очереди за соединением, пользователь уже давно не счастлив, а ваш HTTP thread занят и держит ресурсы.

Я обычно начинаю с 2-5 секунд для online API и отдельно думаю про batch/background jobs.

Сколько ждать проверки соединения. Дефолт: 5 секунд.

Если база или сеть деградирует, длинные проверки могут добавить неприятную задержку. 1-2 секунды часто достаточно, но надо смотреть на сеть и географию.

Сколько idle-соединение может лежать в пуле перед удалением.

Работает только если minimumIdle < maximumPoolSize. Если пул fixed-size, параметр почти не участвует в жизни.

Максимальный возраст соединения.

Это один из самых важных параметров для прода. Он должен быть меньше таймаута, после которого соединение может прибить база, proxy, load balancer, firewall или managed cloud-инфраструктура.

Если инфраструктура закрывает соединения через 30 минут, ставить maxLifetime = 30m плохо. Лучше 25-29 минут, в зависимости от конкретного окружения. Hikari сам добавляет небольшое размазывание по времени, чтобы не убивать весь пул разом.

Периодическая проверка idle-соединений, чтобы инфраструктура не считала их мёртвыми.

Появился не в самых древних версиях, поэтому если у вас HikariCP 3.4.5, пора посмотреть changelog и совместимость. В современных версиях дефолт около 2 минут. Значение должно быть меньше maxLifetime.

Через сколько миллисекунд Hikari логирует предупреждение, что соединение слишком долго не вернули в пул.

Дефолт: 0, то есть выключено. Минимальное значение для включения: 2000 мс.

И вот тут возвращаемся к конфигу из начала статьи:

config.setLeakDetectionThreshold(1000)

Выглядит как “ловим утечки быстрее”. На деле в современных HikariCP значение меньше 2 секунд не считается валидным. То есть такая настройка может быть просто отключена валидацией. Обидный случай: строчка есть, а пользы нет.

В проде я бы не держал короткий leak detection постоянно. Он может шуметь на нормальных длинных запросах. Лучше включать временно при расследовании или ставить порог выше ожидаемого p99 использования соединения.