Spring Boot DataSource: Auto-Configured, Custom, and Multiple Databases

DataSource configuration is one of those things you set up once and forget about, until it breaks. Connection timeouts and pool exhaustion errors are notoriously hard to reproduce locally and show up at the worst possible moment in production. This guide covers the three scenarios you will encounter: letting Spring Boot handle everything via auto-configuration, wiring up a custom DataSource when you need fine-grained control, and configuring multiple independent DataSources for multi-tenant or polyglot persistence architectures.

When to Use DataSource Configuration

Introduction

A Spring Boot data source supplies the database connections used by repositories, JDBC operations, and ORM components. This guide explains auto-configuration, property-based setup, profiles, credentials, connection pools, and the production checks that keep database connectivity predictable and secure.

When Not to Use DataSource Configuration

If you have a single PostgreSQL database and your connection pool needs are unremarkable, the auto-configured HikariCP instance is almost certainly fine. Adding custom configuration in this case introduces complexity without benefit.

Do not configure multiple DataSources if you only need to occasionally query an external API or cache layer. A REST template or a dedicated client bean handles these interactions more cleanly and avoids the @Primary and @Qualifier entanglement that comes with multiple DataSources.

Pool sizing depends on your database’s max_connections setting, your application’s concurrency characteristics, and your query patterns. Setting pool size to 50 because that sounds reasonable is how you end up with exhausted pools or database-level resource starvation.

DataSource Configuration Flow

The following diagram shows how a DataSource bean flows from configuration properties through auto-configuration to the final resolved bean in your application context.

graph TD
    A["spring.datasource.url<br/>spring.datasource.username<br/>spring.datasource.password"] --> B["DataSourceProperties<br/>Bean"]
    B --> C["DataSource auto-configuration<br/>HikariCP auto-configured"]
    C --> D["DataSource bean<br/>in ApplicationContext"]
    E["@DataSourceDefinition<br/>Programmatic config"] --> D
    F["Multiple DataSource<br/>@Primary + @Qualifier"] --> D
    G["Custom DataSourceProperties<br/>@Configuration class"] --> D

Spring Boot’s auto-configuration activates when it detects spring-boot-starter-data-jpa or spring-boot-starter-jdbc on the classpath. DataSourceProperties maps your spring.datasource.* properties to a canonical form, and the auto-configuration classes create the actual DataSource bean using HikariCP as the default pool.

Failure Scenarios

Connection Pool Exhaustion

HikariCP has a hard limit on concurrent borrowed connections. When your application requests a connection and the pool is empty, HikariCP waits up to connectionTimeout milliseconds. If no connection arrives, you get a PoolExhaustedException. This happens when queries take longer than expected under load, or when your pool size is too small for the concurrency your application handles.

Misconfiguration

Missing or malformed spring.datasource.url trips up most people. Spring Boot can usually infer the driver class from the URL, but unusual JDBC drivers or non-standard URL formats may require an explicit spring.datasource.driver-class-name.

Plain text credentials in application.properties is a security misconfiguration that creates audit risk. Externalize credentials to a secrets manager and inject them at runtime.

Transaction Routing Issues

When you configure multiple DataSources, Spring needs to know which one to use by default. Forgetting @Primary on one of them throws NoUniqueBeanDefinitionException at startup.

Routing transactions to the wrong database is subtler. If your application uses @Transactional and expects a read replica but the transaction manager is bound to the primary, you will not get the load distribution you designed for.

Trade-off Table

Aspect	HikariCP (Default)	Tomcat Pool	DBCP2	Oracle UCP
Default pool	Yes	No	No	No
Performance	Fastest	Good	Moderate	Good
Configuration simplicity	Properties prefix	spring.datasource.tomcat.*	spring.datasource.dbcp2.*	spring.datasource.oracleucp.*
JMX metrics	Built-in	Built-in	Limited	Built-in
Fairness algorithm	Yes	Yes	No	Yes
Connection testing	Idle timeout + connection test	Test on borrow	Test on borrow	Test on borrow

Aspect	Auto-Configuration	Manual Configuration
Setup time	Instant	Requires explicit bean definitions
Flexibility	Limited to documented properties	Full control over bean lifecycle
Multi-database support	Single only	Multiple with qualifiers
Production tuning	Requires override	Built-in from the start
Code complexity	None	Additional @Configuration class

Implementation Snippets

Standard Auto-Configuration

The simplest configuration requires only the JDBC URL and credentials:

spring.datasource.url=jdbc:postgresql://localhost:5432/myapp
spring.datasource.username=dbuser
spring.datasource.password=dbpass
spring.datasource.hikari.maximum-pool-size=20
spring.datasource.hikari.connection-timeout=30000
spring.datasource.hikari.idle-timeout=600000

Spring Boot automatically creates a HikariDataSource bean with these settings. No Java configuration needed for straightforward cases.

Programmatic DataSource Definition

Use @DataSourceDefinition when you want to define a DataSource directly on a @Bean method or a @DataSourceDefinition annotation on a managed bean:

import javax.sql.DataSource;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import com.zaxxer.hikari.HikariDataSource;
import org.springframework.boot.context.properties.ConfigurationProperties;

@Configuration
public class DataSourceConfig {

    @Bean
    @ConfigurationProperties(prefix = "app.datasource")
    public DataSource dataSource() {
        return new HikariDataSource();
    }
}

app.datasource.url=jdbc:mysql://localhost:3306/myapp
app.datasource.username=dbuser
app.datasource.password=dbpass
app.datasource.maximum-pool-size=15

Multiple DataSources

When your application needs to connect to two or more independent databases, you need to define each DataSource explicitly with qualifiers and mark one as @Primary:

@Configuration
public class MultiDataSourceConfig {

    @Primary
    @Bean
    @ConfigurationProperties("app.datasource.primary")
    public DataSourceProperties primaryDataSourceProperties() {
        return new DataSourceProperties();
    }

    @Primary
    @Bean
    public DataSource primaryDataSource() {
        return primaryDataSourceProperties()
            .initializeDataSourceBuilder()
            .type(HikariDataSource.class)
            .build();
    }

    @Bean
    @ConfigurationProperties("app.datasource.secondary")
    public DataSourceProperties secondaryDataSourceProperties() {
        return new DataSourceProperties();
    }

    @Bean
    public DataSource secondaryDataSource() {
        return secondaryDataSourceProperties()
            .initializeDataSourceBuilder()
            .type(HikariDataSource.class)
            .build();
    }
}

app.datasource.primary.url=jdbc:postgresql://localhost:5432/primarydb
app.datasource.primary.username=primaryuser
app.datasource.primary.password=primarypass

app.datasource.secondary.url=jdbc:postgresql://localhost:5432/secondarydb
app.datasource.secondary.username=secondaryuser
app.datasource.secondary.password=secondarypass

Inject specific DataSources using @Qualifier:

@Service
public class ReportingService {

    private final DataSource secondaryDataSource;

    public ReportingService(
            @Qualifier("secondaryDataSource") DataSource secondaryDataSource) {
        this.secondaryDataSource = secondaryDataSource;
    }
}

Observability Checklist

HikariCP exposes metrics through JMX and integrates with Micrometer for Prometheus scraping. Here is what to watch.

• Active connections — number of connections currently borrowed from the pool
• Idle connections — number of connections sitting in the pool waiting to be used
• Pending threads — number of threads waiting for a connection when the pool is exhausted
• Connection timeout rate — how often connection requests time out (indicates pool saturation)
• Connection creation time — how long it takes to establish a new connection
• Connection usage time — how long borrowed connections are held
• Connection leak detection — HikariCP can log stack traces when connections are not returned within a configurable threshold

Enable HikariCP metrics collection:

spring.datasource.hikari.register-mbeans=true
management.metrics.enable.hikaricp=true

Spring Boot Actuator exposes health checks for DataSource connectivity:

management.endpoint.health.show-details=always
management.endpoint.health.show-components=always

Add a custom health indicator if you need to verify connectivity to specific databases in a multi-DataSource setup:

@Component
public class SecondaryDataSourceHealthIndicator
        extends AbstractDataSourceHealthIndicator {

    public SecondaryDataSourceHealthIndicator(
            @Qualifier("secondaryDataSource") DataSource dataSource) {
        super(dataSource);
    }

    @Override
    protected Mono<Health> doHealthCheck(Health.Builder builder) {
        return Mono.fromSupplier(() -> {
            builder.up();
            return builder.build();
        });
    }
}

Security Notes

Credentials should never appear in plain text in configuration files that are committed to source control. Use environment variable substitution or a secrets manager integration.

spring.datasource.username=${DB_USER}
spring.datasource.password=${DB_PASSWORD}

Spring Boot supports credential injection via environment variables, Docker secrets, Kubernetes secrets, or external secrets managers like HashiCorp Vault or AWS Secrets Manager. Choose a mechanism that fits your deployment pipeline and audit requirements.

Connection encryption using TLS should be enabled for any database connection that crosses a network boundary. Most cloud-managed databases require SSL connections and reject non-encrypted connections by default.

spring.datasource.url=jdbc:postgresql://host:5432/db?ssl=true&sslmode=require

Verify the SSL certificate presented by the database server to prevent man-in-the-middle attacks:

spring.datasource.hikari.data-source-properties.ssl=true
spring.datasource.hikari.data-source-properties.sslmode=verify-full
spring.datasource.hikari.data-source-properties.sslcert=/path/to/ca-cert.pem

Connection pool settings should be reviewed to prevent resource exhaustion attacks. Setting maximumPoolSize too high can starve the database’s connection limit for other applications or administrative sessions. Setting connectionTimeout too high can cause your application to hang indefinitely when the database is unreachable.

Security and Compliance Notes

DataSource configuration touches credentials, network boundaries, and resource limits — all security-sensitive areas.

Credential Storage in Configuration

Never store database passwords in plain text. Use environment variable substitution: spring.datasource.password=${DB_PASSWORD}. For Kubernetes, use Secrets. For enterprise environments, integrate with HashiCorp Vault or AWS Secrets Manager. Audit access to wherever credentials are stored and rotate them on a schedule.

TLS/SSL for Database Connections

Any database connection crossing a network boundary should use TLS. Cloud-managed databases increasingly require SSL and reject unencrypted connections. Configure ssl=true in your JDBC URL and use sslmode=verify-full to validate the server certificate. For production databases, enable certificate verification to prevent man-in-the-middle attacks.

Network Access Controls

Restrict database access to application servers only. Use firewall rules or security groups to prevent direct database access from developer workstations or other networks. Spring Boot applications should connect through the application tier, not directly to databases from frontend layers.

Connection Pool Resource Limits

Setting maximumPoolSize too high can starve other applications sharing the same database. Know your database’s total connection limit and allocate pool sizes that leave headroom for administrative access and connection overhead. Monitor actual connection usage against pool configuration.

Read-Only Replica Routing for Security

In a primary-replica configuration, route read-only queries to replicas and write queries to the primary. This reduces load on the primary and limits exposure if a replica is compromised. Implement AbstractRoutingDataSource to route readOnly = true transactions to replicas automatically.

Credential Least Privilege

Create application database users with minimum required privileges. An application user rarely needs SUPERUSER, CREATEDB, or CREATE privileges. Separate read and write operations if your framework supports it. Audit privilege grants regularly and remove unnecessary permissions.

Production Failure Scenarios

DataSource configuration problems are deceptively hard to debug because they only surface under load or during infrastructure events. Here are the scenarios that send engineers to production at odd hours.

Connection Pool Exhaustion Under Traffic Spikes

When traffic spikes and the connection pool is exhausted, HikariCP waits up to connectionTimeout for a connection. If your pool size is too small for peak load, requests queue up and eventually fail with PoolExhaustedException. Right-size maximumPoolSize based on load testing, not gut feel. Monitor pending threads waiting for connections as an early warning indicator.

HikariCP Timeout During Database Failover

Cloud databases fail over to standby replicas during maintenance windows or outages. Existing connections are terminated, and HikariCP must create new connections to the new primary. During this window, connection attempts fail. HikariCP retries automatically, but your application needs to handle the transient errors gracefully and configure validationTimeout so dead connections are detected before being handed to application code.

Multiple DataSources with Missing @Primary

Defining two DataSource beans without marking one @Primary throws NoUniqueBeanDefinitionException at startup. This is a deployment-time failure, not a runtime one, which is fortunate. The fix is marking one bean @Primary and using @Qualifier everywhere you specifically need the other DataSource. Document which DataSource is primary since it affects every unguarded injection.

Pool Size Exceeding Database max_connections

Each DataSource instance contributes connections to the total database connection count. If your HikariCP pool size times the number of application instances exceeds the database’s max_connections, some connections are rejected. Know your database’s connection limit and divide it carefully among all applications and administrative sessions.

Connection Leak from Unclosed ResultSets and Statements

Every database resource — Connection, Statement, ResultSet — must be closed. A single leak in a code path that runs frequently (a cached endpoint, a scheduled job) gradually consumes connections until the pool is exhausted. Use try-with-resources for all manual resource handling, or prefer JdbcTemplate which handles cleanup automatically.

Common Pitfalls / Anti-Patterns

Forgetting @Primary on one of multiple DataSources. Spring throws NoUniqueBeanDefinitionException at startup because it cannot determine which DataSource to inject by default.

Leaving spring.datasource.driver-class-name unset when the URL does not match a known pattern. Some JDBC drivers do not encode their class name in the URL in an easily recognizable way, particularly older Oracle drivers.

Setting pool size based on gut feel rather than load testing. Use connection pool metrics and database-level max_connections to guide configuration. A pool size of 50 might work for one workload and cause deadlock in another.

Not configuring connectionTimeout appropriately for your environment. In a containerized environment where the database might restart, a 30-second timeout means 30 seconds of hung requests during a database failover.

Leaking connections by failing to close ResultSet, Statement, or Connection objects. Use try-with-resources or Spring’s JdbcTemplate to ensure connections are returned to the pool. A single leaked connection can exhaust a small pool under load.

Ignoring the idleTimeout setting. Connections that remain idle for too long may be terminated by a firewall or load balancer, or the database may close them. HikariCP’s idleTimeout ensures idle connections are validated and recycled before they go stale.

Transaction Isolation Levels and DataSource Behavior

Transaction isolation levels directly affect how your DataSource connections behave under concurrency and have implications for locking, blocking, and read consistency.

Available Isolation Levels

Isolation Level	Dirty Reads	Non-Repeatable Reads	Phantom Reads
READ_UNCOMMITTED	Possible	Possible	Possible
READ_COMMITTED	Prevented	Possible	Possible
REPEATABLE_READ	Prevented	Prevented	Possible
SERIALIZABLE	Prevented	Prevented	Prevented

Most relational databases default to READ_COMMITTED. PostgreSQL uses MVCC to implement it efficiently, while MySQL’s InnoDB defaults to REPEATABLE_READ for historical compatibility.

Configuring Isolation Level

Set the default isolation level for a specific DataSource:

spring.datasource.hikari.transaction-isolation=TRANSACTION_READ_COMMITTED

For multi-DataSource setups, configure each independently:

@Bean
@ConfigurationProperties("app.datasource.primary")
public DataSourceProperties primaryDataSourceProperties() {
    DataSourceProperties props = new DataSourceProperties();
    props.setIsolation("TRANSACTION_READ_COMMITTED");
    return props;
}

Isolation Level Impact on Connection Pool Behavior

Higher isolation levels hold locks longer. SERIALIZABLE can cause increased lock contention and blocking in write-heavy workloads. Under READ_COMMITTED, long-running transactions holding shared locks can block incoming connection requests indirectly through lock manager pressure, even though the pool itself is not exhausted.

Monitor lock wait times in your database to detect isolation-level-induced contention:

-- PostgreSQL: find sessions waiting on locks
SELECT pg_blocking_pids(pid) AS blocked_by, pid, query
FROM pg_stat_activity
WHERE state != 'idle'
AND cardinality(pg_blocking_pids(pid)) > 0;

Read-Replica Consistency

Isolation levels govern read consistency within a transaction. When routing reads to replicas (via AbstractRoutingDataSource), be aware that replicas may lag the primary. A transaction running at READ_COMMITTED on a replica may see stale data that was already committed on the primary. For strong consistency guarantees with replicas, you may need to route reads to the primary or accept eventual consistency.

Database Migration Integration with DataSource

Schema migrations run against the same DataSource your application uses, which means migration tools hold connections during DDL operations. This has implications for pool sizing and migration strategy.

Flyway Integration

Flyway integrates with Spring Boot’s DataSource through spring.flyway.* properties:

spring.flyway.enabled=true
spring.flyway.baseline-on-migrate=true
spring.flyway.locations=classpath:db/migration
spring.flyway.url=jdbc:postgresql://localhost:5432/myapp
spring.flyway.user=flyway_user
spring.flyway.password=${FLYWAY_PASSWORD}

Flyway acquires a connection for the duration of each migration. Long-running DDL operations like ALTER TABLE holding a connection can contribute to pool pressure if your pool is undersized and multiple migrations run sequentially.

Liquibase Integration

Liquibase works similarly with spring.liquibase.* properties:

spring.liquibase.enabled=true
spring.liquibase.change-log=classpath:db/changelog/db-changelog.xml
spring.liquibase.url=jdbc:postgresql://localhost:5432/myapp
spring.liquibase.user=liquibase_user
spring.liquibase.password=${LIQUIBASE_PASSWORD}

Migration User Best Practices

Create a separate database user for migrations with elevated privileges limited to DDL operations:

CREATE USER migration_user WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE myapp TO migration_user;
GRANT USAGE ON SCHEMA public TO migration_user;
GRANT CREATE ON SCHEMA public TO migration_user;
-- Allow migration user to alter only the schemas it needs
GRANT ALTER, REFERENCES, TRIGGER ON ALL TABLES IN SCHEMA public TO migration_user;

This principle of least privilege limits the blast radius if the migration user’s credentials are compromised.

Migration Lock Timeout

Both Flyway and Liquibase use database-level locks to prevent concurrent migrations. If your migration user cannot acquire the lock within the timeout, the migration fails:

# Flyway
spring.flyway.lock-timeout=300  # seconds

# Liquibase
spring.liquibase.lock-define=30  # seconds

If migrations fail with lock timeouts on a busy database, investigate long-running transactions that hold locks across migration boundaries or increase the timeout for large schema changes.

XA Transactions and Distributed DataSources

When your application coordinates updates across multiple databases within a single transaction, you need XA (eXtended Architecture) transaction support. Spring Boot integrates with JTA (Java Transaction API) for this purpose.

When XA Is Required

XA transactions are necessary when:

• A single business operation spans multiple databases (e.g., updating an order in one DB and inventory in another atomically)
• You are integrating with external message brokers that support XA (like IBM MQ or TIBCO EMS)
• You need exactly-once delivery semantics across heterogeneous resources

Atomikos Configuration

Spring Boot supports Atomikos as the XA transaction manager:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jta-atomikos</artifactId>
</dependency>

spring.jta.atomikos.datasource.unique-resource-name=ds1
spring.jta.atomikos.datasource.xa-properties.URL=jdbc:postgresql://localhost:5432/primarydb
spring.jta.atomikos.datasource.xa-properties.user=dbuser
spring.jta.atomikos.datasource.xa-properties.password=${DB_PASSWORD}

spring.jta.atomikos.datasource.secondary.unique-resource-name=ds2
spring.jta.atomikos.datasource.secondary.xa-properties.URL=jdbc:postgresql://localhost:5432/secondarydb
spring.jta.atomikos.datasource.secondary.xa-properties.user=dbuser2
spring.jta.atomikos.datasource.secondary.xa-properties.password=${DB_PASSWORD2}

Performance Considerations

XA transactions carry overhead from two-phase commit coordination. Each participating resource must confirm prepare and commit, adding network round trips and blocking time. The performance penalty is typically 2-5x compared to local transactions for write-heavy workloads.

Evaluate whether you actually need true ACID transactions across databases or whether eventual consistency with saga patterns is sufficient. Many distributed systems opt for saga patterns with compensating transactions because XA’s blocking nature can cause cascade failures when one participant becomes unavailable.

Quick Recap Checklist

• Spring Boot auto-configures HikariCP when spring-boot-starter-data-jpa or spring-boot-starter-jdbc is present
• Set credentials via environment variables in production, not plain text in config files
• Use @Primary and @Qualifier to disambiguate multiple DataSource beans
• Enable register-mbeans and Micrometer integration for pool metrics
• Configure connectionTimeout to match your failover and resilience requirements
• Use try-with-resources or JdbcTemplate to prevent connection leaks
• Enable SSL/TLS for any database connection that crosses a network boundary
• Size your pool based on load testing, not intuition
• Add custom health indicators for multi-DataSource setups
• Validate idleTimeout settings for your deployment environment

Interview Questions

Further Reading

These resources go deeper on the topics covered and adjacent areas worth understanding as your DataSource usage scales.

HikariCP Internals

Understanding how HikariCP manages its pool internally helps you tune it correctly. The pool uses a ConcurrentBag for lock-free connection management, which reduces contention under high concurrency. Connections are borrowed from the bag and must be returned explicitly or via try-with-resources. HikariCP also performs idle connection eviction based on idleTimeout and validates connections before handing them out using validationTimeout. The official HikariCP documentation covers the mechanics of connection states and the lifecycle of connections in the bag.

AbstractRoutingDataSource for Read/Write Splitting

Spring’s AbstractRoutingDataSource lets you route queries to different DataSources based on runtime context. The most common pattern is primary-replica routing: writes go to the primary database and reads are routed to replicas. Implement determineDataSourceKey() to inspect the current transaction context and return the appropriate DataSource key. Pair this with @Transactional(readOnly = true) to signal replica intent. This pattern is foundational for read scaling in relational databases.

Connection Pool Sizing Methodology

Pool size is not arbitrary. The classic formula is: pool_size = (core_count * 2) + effective_spindle_count. For SSDs with no disk contention, start with core_count * 2. For traditional disks, add head seek time overhead. In containerized environments, factor in the database’s max_connections divided by the number of application instances. Use the Observability Checklist metrics to validate your settings under real load. Use load testing to confirm the pool behaves correctly at the upper bound of expected concurrency.

Conclusion

For most Spring Boot projects, spring.datasource.url plus credentials is all you need. HikariCP spins up automatically and handles pooling with sensible defaults. You only need to think about DataSource configuration when you have multiple databases, a pool that needs tuning, or a connection requirement auto-configuration cannot guess.

For multiple DataSources, the pattern is consistent: one @Primary bean, separate DataSourceProperties per database, and @Qualifier wherever you need the non-primary. The wiring is verbose but predictable.