Spring Boot Datasource Configuration Completion and Validation

Review datasource basics, connection pool settings, profile overrides, and startup validation.

Written and maintained by ErickPang ยท Updated

Common Spring Boot datasource keys, YAML/Properties examples, connection pool settings, and startup verification methods.

Basic datasource configuration

Datasource settings are among the most common Spring Boot configuration areas and can directly affect startup. For an external database, specify at least the url and provide username and password when its authentication requires them. Spring Boot can usually infer the JDBC driver from the URL; set driver-class-name only when inference fails or a specific implementation is required.

Completion tools help enter common keys under spring.datasource, but they cannot determine whether the database is reachable. After writing configuration, verify it through startup logs, connection pool initialization, or a simple query.

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/app
    username: app
    password: secret
    driver-class-name: org.postgresql.Driver

Connection pool settings

Most Spring Boot projects use HikariCP by default. Do not blindly copy production pool values into local development. Local environments can use smaller maximum-pool-size values, while production should consider database capacity, service replicas, and peak traffic.

Poor pool settings may cause slow startup, exhausted connections, or excessive database pressure. Review pool settings together with concurrency and deployment replica count.

spring:
  datasource:
    hikari:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout: 30000

Validation method

After startup, confirm there are no bean creation failures, missing driver classes, or authentication errors. Then run a minimal query to verify the connection. For multi-profile projects, confirm the active profile points to the expected database URL.

Do not put production database URLs in local default configuration. Use environment variables or profile-specific files and check for sensitive values before committing.

  • Confirm the database driver dependency is present
  • Confirm URL, username, password, and database reachability
  • Confirm active profile does not override datasource
  • Confirm connection pool settings fit the environment

Verify dependencies before tuning the pool

A valid configuration still fails when the JDBC driver is absent from the runtime classpath. spring-boot-starter-jdbc and spring-boot-starter-data-jpa normally bring in HikariCP, but PostgreSQL, MySQL, and other database drivers must still be declared separately with versions compatible with the Java and database lines in use.

Do not raise maximum-pool-size to hide connection leaks or slow queries. Multiply the per-instance limit by the number of service replicas and leave database capacity for migrations, administrative tools, and other services. connection-timeout only controls how long a request waits for a pooled connection; it cannot fix an unreachable host or invalid credentials.

  • No suitable driver: check the JDBC driver dependency and URL prefix
  • Connection refused: check host, port, network path, and database listener
  • Authentication failed: check credential sources and the active profile
  • Connection is not available: inspect pool limits, leaks, and slow queries

Keep credentials in environment variables

Shared configuration can keep variable names and non-sensitive defaults, but it should not contain a real production password. The deployment environment injects DB_URL, DB_USERNAME, and DB_PASSWORD; local development can use an uncommitted environment file or an IDE Run Configuration.

Before committing, search application-*.yml, application-*.properties, launch scripts, and CI configuration. Removing a secret from Git does not make it safe again; rotate exposed credentials at the database as well.

spring:
  datasource:
    url: ${DB_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      maximum-pool-size: ${DB_POOL_SIZE:10}

Primary reference and related guides

Spring Boot's SQL Databases reference documents spring.datasource.* settings, driver inference, and connection-pool selection. HikariCP parameter units and behavior can vary with the managed dependency version, so check the HikariCP version used by the Spring Boot line before tuning.

Related guides

Independently maintained by ErickPang. Not affiliated with Spring, JetBrains, or Broadcom.