OSCHINA-MIRROR/mirrors-hikaricp

HikariCP: быстрее, проще, надёжнее

HikariCP — это «нулевой» пул соединений JDBC, готовый к использованию в производстве. Библиотека имеет небольшой размер — около 130 Кб — и легковесна. Подробнее об этом читайте здесь.

"Простота — залог надёжности".
Эдсгер Вибе Дейкстра

Артефакты

Артефакт Java 11+ maven:

<dependency>
   <groupId>com.zaxxer</groupId>
   <artifactId>HikariCP</artifactId>
   <version>5.1.0</version>
</dependency>

Артефакт Java 8 maven (в режиме обслуживания):

<dependency>
   <groupId>com.zaxxer</groupId>
   <artifactId>HikariCP</artifactId>
   <version>4.0.3</version>
</dependency>

Артефакт Java 7 maven (в режиме обслуживания):

<dependency>
   <groupId>com.zaxxer</groupId>
   <artifactId>HikariCP-java7</artifactId>
   <version>2.4.13</version>
</dependency>

Артефакт Java 6 maven (в режиме обслуживания):

<dependency>
   <groupId>com.zaxxer</groupId>
   <artifactId>HikariCP-java6</artifactId>
   <version>2.3.13</version>
</dependency>

Или скачайте отсюда.

Бенчмарки JMH

Микробенчмарки были созданы для изоляции и измерения накладных расходов пулов с использованием микробенчмарка JMH. Вы можете ознакомиться с проектом HikariCP для получения более подробной информации и самостоятельно просмотреть/запустить бенчмарки.

Один цикл соединения определяется как один вызов DataSource.getConnection()/Connection.close().
Один цикл оператора определяется как один вызов Connection.prepareStatement(), Statement.execute(), Statement.close().

Версии: HikariCP 2.6.0, commons-dbcp2 2.1.1, Tomcat 8.0.24, Vibur 16.1, c3p0 0.9.5.2, Java 8u111
Intel Core i7-3770 CPU @ 3.40GHz
Бесконкурентный бенчмарк: 32 потока/32 соединения, конкурентный бенчмарк: 32 потока, 16 соединений
Apache Tomcat не может завершить операторный бенчмарк, когда используется Tomcat StatementFinalizer из-за чрезмерного времени сборки мусора.
Apache DBCP не может завершить операторный бенчмарк из-за чрезмерного времени сборки мусора. Анализ HikariCP версии 2.6 в сравнении с другими пулами в контексте уникальной нагрузки «пикового спроса».

Среда заказчика предъявляла высокие требования к стоимости получения нового соединения и требовала пул динамического размера, но при этом нуждалась в быстром реагировании на всплески запросов. Подробнее о работе с пиковым спросом читайте здесь.

Возможно, вы делаете это неправильно

AKA «Что вы, вероятно, не знали о размере пула соединений». Посмотрите видео от группы Oracle Real-world Performance и узнайте, почему пулы соединений не нужно делать такими большими, как это часто бывает. На самом деле, слишком большие пулы соединений имеют явное и заметное негативное влияние на производительность; в случае демонстрации Oracle разница составила 50 раз. Читайте дальше, чтобы узнать больше.

Анализ WIX Engineering

Мы хотели бы поблагодарить ребят из WIX за неофициальный и глубокий обзор HikariCP в их инженерном блоге. Взгляните, если у вас есть время.

Отказ: Пулы ведут себя плохо

Прочитайте нашу интересную статью «База данных не работает»: проблема с пулом.

«Плагиат — это воровство у других, а выдача чужого произведения за собственное — это кража личности» — анонимный автор.

Программное обеспечение с открытым исходным кодом, такое как HikariCP, конкурирует на свободном рынке, как и любой другой продукт. Мы понимаем, что идеи могут возникать из духа времени; одновременно и независимо. Но сроки инноваций, особенно в проектах с открытым исходным кодом, также ясны, и мы хотим, чтобы наши пользователи понимали направление потока инноваций в нашей области. Может быть деморализующим видеть результат сотен часов размышлений и исследований, так легко присвоенных, и, возможно, это присуще свободному рынку, но мы не деморализованы. Мы мотивированы; чтобы увеличить разрыв.

Отзывы пользователей

:gear: Конфигурация (ручки, детка!)

HikariCP поставляется с разумными настройками по умолчанию, которые хорошо работают в большинстве развёртываний без дополнительной настройки. Каждое свойство является необязательным, за исключением «основных», отмеченных ниже.

^📎 HikariCP использует миллисекунды для всех значений времени.

🚨 HikariCP полагается на точные таймеры как для производительности, так и для надёжности. Крайне важно, чтобы ваш сервер был синхронизирован с источником времени, таким как сервер NTP. Особенно если ваш сервер работает внутри виртуальной машины. Почему? Подробнее здесь. Не полагайтесь на настройки гипервизора для «синхронизации» часов виртуальной машины. Настройте синхронизацию источника времени. Внутри виртуальной машины.

Если вы обратитесь за поддержкой по вопросу, который окажется связанным с отсутствием синхронизации времени, вас публично высмеют в Twitter.

Essentials

🔤dataSourceClassName
Это имя класса DataSource, предоставляемого драйвером JDBC. Обратитесь к документации для вашего конкретного драйвера JDBC, чтобы получить это имя класса, или см. таблицу ниже. Обратите внимание, что источники данных XA не поддерживаются. Для XA требуется реальный менеджер транзакций, такой как bitronix. Обратите внимание: вам не нужно это свойство, если вы используете jdbcUrl для конфигурации на основе JDBC-драйвера DriverManager. По умолчанию: нет

- или -

🔤jdbcUrl
Это свойство указывает HikariCP использовать конфигурацию на основе «DriverManager». Мы считаем, что конфигурация на основе DataSource (выше) лучше по ряду причин (см. ниже), но для многих развёртываний существенной разницы нет. При использовании этого свойства со «старыми» драйверами вам также может потребоваться установить свойство driverClassName, но сначала попробуйте без него. Обратите внимание, что если используется это свойство, вы всё равно можете использовать свойства DataSource для настройки своего драйвера, и на самом деле это рекомендуется вместо параметров драйвера, указанных в самом URL. По умолчанию: нет

🔤username
Это свойство устанавливает имя пользователя по умолчанию для аутентификации, которое используется при получении Connections от базового драйвера. Обратите внимание, что для DataSources это работает очень детерминированным образом, вызывая DataSource.getConnection (имя пользователя, пароль) для базового DataSource. Однако для конфигураций на основе драйверов каждый драйвер отличается. В случае на основе драйвера HikariCP будет использовать это свойство имени пользователя для установки свойства user в свойствах, передаваемых в вызов DriverManager.getConnection(jdbcUrl, props) драйвера. Если это не то, что вам нужно, полностью пропустите этот метод и вызовите addDataSourceProperty («имя пользователя», ...), например. По умолчанию: нет

🔤password
Это свойство устанавливает пароль по умолчанию для аутентификации, который используется при получении Connections от базового драйвера. Обратите внимание, что для DataSources это работает очень детерминированным образом, вызывая DataSource.getConnection (имя пользователя, пароль) для базового DataSource. Однако для конфигураций на основе драйверов каждый драйвер отличается. В случае на основе драйвера HikariCP будет использовать это свойство пароля для установки свойства password в свойствах, передаваемых в вызов DriverManager.getConnection(jdbcUrl, props) драйвера. Если это не то, что вам нужно, полностью пропустите этот метод и вызовите addDataSourceProperty ("pass", ...), например. По умолчанию: нет

Часто используемые

✅autoCommit
Это свойство управляет поведением автофиксации по умолчанию для соединений, возвращаемых из пула. Это логическое значение. По умолчанию: true

⏳connectionTimeout
Это свойство контролирует максимальное количество миллисекунд, в течение которых клиент (то есть вы) будет ждать соединения из пула. Если это время превышено без того, чтобы соединение стало доступным, будет выдано SQLException. Наименьшее приемлемое время ожидания соединения составляет 250 мс. По умолчанию: 30000 (30 секунд)

⏳idleTimeout
Это свойство контролирует максимальный промежуток времени, в течение которого соединению разрешено простаивать в пуле. Этот параметр применяется только тогда, когда minimumIdle определён как меньше, чем maximumPoolSize. Соединения в режиме ожидания не будут удалены после достижения пулом minimumIdle соединений. Будет ли соединение удалено как находящееся в режиме ожидания или нет, зависит от максимального отклонения +30 секунд и среднего отклонения +15 секунд. Соединение никогда не будет удалено как простаивающее до этого тайм-аута. Значение 0 означает, что соединения в режиме ожидания никогда не удаляются из пула. Минимально допустимое значение — 10000мс (10 секунд). По умолчанию: 600000 (10 минут)

⏳keepaliveTime
Это свойство определяет, как часто HikariCP будет пытаться поддерживать соединение в рабочем состоянии, чтобы предотвратить его закрытие по тайм-ауту со стороны базы данных или сетевой инфраструктуры. Это значение должно быть меньше значения maxLifetime. «Поддержание соединения» будет происходить только с незанятым соединением. Когда придёт время для «поддержания соединения» в отношении данного соединения, это соединение будет удалено из пула, «пропинговано», а затем возвращено в пул. «Пингование» — это одно из следующих действий: вызов метода JDBC4 isValid() или выполнение connectionTestQuery. Как правило, длительность нахождения вне пула должна измеряться однозначными миллисекундами или даже субмиллисекундами и поэтому должна оказывать незначительное или вообще не оказывать заметного влияния на производительность. Минимально допустимое значение составляет 30000 мс (30 секунд), но наиболее желательно значение в диапазоне минут. По умолчанию: 0 (отключено)

maxLifetime Это свойство управляет максимальным временем жизни соединения в пуле. Используемое соединение никогда не будет закрыто, оно будет удалено только после закрытия. Для каждого соединения применяется небольшое отрицательное ослабление, чтобы избежать массового вымирания в пуле. Мы настоятельно рекомендуем установить это значение, и оно должно быть на несколько секунд короче, чем любой лимит времени подключения, установленный базой данных или инфраструктурой. Значение 0 указывает на отсутствие максимального времени жизни (бесконечное время жизни), конечно, с учётом настройки idleTimeout. Минимально допустимое значение — 30000 мс (30 секунд). По умолчанию: 1800000 (30 минут)

connectionTestQuery Если ваш драйвер поддерживает JDBC4, мы настоятельно рекомендуем не устанавливать это свойство. Это для «унаследованных» драйверов, которые не поддерживают API JDBC4 Connection.isValid(). Это запрос, который будет выполнен непосредственно перед тем, как соединение будет предоставлено вам из пула для проверки того, что соединение с базой данных всё ещё живо. Опять же, попробуйте запустить пул без этого свойства, HikariCP зарегистрирует ошибку, если ваш драйвер не соответствует требованиям JDBC4. По умолчанию: нет

minimumIdle Это свойство контролирует минимальное количество незанятых соединений, которые HikariCP пытается поддерживать в пуле. Если незанятые соединения опускаются ниже этого значения, а общее количество соединений в пуле меньше maximumPoolSize, HikariCP приложит все усилия, чтобы быстро и эффективно добавить дополнительные соединения. Однако для максимальной производительности и реагирования на пиковые нагрузки мы рекомендуем не устанавливать это значение и вместо этого позволить HikariCP действовать как пулу соединений фиксированного размера. По умолчанию: то же, что и maximumPoolSize

maximumPoolSize Это свойство определяет максимальный размер, которого может достичь пул, включая как незанятые, так и используемые соединения. По сути, это значение будет определять максимальное количество фактических подключений к серверной части базы данных. Разумное значение для этого лучше всего определяется вашей средой выполнения. Когда пул достигает этого размера и незанятых соединений нет, вызовы getConnection() будут блокироваться на срок до connectionTimeout миллисекунд, прежде чем истечёт время ожидания. Пожалуйста, прочтите о размере пула. По умолчанию: 10

metricRegistry Это свойство доступно только через программную конфигурацию или контейнер IoC. Это свойство позволяет указать экземпляр Codahale/Dropwizard MetricRegistry, который будет использоваться пулом для записи различных показателей. Подробные сведения см. на странице Metrics вики. По умолчанию: нет

healthCheckRegistry Это свойство доступно только через программную настройку или контейнер IoC. Это свойство позволяет вам указать экземпляр Codahale/Dropwizard HealthCheckRegistry, который будет использоваться пулом для предоставления текущей информации о работоспособности. Подробные сведения см. на странице Health Checks вики. По умолчанию: нет

poolName Это свойство представляет собой определяемое пользователем имя соединения. pool and appears mainly in logging and JMX management consoles to identify pools and pool configurations.

Default: auto-generated

Infrequently used

⏳initializationFailTimeout
Это свойство управляет тем, будет ли пул «быстро отказывать», если пул не может быть заполнен начальным соединением успешно. Любое положительное число принимается за количество миллисекунд, в течение которых будет предпринята попытка получить начальное соединение; поток приложения будет заблокирован в этот период. Если соединение не может быть получено до истечения этого тайм-аута, будет выброшено исключение. Этот тайм-аут применяется после периода connectionTimeout. Если значение равно нулю (0), HikariCP попытается получить и проверить соединение. Если соединение получено, но проверка не пройдена, будет выдано исключение, и пул не запустится. Однако, если соединение не может быть получено, пул запустится, но последующие попытки получить соединение могут завершиться неудачей. Значение меньше нуля позволит пропустить любую первоначальную попытку подключения, и пул немедленно запустится, пытаясь получить соединения в фоновом режиме. Следовательно, последующие попытки получения соединения могут завершиться неудачно. По умолчанию: 1

❎isolateInternalQueries
Это свойство определяет, изолирует ли HikariCP внутренние запросы пула, такие как проверка соединения, в собственной транзакции. Поскольку это обычно запросы только для чтения, редко бывает необходимо заключать их в собственную транзакцию. Это свойство применяется только в том случае, если autoCommit отключён. По умолчанию: false

❎allowPoolSuspension
Это свойство контролирует, может ли пул быть приостановлен и возобновлён через JMX. Это полезно для определённых сценариев автоматизации отработки отказа. Когда пул приостановлен, вызовы getConnection() не будут истекать по времени ожидания и будут удерживаться до тех пор, пока пул не возобновит работу. По умолчанию: false

❎readOnly
Это свойство управляет режимом соединений по умолчанию, которые получаются из пула в режиме только для чтения. Обратите внимание, что некоторые базы данных не поддерживают концепцию режима только для чтения, в то время как другие обеспечивают оптимизацию запросов, когда соединение установлено в режим только для чтения. Понадобится ли вам это свойство или нет, во многом зависит от вашего приложения и базы данных. По умолчанию: false

❎registerMbeans
Это свойство управляет регистрацией или отсутствием регистрации JMX Management Beans («MBeans»). По умолчанию: false

🔤catalog
Это свойство устанавливает каталог по умолчанию для баз данных, поддерживающих концепцию каталогов. Если это свойство не указано, используется каталог по умолчанию, определённый драйвером JDBC. По умолчанию: драйвер по умолчанию

🔤connectionInitSql
Это свойство задаёт оператор SQL, который будет выполняться после каждого нового создания соединения перед добавлением его в пул. Если этот SQL недействителен или вызывает исключение, он будет рассматриваться как сбой соединения, и будет следовать стандартной логике повторных попыток. По умолчанию: нет

🔤driverClassName
HikariCP попытается разрешить драйвер через DriverManager исключительно на основе jdbcUrl, но для некоторых старых драйверов также необходимо указать driverClassName. Опустите это свойство, если вы не получите очевидное сообщение об ошибке, указывающее на то, что драйвер не найден. По умолчанию: нет

🔤transactionIsolation
Это свойство управляет уровнем изоляции транзакций по умолчанию для соединений, возвращаемых из пула. Если это свойство не указано, используется уровень изоляции транзакций по умолчанию, определяемый драйвером JDBC. Используйте это свойство только в том случае, если у вас есть конкретные требования к изоляции, общие для всех запросов. Значением этого свойства является имя константы из класса Connection, такое как TRANSACTION_READ_COMMITTED, TRANSACTION_REPEATABLE_READ и т. д. По умолчанию: драйвер по умолчанию

⏳validationTimeout
Это свойство управляет максимальным временем, в течение которого соединение будет проверяться на активность. Это значение должно быть меньше, чем connectionTimeout. Наименьший приемлемый тайм-аут проверки — 250 мс. По умолчанию: 5000 leakDetectionThreshold

Это свойство определяет промежуток времени, в течение которого соединение может отсутствовать в пуле перед тем, как будет зарегистрировано сообщение о возможной утечке соединения. Значение 0 означает, что обнаружение утечек отключено. Минимально допустимое значение для включения обнаружения утечек составляет 2000 (2 секунды). По умолчанию: 0

dataSource

Это свойство доступно только через программную конфигурацию или контейнер IoC. Это свойство позволяет напрямую установить экземпляр DataSource, который будет оборачиваться пулом, вместо того чтобы HikariCP создавал его с помощью рефлексии. Это может быть полезно в некоторых средах внедрения зависимостей. Если указано это свойство, свойства dataSourceClassName и все специфичные для DataSource свойства будут игнорироваться. По умолчанию: нет

schema

Это свойство устанавливает схему по умолчанию для баз данных, поддерживающих концепцию схем. Если это свойство не указано, используется схема по умолчанию, определённая драйвером JDBC. По умолчанию: драйвер по умолчанию

threadFactory

Это свойство доступно только через программную настройку или контейнер IoC. Оно позволяет установить экземпляр java.util.concurrent.ThreadFactory, который будет использоваться для создания всех потоков, используемых пулом. Это необходимо в некоторых ограниченных средах выполнения, где потоки могут быть созданы только через ThreadFactory, предоставленный контейнером приложения. По умолчанию: нет

scheduledExecutor

Это свойство доступно только через программную настройку или контейнер IoC. Позволяет установить экземпляр java.util.concurrent.ScheduledExecutorService, который будет использоваться для различных внутренних запланированных задач. При предоставлении HikariCP экземпляра ScheduledThreadPoolExecutor рекомендуется использовать setRemoveOnCancelPolicy(true). По умолчанию: нет

Отсутствующие настройки

HikariCP имеет множество «настроек», которые можно настроить, как вы можете видеть выше, но их сравнительно меньше, чем у некоторых других пулов. Это философия дизайна. Эстетика дизайна HikariCP — минимализм. В соответствии с философией дизайна «простота лучше» или «меньше значит больше» некоторые оси конфигурации намеренно исключены.

Кэш операторов

Многие пулы соединений, включая Apache DBCP, Vibur, c3p0 и другие, предлагают кэширование PreparedStatement. HikariCP этого не делает. Почему?

На уровне пула соединений операторы PreparedStatements можно кэшировать только для каждого соединения. Если ваше приложение выполняет 250 часто выполняемых запросов, а пул состоит из 20 соединений, вы просите свою базу данных сохранить 5000 планов выполнения запросов — и аналогично пулу необходимо кэшировать такое же количество PreparedStatements и связанный с ними граф объектов.

Большинство основных драйверов JDBC для баз данных уже имеют настраиваемый кэш операторов, включая PostgreSQL, Oracle, Derby, MySQL, DB2 и многие другие. Драйверы JDBC находятся в уникальном положении, позволяющем использовать специфические функции базы данных, и почти все реализации кэширования способны совместно использовать планы выполнения между соединениями. Это означает, что вместо 5000 операторов в памяти и связанных с ними планов выполнения ваши 250 наиболее часто выполняемых запросов приводят ровно к 250 планам выполнения в базе данных. Умные реализации даже не сохраняют объекты PreparedStatement в памяти на уровне драйвера, а просто присоединяют новые экземпляры к существующим идентификаторам плана.

Использование кэша операторов на уровне пулинга является антипаттерном и негативно повлияет на производительность вашего приложения по сравнению с предоставляемыми драйверами кэшами. Быстрое восстановление

Пожалуйста, ознакомьтесь с руководством по быстрому восстановлению для получения подробной информации о том, как настроить драйвер и систему для правильного восстановления после перезапуска базы данных и событий сетевого раздела.

Инициализация

Вы можете использовать класс HikariConfig следующим образом¹:

HikariConfig config = new HikariConfig();
config.setJdbcUrl("jdbc:mysql://localhost:3306/simpsons");
config.setUsername("bart");
config.setPassword("51mp50n");
config.addDataSourceProperty("cachePrepStmts", "true");
config.addDataSourceProperty("prepStmtCacheSize", "250");
config.addDataSourceProperty("prepStmtCacheSqlLimit", "2048");

HikariDataSource ds = new HikariDataSource(config);

^{¹ Пример для MySQL, НЕ КОПИРУЙТЕ ДОСЛОВНО.}

или напрямую создать экземпляр HikariDataSource следующим образом:

HikariDataSource ds = new HikariDataSource();
ds.setJdbcUrl("jdbc:mysql://localhost:3306/simpsons");
ds.setUsername("bart");
ds.setPassword("51mp50n");
...

или на основе файла свойств:

// Проверяет как файловую систему, так и classpath на наличие файла .properties
HikariConfig config = new HikariConfig("/some/path/hikari.properties");
HikariDataSource ds = new HikariDataSource(config);

Пример файла свойств:

dataSourceClassName=org.postgresql.ds.PGSimpleDataSource
dataSource.user=test
dataSource.password=test
dataSource.databaseName=mydb
dataSource.portNumber=5432
dataSource.serverName=localhost

или основанный на java.util.Properties:

Properties props = new Properties();
props.setProperty("dataSourceClassName", "org.postgresql.ds.PGSimpleDataSource");
props.setProperty("dataSource.user", "test");
props.setProperty("dataSource.password", "test");
props.setProperty("dataSource.databaseName", "mydb");
props.put("dataSource.logWriter", new PrintWriter(System.out));

HikariConfig config = new HikariConfig(props);
HikariDataSource ds = new HikariDataSource(config);

Также доступно системное свойство hikaricp.configurationFile, которое можно использовать для указания местоположения файла свойств. Если вы собираетесь использовать эту опцию, создайте экземпляр HikariConfig или HikariDataSource, используя конструктор по умолчанию, и файл свойств будет загружен.

Советы по производительности

Советы по настройке MySQL

База данных	Драйвер	Класс DataSource
Apache Derby	Derby	org.apache.derby.jdbc.ClientDataSource
Firebird	Jaybird	org.firebirdsql.ds.FBSimpleDataSource
Google Spanner	Spanner	com.google.cloud.spanner.jdbc.JdbcDriver
H2	H2	org.h2.jdbcx.JdbcDataSource
HSQLDB	HSQLDB	org.hsqldb.jdbc.JDBCDataSource
IBM DB2	IBM JCC	com.ibm.db2.jcc.DB2SimpleDataSource
IBM Informix	IBM Informix	com.informix.jdbcx.IfxDataSource
MS SQL Server	Microsoft	com.microsoft.sqlserver.jdbc.SQLServerDataSource
~~MySQL~~	Connector/J	~~com.mysql.jdbc.jdbc2.optional.MysqlDataSource~~
MariaDB	MariaDB	org.mariadb.jdbc.MariaDbDataSource
Oracle	Oracle