Spring Boot DataSource Configuration with HikariCP Examples

A DataSource is the object our code asks for a database connection, and Spring Boot builds it from a few properties. Spring Boot reads the URL, user name and password from application.properties and builds a HikariCP connection pool (that is, a set of open connections that the application reuses instead of opening a new connection for every query).

Every JDBC query, JPA repository call or JdbcClient call gets its connection from the DataSource, so we configure it once for each database the application uses. For a typical application, we add a JDBC starter and the database driver, and set three properties.

The following example connects a recipe application to PostgreSQL and checks the DataSource that Spring Boot injects.

spring.datasource.url=jdbc:postgresql://localhost:5432/recipes
spring.datasource.username=chef
spring.datasource.password=secret
# Optional: Spring Boot deduces the driver class from the URL
spring.datasource.driver-class-name=org.postgresql.Driver

@Autowired DataSource dataSource;

HikariDataSource hikari = (HikariDataSource) dataSource;
String type = hikari.getClass().getSimpleName();   // HikariDataSource
String url = hikari.getJdbcUrl();                  // jdbc:postgresql://localhost:5432/recipes
int maxPool = hikari.getMaximumPoolSize();         // 10 (HikariCP default)

Notice that the driver class property is optional, and that the pool holds at most 10 connections by default.

Next, we look at how Spring Boot picks the DataSource and how we tune the HikariCP pool. After that, we cover DataSourceBuilder, a second database, schema.sql and data.sql, tests with H2 and Testcontainers, and the “url attribute is not specified” startup error.

1. What Is a DataSource in Spring Boot?

A DataSource is a factory for JDBC connections. To run a query, our code calls dataSource.getConnection() on a DataSource and gets a connection back, without knowing the database URL, the password, or whether the connection is new or reused.

In Spring Boot 4, the interface is still javax.sql.DataSource. Many packages moved from javax to jakarta, but javax.sql.DataSource stayed because the interface belongs to the JDK, not to Jakarta EE.

The older way to get a connection is DriverManager. Because each web request needs a connection, the difference between DriverManager and a pooled DataSource matters in every web application. For example, when 50 users open a recipe page at the same time, DriverManager opens 50 new database connections, whereas a pool of 10 reuses its open connections and lets the other requests wait.

	DriverManager.getConnection(url, user, password)	Pooled DataSource (HikariCP)
New database connection per call	Yes, a new TCP connection and login	No, an open connection from the pool
Where the URL and password are stored	In the calling code	In configuration, read once at startup
What close() does	Closes the real connection to the database	Gives the connection back to the pool
Limit on open connections	None	maximum-pool-size, 10 by default

In a Spring Boot application, the DataSource is a bean (an object that the Spring container creates and manages for us), and every JDBC, JPA or JdbcClient call gets its connections from that bean.

1.1. How Spring Boot Chooses the DataSource

Spring Boot creates the DataSource bean for us at startup through a feature called auto-configuration. The class that does the work, DataSourceAutoConfiguration, asks a few questions in a fixed order, and the first question with a “yes” answer decides which DataSource we get.

The JDBC starter brings HikariCP, but the database driver is a separate dependency. No starter adds a database driver for us. So a missing driver dependency is a common cause of startup errors.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-jdbc</artifactId>   <!-- brings HikariCP -->
</dependency>
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <scope>runtime</scope>
</dependency>

The starter spring-boot-starter-data-jpa depends on spring-boot-starter-jdbc, so a JPA project gets HikariCP the same way. When HikariCP is missing, Spring Boot looks for the other pools in this order.

1. HikariCP (com.zaxxer.hikari.HikariDataSource)
2. Tomcat JDBC pool (org.apache.tomcat.jdbc.pool.DataSource)
3. Commons DBCP2 (org.apache.commons.dbcp2.BasicDataSource)
4. Oracle UCP (oracle.ucp.jdbc.PoolDataSource)

We can skip the pool search with the spring.datasource.type property, which names the pool class, for example spring.datasource.type=org.apache.commons.dbcp2.BasicDataSource.

2. Spring Boot DataSource Configuration Example

Our example is a small recipe application that runs on Spring Boot 4.1.1, Java 25, HikariCP 7.0.2 and H2 2.4.240. The main database, recipes, holds the recipes, and a second database, audit, records who read them.

The complete project on GitHub checks every value shown here with 15 JUnit tests. We run the tests with mvn test, and the PostgreSQL test needs Docker.

2.1. DataSource Properties for MySQL, PostgreSQL, Oracle and SQL Server

For a real database, only spring.datasource.url is required, and we add username and password when the database asks for them. We do not need to name the driver class, because Spring Boot looks at the start of the URL, such as jdbc:mysql, and picks the driver. The driver class for each URL comes from DatabaseDriver.fromJdbcUrl(), the method Spring Boot calls for that check.

Database	spring.datasource.url	Driver class Spring Boot deduces
H2 (in memory)	jdbc:h2:mem:recipes	org.h2.Driver
MySQL	jdbc:mysql://localhost:3306/recipes	com.mysql.cj.jdbc.Driver
MariaDB	jdbc:mariadb://localhost:3306/recipes	org.mariadb.jdbc.Driver
PostgreSQL	jdbc:postgresql://localhost:5432/recipes	org.postgresql.Driver
Oracle	jdbc:oracle:thin:@localhost:1521/FREEPDB1	oracle.jdbc.OracleDriver
SQL Server	jdbc:sqlserver://localhost;databaseName=recipes	com.microsoft.sqlserver.jdbc.SQLServerDriver

In YAML, the same configuration uses nested keys.

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/recipes
    username: chef
    password: secret

Old tutorials also set spring.jpa.database-platform to a dialect such as MySQL5InnoDBDialect or Oracle10gDialect. A dialect tells Hibernate which SQL variant the database uses. With Hibernate 6 and 7, we leave the dialect out. Hibernate reads the database type and version from the connection, and the versioned dialect classes such as MySQL5InnoDBDialect are no longer in hibernate-core 7.4.

2.2. Tuning the HikariCP Connection Pool

Every HikariCP setting has a matching property under *spring.datasource.hikari.**. Our main database uses a pool named recipes-pool, which holds up to 10 connections and keeps 2 connections open when the application is idle.

spring.datasource.hikari.pool-name=recipes-pool
spring.datasource.hikari.maximum-pool-size=10
spring.datasource.hikari.minimum-idle=2
spring.datasource.hikari.connection-timeout=30000
spring.datasource.hikari.idle-timeout=600000
spring.datasource.hikari.max-lifetime=1800000

At startup, HikariCP logs the pool name and the first connection it opens.

com.zaxxer.hikari.HikariDataSource : recipes-pool - Starting...
com.zaxxer.hikari.pool.HikariPool  : recipes-pool - Added connection conn1: url=jdbc:h2:mem:recipes user=SA
com.zaxxer.hikari.HikariDataSource : recipes-pool - Start completed.

Most applications change only a few of the HikariCP settings. The defaults come from a new HikariConfig object in HikariCP 7.0.2.

Property (spring.datasource.hikari.)	Default	What it controls
maximum-pool-size	10	Largest number of connections in the pool, busy and idle together
minimum-idle	Same as maximum-pool-size	Idle connections the pool keeps open
connection-timeout	30000 ms	How long getConnection() waits for a free connection before it throws an exception
idle-timeout	600000 ms (10 min)	When the pool closes an idle connection above minimum-idle
max-lifetime	1800000 ms (30 min)	Oldest age of a connection. Keep it below the database’s own timeout.
keepalive-time	120000 ms (2 min)	How often the pool tests an idle connection
leak-detection-threshold	0 (off)	Logs a warning when code holds a connection longer than this time
pool-name	HikariPool-1, HikariPool-2, …	Name in logs and metrics

A bigger pool is not a faster pool. Each connection is a session on the database server, and the database runs only a limited number of queries at the same time. So we start with the default of 10 and raise the size only when metrics show threads waiting for a connection.

The Tomcat and DBCP2 pools use their own prefixes, *spring.datasource.tomcat. and *spring.datasource.dbcp2., and the property names under those prefixes come from each library.

2.3. Creating a DataSource Bean With DataSourceBuilder

When we want to create the DataSource in Java code, we use DataSourceBuilder. If we do not call type(), the builder picks the first pool on the classpath, which is HikariCP with the JDBC starter, so we get a HikariDataSource.

DataSource ds = DataSourceBuilder.create()
    .url("jdbc:h2:mem:builder")
    .username("sa")
    .password("")
    .build();

String type = ds.getClass().getSimpleName();                    // HikariDataSource
String driver = ((HikariDataSource) ds).getDriverClassName();   // org.h2.Driver (deduced from the URL)

DataSource simple = DataSourceBuilder.create()
    .type(SimpleDriverDataSource.class)                         // a non-pooled DataSource from Spring JDBC
    .url("jdbc:h2:mem:simple")
    .build();                                                   // SimpleDriverDataSource

We hard-code URLs and passwords only in tests. In an application, we declare the builder as a @Bean, and @ConfigurationProperties fills in the builder’s settings from the properties file.

@Bean
@ConfigurationProperties("app.datasource")
DataSource dataSource() {
  return DataSourceBuilder.create().build();
}

app.datasource.jdbc-url=jdbc:h2:mem:mine
app.datasource.username=sa

When we declare our own DataSource bean, Spring Boot’s auto-configuration backs off. Spring Boot no longer creates its own DataSource. In our test, spring.datasource.url was set as well, but Spring Boot ignored it and the bean used jdbc:h2:mem:mine.

Notice that the property key is jdbc-url, not url. Spring binds each property to a setter method on HikariDataSource, and HikariCP has a setJdbcUrl() method but no setUrl() method. So with app.datasource.url, the bean starts without a URL and the first getConnection() call fails.

java.lang.IllegalArgumentException: dataSource or dataSourceClassName or jdbcUrl is required.

Section 2.4 uses DataSourceProperties instead, which accepts url and converts the value for HikariCP.

2.4. Configuring Multiple DataSources

A second database needs a second DataSource bean. Spring Boot 4 supports two ways to set up a second database, and they differ in what happens to the DataSource that Spring Boot creates for us.

Spring Boot recommends option A, which uses @Bean(defaultCandidate = false), available since Spring Framework 6.2. Spring injects a bean with defaultCandidate = false only where we ask for it with @Qualifier, and Spring Boot ignores it when it checks for our own DataSource. So Spring Boot still creates the auto-configured DataSource.

@Bean(defaultCandidate = false)
@Qualifier("audit")
@ConfigurationProperties("app.datasource.audit")
DataSourceProperties auditDataSourceProperties() {
  return new DataSourceProperties();
}

@Bean(defaultCandidate = false)
@Qualifier("audit")
@ConfigurationProperties("app.datasource.audit.configuration")
HikariDataSource auditDataSource(@Qualifier("audit") DataSourceProperties properties) {
  return properties.initializeDataSourceBuilder().type(HikariDataSource.class).build();
}

DataSourceProperties is the class behind the *spring.datasource.** properties, so the audit database uses the same url, username and password keys, while HikariCP settings go under an extra configuration prefix.

app.datasource.audit.url=jdbc:h2:mem:audit
app.datasource.audit.username=sa
app.datasource.audit.password=
app.datasource.audit.configuration.pool-name=audit-pool
app.datasource.audit.configuration.maximum-pool-size=3

A DataSource parameter without a qualifier still gets the main database, whereas the @Qualifier annotation selects the audit database.

public RecipeService(DataSource dataSource, @Qualifier("audit") DataSource auditDataSource) {
  this.recipes = JdbcClient.create(dataSource);       // jdbc:h2:mem:recipes
  this.audit = JdbcClient.create(auditDataSource);    // jdbc:h2:mem:audit
}

main : HikariDataSource jdbc:h2:mem:recipes pool=recipes-pool max=10
audit: HikariDataSource jdbc:h2:mem:audit pool=audit-pool max=3
recipes      = [Pancakes, Omelette]
audit events = 1

Option B is the setup in most older tutorials, and it still works in Spring Boot 4. We declare two DataSource beans and mark one of them with @Primary, which Spring injects by default. Because we declare DataSource beans ourselves, Spring Boot does not create its own DataSource and uses *spring.datasource.** for neither database.

@Bean
@Primary
@ConfigurationProperties("app.datasource.recipes")
DataSource recipesDataSource() {
  return DataSourceBuilder.create().build();
}

@Bean
@ConfigurationProperties("app.datasource.audit")
DataSource auditDataSource() {
  return DataSourceBuilder.create().build();
}

app.datasource.recipes.jdbc-url=jdbc:h2:mem:recipes2
app.datasource.recipes.username=sa
app.datasource.recipes.maximum-pool-size=5
app.datasource.audit.jdbc-url=jdbc:h2:mem:audit2
app.datasource.audit.username=sa

In option B, the bean name works as the qualifier, as in @Qualifier(“auditDataSource”). HikariCP settings such as maximum-pool-size go under the same prefix as jdbc-url, because these properties bind straight to the HikariDataSource.

With JPA, each database also needs its own EntityManagerFactory and its own transaction manager.

2.5. Using a JNDI DataSource on an Application Server

Java application servers such as WildFly or WebLogic can run our application as a WAR file. On an application server, the administrator often defines the connection pool, and the application looks it up by name through JNDI (Java Naming and Directory Interface). Spring Boot 4 still supports JNDI with one property, which replaces url, username and password.

spring.datasource.jndi-name=java:jboss/datasources/recipes

Here the server creates and manages the pool, so *spring.datasource.hikari.** settings have no effect. The usual Spring Boot setup is an executable JAR with embedded Tomcat, which has no JNDI server, so JNDI does not apply there.

2.6. Embedded Database Defaults

An embedded database runs inside the application’s JVM. When spring.datasource.url is not set and H2, HSQLDB or Derby is on the classpath, Spring Boot creates an in-memory database with these settings.

embedded url = jdbc:h2:mem:0df15f3a-096d-4258-80bd-f8f30aa44aeb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE, user = sa

The pool is still HikariCP, and the database name is a random UUID, so two application contexts in one test run never share data.

Property	Default	Effect
spring.datasource.generate-unique-name	true	Random database name. With false, the URL is jdbc:h2:mem:testdb.
spring.datasource.username	sa	User of the embedded database
spring.datasource.password	empty	No password
spring.datasource.embedded-database-connection	detected	h2, hsql or derby. The value none turns embedded databases off.

The in-memory database disappears when the application stops. If we want to keep data after a restart, we set a file URL such as jdbc:h2:file:./data/recipes. H2 also has a file mode and a web console.

2.7. Loading schema.sql and data.sql With spring.sql.init

When the application starts, Spring Boot runs two scripts from src/main/resources. The script schema.sql runs first and creates the tables, and data.sql runs next and inserts the rows. Our scripts create the recipe table and insert two recipes.

create table recipe (
  id      int generated by default as identity primary key,
  name    varchar(100) not null,
  minutes int not null
);

insert into recipe (name, minutes) values ('Pancakes', 20);
insert into recipe (name, minutes) values ('Omelette', 10);

The spring.sql.init.mode property decides when the scripts run.

• The value embedded (default) runs the scripts only for an embedded database such as H2.
• The value always runs the scripts for every database, including MySQL and PostgreSQL.
• The value never turns script loading off.

The scripts run only on the auto-configured DataSource. In our example, the recipe table exists in recipes but not in audit, so a query on the audit database failed with Table “RECIPE” not found. To create the audit tables, the audit database gets its own initializer bean.

@Bean
DataSourceScriptDatabaseInitializer auditDatabaseInitializer(@Qualifier("audit") DataSource audit) {
  DatabaseInitializationSettings settings = new DatabaseInitializationSettings();
  settings.setSchemaLocations(List.of("classpath:audit-schema.sql"));
  settings.setMode(DatabaseInitializationMode.ALWAYS);
  return new DataSourceScriptDatabaseInitializer(audit, settings);
}

Other script settings are spring.sql.init.schema-locations, spring.sql.init.data-locations, spring.sql.init.continue-on-error and spring.sql.init.platform. For example, with platform=postgresql, Spring Boot also loads schema-postgresql.sql. With JPA, the scripts run before Hibernate creates tables, and setting spring.jpa.defer-datasource-initialization=true reverses the order.

For production schemas, a migration tool such as Flyway or Liquibase is the better choice, because it records which changes already ran.

See also Load Initial Data with SQL Scripts in Spring Boot

2.8. Testing the DataSource With H2 and Testcontainers

@JdbcTest starts only the JDBC part of the application, so the test gets the DataSource, JdbcClient, JdbcTemplate and the SQL scripts. By default, @JdbcTest also replaces our configured DataSource with an embedded database, so the test runs on H2 even when application.properties points to PostgreSQL.

@JdbcTest
class RecipeJdbcTest {

  @Autowired DataSource dataSource;
  @Autowired JdbcClient jdbcClient;

  @Test
  void runsAgainstEmbeddedDatabaseWithSchemaAndData() {
    String type = dataSource.getClass().getSimpleName();   // EmbeddedDataSourceProxy
    List<String> names = jdbcClient.sql("select name from recipe order by id")
        .query(String.class).list();                       // [Pancakes, Omelette]
  }
}

H2 does not behave the same as PostgreSQL or MySQL in every case. To test against the real database, we use Testcontainers, which starts the database in Docker. The @ServiceConnection annotation passes the container’s URL, user and password to the DataSource, so we write no spring.datasource.url for tests. Spring Boot 4 uses the Testcontainers 2 artifact names.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-jdbc-test</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-testcontainers</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-postgresql</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-junit-jupiter</artifactId>
  <scope>test</scope>
</dependency>

@JdbcTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)   // keep the real DataSource
@Testcontainers(disabledWithoutDocker = true)
class RecipePostgresTest {

  @Autowired DataSource dataSource;
  @Autowired JdbcClient jdbcClient;

  @Container
  @ServiceConnection
  static PostgreSQLContainer postgres = new PostgreSQLContainer("postgres:17-alpine");

  @Test
  void runsAgainstPostgres() throws Exception {
    try (Connection connection = dataSource.getConnection()) {
      String url = connection.getMetaData().getURL();   // jdbc:postgresql://localhost:32770/test?loggerLevel=OFF
    }
    List<String> names = jdbcClient.sql("select name from recipe order by id")
        .query(String.class).list();                    // [Pancakes, Omelette]
  }
}

Docker picks a free port, so the port changes on every run. The same schema.sql runs on H2 and on PostgreSQL, because generated by default as identity is standard SQL and both databases accept it.

A test that starts only one part of the application, such as a @JdbcTest test, is called a test slice. The JPA version of the slice is @DataJpaTest.

3. Spring Boot DataSource FAQs

3.1. Why Does Startup Fail When spring.datasource.url Is Missing?

Startup fails because Spring Boot found nothing to connect to. The application declared no DataSource bean and set no spring.datasource.url, and the classpath had no embedded database driver. The flowchart in section 1.1 shows the failure as the last box. To reproduce the failure, we started the application without a URL and with H2 removed from the classpath.

***************************
APPLICATION FAILED TO START
***************************

Description:

Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured.

Reason: Failed to determine a suitable driver class


Action:

Consider the following:
	If you want an embedded database (H2, HSQL or Derby), please put it on the classpath.
	If you have database settings to be loaded from a particular profile you may need to activate it (no profiles are currently active).

The message has four common causes, and each cause has its own fix.

Cause	Fix
The URL is in a profile file such as application-dev.properties. No profile is active.	Start with –spring.profiles.active=dev. Or move the URL to application.properties (DataSource per profile).
A typo in the key, such as spring.datasource.uri or spring.data-source.url	Use the key spring.datasource.url
The properties file is in the wrong folder, so the file is not on the classpath	Put the file in src/main/resources
The application needs no database, but a JDBC or JPA starter is on the classpath	Remove the starter, or exclude the auto-configuration (see the next snippet)

For the last case, notice the import, because in Spring Boot 4 the auto-configuration class moved to a new package.

import org.springframework.boot.jdbc.autoconfigure.DataSourceAutoConfiguration;   // Spring Boot 4

@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
public class Application { }

3.2. Do We Need spring.datasource.driver-class-name?

No, in most cases, because Spring Boot deduces the driver from the start of the URL, as the table in section 2.1 shows. In our DataSourceBuilder test, an H2 URL without the property got the driver org.h2.Driver.

We set the property only for a driver that Spring Boot does not know, and in that case the driver class must be on the classpath. The class com.mysql.jdbc.Driver is the old name from MySQL Connector/J 5, whereas the current MySQL driver class is com.mysql.cj.jdbc.Driver.

3.3. How Do We Keep the Database Password Out of application.properties?

We use environment variables, because Spring Boot reads them too. The variable name is the property name in upper case, with underscores, so for example spring.datasource.url becomes SPRING_DATASOURCE_URL. Environment variables override application.properties. We started the example with two variables, and the pool used their values.

SPRING_DATASOURCE_URL=jdbc:h2:mem:fromenv SPRING_DATASOURCE_HIKARI_POOL_NAME=env-pool mvn spring-boot:run
# main : HikariDataSource jdbc:h2:mem:fromenv pool=env-pool max=10

In production, we set SPRING_DATASOURCE_PASSWORD the same way, with the value coming from the deployment platform or a secrets manager, so the password stays out of the repository.

3.4. Which DataSource Gets Injected When There Are Two?

The answer depends on the setup, because a DataSource injection point (a constructor parameter or field where Spring passes in a bean) without a qualifier needs a single candidate bean. With option A from section 2.4, the auto-configured bean is the only default candidate, and with option B, Spring injects the @Primary bean. With two beans and neither setup, startup fails at the first injection point that does not name a bean.

NoUniqueBeanDefinitionException: No qualifying bean of type 'javax.sql.DataSource' available: expected single matching bean but found 2: recipesDataSource,auditDataSource

To fix the error, we add @Primary to one bean or defaultCandidate = false to the extra bean, and adding @Qualifier at every injection point also works.

4. Conclusion

For one database, Spring Boot needs only spring.datasource.url, username and password, and it deduces the driver and creates a HikariCP pool with 10 connections. We tune the pool with *spring.datasource.hikari.**, and we use DataSourceBuilder when the DataSource must be built in code.

For a second database, we use @Bean(defaultCandidate = false), so the auto-configured DataSource stays in place, but spring.sql.init loads scripts into the main database only. @JdbcTest gives each test an embedded H2 database, and Testcontainers with @ServiceConnection runs the same tests on the real database.

5. References

• Spring Boot Reference: SQL Databases
• Spring Boot How-to: Data Access
• Spring Boot How-to: Database Initialization
• Spring Boot Reference: Testcontainers
• Spring Boot Application Properties: Data
• DataSourceBuilder JavaDoc
• DataSourceProperties JavaDoc
• Testcontainers PostgreSQL Module

Happy Learning !!

Source Code on Github