Application.yml: The Complete Playbook for Spring Boot Configuration

Confidence in your configuration is confidence in your application. application.yml is the single most important file in any Spring Boot project — and one of the most misunderstood. This playbook gives you everything you need to configure it correctly the first time, avoid common pitfalls, and scale your setup as your project grows.

Key Takeaways

• Start with a clean structure: Organise properties by concern (server, datasource, logging, custom) to keep the file readable and maintainable.
• Use Spring profiles for environment separation: Never hard-code environment-specific values; use application-dev.yml, application-prod.yml, etc.
• Prefer application.yml over application.properties: YAML offers nested structure, better readability, and reduced redundancy.
• Externalise sensitive data: Use ${ENV_VAR} placeholders or a secrets manager — never commit passwords to version control.
• Leverage Spring Boot's built-in property resolution order: Command-line args > environment variables > application.yml > defaults.
• Validate configuration at startup: Use @ConfigurationProperties with JSR-303 Bean Validation to catch errors early.
• Keep defaults explicit: Define sensible defaults in application.yml so the app is runnable out of the box.

What Is application.yml?

application.yml is a YAML-formatted configuration file that Spring Boot reads automatically from the classpath (or filesystem) at startup. It replaces the older flat application.properties format with a hierarchical structure that mirrors how developers actually think about configuration.

Spring Boot looks for this file in four locations, in priority order:

1. /config/ subdirectory of the current directory
2. Current directory
3. classpath:/config/
4. classpath:/

Understanding this lookup chain is critical — it explains why a local file can override a committed default, which is both a powerful feature and a common source of confusion during deployments.

Core Structure and Conventions

A well-structured application.yml follows these conventions:

1. Server Configuration

server:
  port: 8080
  servlet:
    context-path: /api
  error:
    include-stacktrace: never
    include-message: always

2. Database and DataSource

spring:
  datasource:
    url: jdbc:postgresql://${DB_HOST:localhost}:${DB_PORT:5432}/${DB_NAME:myapp}
    username: ${DB_USER}
    password: ${DB_PASSWORD}
    driver-class-name: org.postgresql.Driver
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

3. JPA / Hibernate Settings

  jpa:
    database-platform: org.hibernate.dialect.PostgreSQLDialect
    hibernate:
      ddl-auto: validate
    show-sql: false
    properties:
      hibernate:
        format_sql: true
        use_sql_comments: true

4. Logging Configuration

logging:
  level:
    root: INFO
    com.myapp: DEBUG
    org.springframework.web: INFO
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/application.log
    size: 10MB
    max-history: 30

5. Custom Application Properties

app:
  name: MyService
  version: @project.version@
  features:
    enable-cache: true
    cache-ttl: 3600
    max-retry-attempts: 3
  security:
    jwt-secret: ${JWT_SECRET}
    token-expiry-hours: 24

Profile-Specific Configuration

Profiles are the cornerstone of production-ready configuration. They let you maintain a single codebase across development, testing, staging, and production environments without duplication.

Setting Up Profiles

• Create application-dev.yml for local development
• Create application-test.yml for integration tests
• Create application-staging.yml for pre-production
• Create application-prod.yml for production

Activating Profiles

# Activate via command line
java -jar myapp.jar --spring.profiles.active=prod

# Activate via environment variable
export SPRING_PROFILES_ACTIVE=prod

# Activate via application.yml default
spring:
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}

Example Profile: Development

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/myapp_dev
    username: dev_user
    password: dev_pass
  jpa:
    hibernate:
      ddl-auto: create-drop
    show-sql: true
  sql:
    init:
      mode: always
      schema-locations: classpath:schema.sql
      data-locations: classpath:data.sql
logging:
  level:
    com.myapp: DEBUG
    org.springframework: DEBUG

Example Profile: Production

spring:
  datasource:
    url: jdbc:postgresql://${DB_HOST}:${DB_PORT:5432}/${DB_NAME}
    username: ${DB_USER}
    password: ${DB_PASSWORD}
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
logging:
  level:
    root: WARN
    com.myapp: INFO

application.yml vs application.properties: Comparison

Property Resolution and Override Mechanisms

Spring Boot resolves property values from multiple sources in a defined priority order. Knowing this order prevents surprising behaviour when values don't update as expected.