Avant d'aborder la configuration de HikariCP dans Spring Boot, il convient de clarifier certains fondamentaux liés à l'accès aux bases de données en Java.
Les fondements de JDBC
L'API JDBC (Java Database Connectivity) constitue le standard Java permettant aux applications d'interagir avec des bases de données relationnelles. Elle expose un ensemble d'interfaces et de classes réparties principalement entre java.sql et javax.sql.
Les composants essentiels de cette API sont les suivants :
- DriverManager : orchestre le chargement des pilotes JDBC et fournit des connexions à la demande.
- Driver : pilote spécifique à une base de données, qui s'enregistre auprès du DriverManager.
- Connection : représente une session active avec la base de données, supportant l'exécution SQL et la gestion transactionnelle.
- Statement : permet d'exécuter des requêtes SQL statiques.
- PreparedStatement : optimise l'exécution de requêtes paramétrées grâce à une précompilation côté serveur.
- CallableStatement : dédié à l'invocation de procédures stockées.
- SQLException : encapsule les erreurs survenant durant les opérations de connexion ou d'exécution SQL.
La notion de source de données
L'API JDBC classique ne définit pas explicitement le concept de source de données (DataSource). C'est dans l'extension javax.sql qu'on trouve l'interface DataSource, qui apporte deux avantages majeurs :
- Centralisation et gestion unifiée des paramètres de connexion.
- Mise en pool des connexions pour réduire le coût d'établissement et améliorer les performances.
Plusieurs implémentations open source sont disponibles : DBCP, C3P0, Druid et HikariCP. Depuis Spring Boot 2.x, HikariCP a été retenu comme pool par défaut en raison de ses excellentes performances.
Configuration de HikariCP dans Spring Boot
Le mécanisme d'auto-configuration de Spring Boot permet de paramétrer HikariCP essentiellement via des propriétés dans application.properties ou application.yml. On distingue deux familles de propriétés.
Paramètres communs à toutes les sources de données
Ces propriétés sont préfixées par spring.datasource.* et couvrent les informations de base nécessaires quel que soit le pool utilisé :
spring.datasource.url=jdbc:postgresql://dbhost:5432/appdb
spring.datasource.username=appuser
spring.datasource.password=s3cr3t
spring.datasource.driver-class-name=org.postgresql.Driver
Paramètres spécifiques à HikariCP
Les réglages propres à HikariCP sont préfixés par spring.datasource.hikari.*. Voici une configuraton typique avec des noms de propriétés modifiés pour clarifier leur rôle :
spring.datasource.hikari.min-idle-connections=10
spring.datasource.hikari.max-pool-size=20
spring.datasource.hikari.idle-connection-timeout=500000
spring.datasource.hikari.connection-max-lifetime=540000
spring.datasource.hikari.connection-acquisition-timeout=60000
spring.datasource.hikari.health-check-query=SELECT 1
Détail de chaque propriété :
- min-idle-connections : nombre minimal de connexions inactives maintenues dans le pool. Valeur par défaut : 10. Si la valeur est négative ou supérieure à la taille maximale du pool, elle est ramenée à la taille maximale.
- max-pool-size : nombre maximum de connexions (actives et inactives). Par défaut : 10. Une valeur inférieure à 1 est ramenée à 10 ; une valeur comprise entre 0 et 1 est ajustée au minimum d'inactives.
- idle-connection-timeout : durée maximale d'inactivité d'une connexion avant éviction (en millisecondes). Par défaut : 600000 (10 minutes). Si cette valeur est supérieure ou égale à la durée de vie maximale et que celle-ci est positive, elle est remise à zéro. Une valeur non nulle inférieure à 10 secondes est relevée à 10 secondes.
- connection-max-lifetime : durée de vie maximale d'une connexion dans le pool. Par défaut : 1800000 (30 minutes). Une valeur non nulle inférieure à 30 secondes est ramenée à 30 minutes. Ce paramètre doit toujours être inférieur au timeout côté serveur de base de données.
- connection-acquisition-timeout : temps d'attente maximum pour obtenir une connexion depuis le pool (en millisecondes). Par défaut : 30000. Une valeur inférieure à 250 ms est ramenée à 30 secondes.
- health-check-query : requête SQL exécutée pour vérifier la validité d'une connexion. Inutile si le pilote supporte JDBC4.
Tableau de référence complet
| Propriété | Rôle | Valeur constructeur | Valeur après validation | Règle de validation |
|---|---|---|---|---|
| autoCommit | Active l'auto-commit des connexions retournées | true | true | – |
| connectionTimeout | Attente maximale pour obtenir une connexion (ms) | 30000 | 30000 | Si < 250 ms → 30 s |
| idleTimeout | Durée d'inactivité maximale tolérée (ms) | 600000 | 600000 | Si idleTimeout + 1s > maxLifetime et maxLifetime > 0 → 0 ; si ≠ 0 et < 10s → 10s |
| maxLifetime | Durée de vie maximale d'une connexion (ms) | 1800000 | 1800000 | Si ≠ 0 et < 30s → 30 min |
| connectionTestQuery | Requête de validation (inutile avec JDBC4) | null | null | – |
| minimumIdle | Connexions inactives minimales | -1 | 10 | Si < 0 ou > maxPoolSize → maxPoolSize |
| maximumPoolSize | Taille maximale du pool | -1 | 10 | Si < 1 → DEFAULT_POOL_SIZE (10) ; si minIdle > 0 → minIdle |
| metricRegistry | Instance MetricRegistry pour les métriques | null | null | – |
| healthCheckRegistry | Instance HealthCheckRegistry pour le suivi | null | null | – |
| poolName | Nom identifiant le pool dans les logs et JMX | null | HikariPool-1 | – |
| initializationFailTimeout | Échec rapide si l'init du pool échoue | 1 | 1 | – |
| isolateInternalQueries | Isole les requêtes intternes dans leur propre transaction | false | false | – |
| allowPoolSuspension | Autorise la suspension/reprise via JMX | false | false | – |
| readOnly | Connexions en mode lecture seule par défaut | false | false | – |
| registerMbeans | Enregistrement des MBeans JMX | false | false | – |
| catalog | Catalogue par défaut pour les bases compatibles | défaut pilote | null | – |
| connectionInitSql | SQL exécuté à la création de chaque connexion | null | null | – |
| driverClassName | Nom du pilote (utile pour les anciens drivers) | null | null | – |
| transactionIsolation | Niveau d'siolation par défaut des connexions | null | null | – |
| validationTimeout | Temps maximum pour le test de validité (ms) | 5000 | 5000 | Si < 250 ms → 5 s |
| leakDetectionThreshold | Seuil de détection de fuite de connexion (ms) | 0 | 0 | Si > 0 et non test unitaire : si < 2000 ms ou > maxLifetime (quand > 0) → 0 |
| dataSource | Instance de source de données injectée directement | null | null | – |
| schema | Schéma par défaut pour les bases compatibles | défaut pilote | null | – |
| threadFactory | ThreadFactory personnalisé pour les threads du pool | null | null | – |
| scheduledExecutor | ScheduledExecutorService pour les tâches internes | null | null | – |