Spring Boot app.properties - Dev DB Wiped Profile

In professional software engineering, hardcoding is a cardinal sin. Embedding your database password or server port directly into Java source code creates a fragile system that requires a full recompile just to change a timeout value. This is where externalized configuration becomes critical.

Spring Boot's application.properties serves as the control center for your entire application. It separates the logic of your code from the environment it runs in. Whether deploying to a local Docker container or a Kubernetes cluster, the code stays the same — only the properties change.

Misconfiguring properties causes production failures that are silent and genuinely hard to diagnose. A misplaced space around the equals sign silently ignores your config change. A missing environment variable crashes the app at 2 AM when the fallback was never defined. Using tabs instead of spaces in a YAML file misparses your entire datasource configuration without throwing a startup error. These are not theoretical edge cases — they are the class of incidents that generate post-mortems.

This guide covers property injection patterns, environment profiles, the fail-fast validation strategy that catches misconfiguration at startup rather than at runtime, and the configuration management approaches used in production systems that handle secrets without committing them to version control.

What application.properties Actually Is and Where It Lives

Spring Boot follows a strict priority order for loading configuration. By default, it looks in src/main/resources/application.properties. When your build tool packages your app, this file is moved to the root of the classpath inside your JAR. Spring Boot finds it by convention — you do not register it anywhere.

The syntax is a flat key=value format. Spring uses these keys to auto-configure beans. Defining spring.datasource.url does not just store a string — it triggers Spring Boot's auto-configuration to create a DataSource bean, a HikariCP connection pool, and wire the entire JPA stack. You provide the parameters; Spring Boot writes the plumbing.

The priority chain matters more than most developers realize. A value in application.properties can be overridden by application-prod.properties, which can be overridden by an OS environment variable, which can be overridden by a JVM argument, which can be overridden by a command-line argument. Every environment variable your Kubernetes pod injects wins over anything in any file. Understanding this chain is what lets you debug configuration mismatches in under five minutes instead of four hours.

One critical detail the official docs bury: as of Spring Boot 2.4, the way additional config files are imported changed. The old spring.config.additional-location property still works, but the new spring.config.import is the forward-compatible approach and is required for Spring Cloud Config Server and Vault integration.

# ── io.thecodeforge: Standard Server Config ───────────────────────
server.port=8081
server.servlet.context-path=/api/v1

# ── Application Identity ──────────────────────────────────────────
spring.application.name=forge-bookstore-service

# ── Database Connection (PostgreSQL) ──────────────────────────────
# ${DB_PASSWORD} resolves from OS environment variable.
# The :default_dev_pass fallback only applies locally — never in prod.
# In prod, DB_PASSWORD must be set explicitly or startup fails at datasource creation.
spring.datasource.url=jdbc:postgresql://localhost:5432/forge_db
spring.datasource.username=forge_admin
spring.datasource.password=${DB_PASSWORD:default_dev_pass}
spring.datasource.driver-class-name=org.postgresql.Driver

# ── Connection Pool (HikariCP) ────────────────────────────────────
# These defaults are tuned for a small service — adjust for your load profile.
# Too small: connection starvation under load.
# Too large: DB server thread exhaustion.
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

# ── JPA / Hibernate ───────────────────────────────────────────────
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect
# validate: checks schema matches entities at startup — use in prod
# update:  modifies schema automatically — never use in prod
# none:    no schema management — use in prod with external migrations (Flyway/Liquibase)
spring.jpa.hibernate.ddl-auto=validate

# ── Logging Configuration ─────────────────────────────────────────
logging.level.root=INFO
logging.level.io.thecodeforge=DEBUG

# ── Importing Additional Config (Spring Boot 2.4+) ────────────────
# Use spring.config.import to pull in extra config files or external sources.
# For Vault: spring.config.import=vault://
# For Config Server: spring.config.import=configserver:
# For local extra file: spring.config.import=optional:classpath:extra-config.properties
# 'optional:' prefix means do not fail if the file does not exist.
# spring.config.import=optional:classpath:extra-config.properties

Injecting Properties Into Java Classes: @Value vs @ConfigurationProperties

Spring provides two mechanisms for getting property values into your Java code. @Value is the quick option for a single value. @ConfigurationProperties is the production option for any group of related settings.

@Value("${key:default}") injects a single property directly into a field. The colon-default syntax is not optional in production — without it, a missing property crashes the application at startup with IllegalArgumentException: Could not resolve placeholder. That crash at 2 AM during deployment is avoidable.

@ConfigurationProperties binds an entire property prefix to a typed Java class. It supports Relaxed Binding, which means forge.bookstore.page-size in the properties file maps to private int pageSize in your Java class automatically — no exact key matching required. It also supports JSR-303 validation via @Validated, which gives you explicit startup failures with clear messages when required properties are missing or out of range.

The IDE tooling difference is real and worth mentioning: if you add the spring-boot-configuration-processor dependency to your build, IntelliJ and VS Code generate autocomplete suggestions, type hints, and deprecation warnings for every field in your @ConfigurationProperties class. Without the processor, you are typing property keys blind. With it, you get the same IDE experience for custom properties that you get for Spring's built-in ones.

package io.thecodeforge.bookstore.config;

import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import org.springframework.validation.annotation.Validated;
import lombok.Data;

/**
 * io.thecodeforge: Type-safe configuration with validation.
 *
 * @Validated: activates JSR-303 validation at startup.
 * If any constraint fails, the app refuses to start with a clear error message.
 * This is the fail-fast pattern — catch misconfiguration at startup, not at runtime.
 *
 * Relaxed Binding examples (all resolve to the same field):
 *   forge.bookstore.page-size=50        (kebab-case in .properties)
 *   forge.bookstore.page_size=50        (snake_case)
 *   FORGE_BOOKSTORE_PAGE_SIZE=50        (env var / UPPER_SNAKE_CASE)
 *   forge.bookstore.pageSize=50         (camelCase)
 */
@Data
@Component
@Validated
@ConfigurationProperties(prefix = "forge.bookstore")
public class ForgeBookstoreProperties {

    // Default values apply when the property is not defined in any config file.
    // These should be safe, conservative defaults — not production tuning values.
    @Min(value = 1, message = "forge.bookstore.page-size must be at least 1")
    private int pageSize = 10;

    @NotBlank(message = "forge.bookstore.default-currency must not be blank")
    private String defaultCurrency = "USD";

    // @Valid cascades validation into nested configuration objects.
    // Without @Valid here, the constraints inside Security are never evaluated.
    @Valid
    @NotNull(message = "forge.bookstore.security configuration block is required")
    private Security security = new Security();

    @Data
    public static class Security {

        // App refuses to start if forge.bookstore.security.api-key is missing or blank.
        // No more null API keys silently reaching production.
        @NotBlank(message = "forge.bookstore.security.api-key must be configured")
        private String apiKey;

        @Min(value = 5, message = "Session timeout must be at least 5 minutes")
        private int sessionTimeoutMinutes = 30;

        // Pattern validation — api-key must match expected format
        // Uncomment when you have a known format to enforce:
        // @Pattern(regexp = "^[A-Za-z0-9\\-]{32,64}$",
        //          message = "forge.bookstore.security.api-key must be 32-64 alphanumeric chars")
    }
}

Spring Boot Profiles — Environment-Specific Configuration Without Code Changes

Every application runs in multiple environments: your laptop, a CI runner, staging, and production. The database URLs differ. The log levels differ. The external service endpoints differ. Profiles let you express those differences in configuration files without touching the Java code or maintaining separate build artifacts.

Spring Boot loads files in this order: application.properties first as the baseline, then application-{profile}.properties as the overlay. Only keys that appear in both files are overridden — everything in the base file that is not mentioned in the profile file is inherited as-is. This means your profile files should be small and specific to what actually changes per environment.

Multiple profiles can be active simultaneously. SPRING_PROFILES_ACTIVE=prod,monitoring activates both the prod profile and a monitoring profile. Spring loads both overlay files. If the same key appears in both profile files, the last one wins in alphabetical order — which is why relying on multiple overlapping profiles for the same key is a maintenance trap.

The profile activation question is one of the most consistently asked in Spring Boot interviews: if the same property key appears in application.properties, application-prod.properties, AND an OS environment variable, what wins? The environment variable wins unconditionally. The full priority chain from highest to lowest is: command-line arguments, Java system properties (-D flags), OS environment variables, profile-specific property files, base application.properties.

# ── io.thecodeforge: Production Overrides ─────────────────────────
# This file contains ONLY what differs in production.
# Everything not listed here is inherited from application.properties.
# Keeping this file small is a feature — it makes prod differences explicit.

# Production runs on standard HTTPS port behind a load balancer
server.port=8080

# Production RDS instance — URL comes from environment variable for security
# SPRING_DATASOURCE_URL is set in the Kubernetes Secret and injected as env var
spring.datasource.url=${SPRING_DATASOURCE_URL}
spring.datasource.username=${SPRING_DATASOURCE_USERNAME}
spring.datasource.password=${SPRING_DATASOURCE_PASSWORD}

# Production connection pool — sized for actual production load
spring.datasource.hikari.maximum-pool-size=25
spring.datasource.hikari.minimum-idle=5

# Schema validation (not creation) — production schema is managed by Flyway
spring.jpa.hibernate.ddl-auto=validate

# No SQL logging in production — performance cost and log volume are not acceptable
logging.level.root=WARN
logging.level.io.thecodeforge=INFO
spring.jpa.show-sql=false

# Stricter session timeout in production
forge.bookstore.security.session-timeout-minutes=15

application.properties vs application.yml — Syntax, Trade-offs, and Failure Modes

Both formats configure the same Spring Boot beans. The properties file is a flat key=value list. The YAML file is a hierarchical structure that eliminates prefix repetition at the cost of indentation sensitivity. Neither is objectively better — each has a specific failure mode that the other does not.

The properties file failure mode: almost none. A trailing space on a key makes it unrecognizable, but the app starts and you notice the value is wrong. A missing equals sign causes a parse error with a clear line number. It is hard to silently corrupt a properties file.

The YAML failure mode: silent misconfiguration. A tab character instead of two spaces causes the YAML parser to misparse the structure. Properties end up under the wrong parent key. Spring may create a bean with a null URL. The app starts, no parse error is thrown, and every database call fails at runtime. This class of failure is significantly harder to diagnose than a startup crash.

YAML has one genuine superpower: multi-document support. Using --- as a separator, you can define multiple Spring profiles in a single application.yml file. In Spring Boot 2.4 and later, use spring.config.activate.on-profile inside the document block. This is a YAML-only feature — you cannot do it with properties files.

The practical advice: use properties files for simple, flat configuration where correctness matters more than readability. Use YAML for complex nested configuration in microservices where the visual hierarchy genuinely helps. If you choose YAML, add a CI linting step that catches tab characters before they reach any server.

# io.thecodeforge: YAML configuration reference
# Equivalent to the application.properties example above, plus multi-profile demo.

spring:
  application:
    name: forge-bookstore-service
  datasource:
    url: jdbc:postgresql://localhost:5432/forge_db
    username: forge_admin
    # Environment variable resolution works identically in YAML
    password: ${DB_PASSWORD:default_dev_pass}
    hikari:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout: 30000
  jpa:
    hibernate:
      ddl-auto: validate
    database-platform: org.hibernate.dialect.PostgreSQLDialect
    show-sql: false

server:
  port: 8081
  servlet:
    context-path: /api/v1

logging:
  level:
    root: INFO
    io.thecodeforge: DEBUG

forge:
  bookstore:
    page-size: 10
    default-currency: USD
    security:
      session-timeout-minutes: 30

# ── Multi-document YAML: profile-specific overrides in one file ────
# The --- separator starts a new YAML document.
# spring.config.activate.on-profile is the Spring Boot 2.4+ syntax.
# Older spring.profiles syntax is deprecated as of 2.4 — do not use it.
---
spring:
  config:
    activate:
      on-profile: dev
server:
  port: 9090
logging:
  level:
    root: DEBUG
    org.hibernate.SQL: TRACE

---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 8080
spring:
  datasource:
    url: ${SPRING_DATASOURCE_URL}
    hikari:
      maximum-pool-size: 25
logging:
  level:
    root: WARN

Secrets Management and External Configuration: Beyond the Properties File

For applications beyond the hobby scale, storing secrets in properties files — even with environment variable placeholders — is not sufficient. Rotating a database password means updating an environment variable on every host, restarting every instance, and hoping nothing was cached. A secret manager like HashiCorp Vault, AWS Secrets Manager, or Spring Cloud Config Server provides centralized secret storage, automatic rotation, audit logs, and fine-grained access control.

Spring Boot 2.4 introduced spring.config.import as the standardized way to pull configuration from external sources. A single line in application.properties or application.yml pulls the entire secret set from Vault or Config Server at startup. If the external source is unreachable and the import is not marked optional, the application refuses to start — which is exactly the fail-fast behavior you want rather than starting with missing secrets.

For teams not ready for Vault or Config Server, Jasypt (Java Simplified Encryption) provides a middle ground: properties files that store AES-encrypted values instead of plaintext. The encryption key is injected at runtime via environment variable. This is not equivalent security to Vault, but it prevents credentials from being readable in any file committed to version control or stored on disk in plaintext.

The environment variable approach used throughout this guide is the minimum acceptable standard for production. The approaches in this section are what teams with actual security requirements implement after the environment variable baseline is working.

# ── io.thecodeforge: External Configuration Import Examples ───────

# --- Spring Cloud Config Server ---
# Imports all properties from Config Server at startup.
# Config Server URL is typically set via SPRING_CONFIG_URI env var.
# If Config Server is unreachable, startup fails immediately (fail-fast).
spring.config.import=configserver:

# --- HashiCorp Vault ---
# Imports secrets from Vault path secret/forge-bookstore.
# Requires spring-cloud-starter-vault-config dependency.
# spring.config.import=vault://
# spring.cloud.vault.uri=http://vault.internal:8200
# spring.cloud.vault.token=${VAULT_TOKEN}
# spring.cloud.vault.kv.enabled=true
# spring.cloud.vault.kv.default-context=forge-bookstore

# --- Optional file import ---
# Import an additional file if it exists — do not fail if absent.
# Useful for local developer overrides that are .gitignored.
# spring.config.import=optional:file:./local-override.properties

# --- AWS Parameter Store (Spring Cloud AWS) ---
# spring.config.import=aws-parameterstore:
# spring.cloud.aws.parameterstore.enabled=true

# ── Jasypt Encryption (middle-ground secret management) ───────────
# Encrypted values are stored as ENC(encryptedString).
# The encryption key is injected at runtime — never stored in the file.
# jasypt.encryptor.password=${JASYPT_ENCRYPTOR_PASSWORD}
#
# Example encrypted datasource password:
# spring.datasource.password=ENC(Gb3V+Kj7Mc2VzXP4q8Rn5A==)
# Jasypt decrypts this at startup using the key from JASYPT_ENCRYPTOR_PASSWORD.
# Without the key, the encrypted string is meaningless — safe to commit.

Externalize the Configuration of SpringApplication — Because Production Is Not a Sandbox

Spring Boot gives you a SpringApplication object. Most devs treat it like a black box. They don't. That object is your last line of defense before your app hits production. Configure it externally.

The spring.config.name and spring.config.location environment variables let you swap entire configuration directories without touching a single line of code. No rebuild. No redeploy. Just a JVM flag.

Why should you care? Because I've seen teams hardcode file paths in application.properties, then panic when their Kubernetes pod can't find the config volume. Or worse, they embed secrets in the JAR. Externalize the SpringApplication configuration and sleep better at night.

Here's the pattern: set SPRING_CONFIG_NAME=myapp and SPRING_CONFIG_LOCATION=file:/etc/config/ on the host. Spring Boot loads /etc/config/myapp.properties. If the file is missing, it fails fast. You want that. Fail fast, not fail silently at 3 AM.

// io.thecodeforge — java tutorial

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.core.env.Environment;

@SpringBootApplication
public class PaymentProcessorApplication {

    public static void main(String[] args) {
        // Environment variable overrides built-in defaults
        // Set SPRING_CONFIG_NAME=payment or use --spring.config.name=payment
        SpringApplication app = new SpringApplication(PaymentProcessorApplication.class);
        
        // External path: /opt/payment/config/
        // Spring Boot reads /opt/payment/config/payment.properties
        app.setDefaultProperties(java.util.Map.of(
            "spring.config.name", System.getenv().getOrDefault("SPRING_CONFIG_NAME", "application"),
            "spring.config.location", System.getenv().getOrDefault("SPRING_CONFIG_LOCATION", "classpath:/")
        ));
        
        Environment env = app.run(args).getEnvironment();
        System.out.println("Active config file: " + env.getProperty("spring.config.name"));
    }
}

Automatically Expand Properties at Build Time — Stop Duplicating Values Across pom.xml and application.properties

You have a Maven version in pom.xml and the same version in application.properties. You update one, forget the other, and spend an hour debugging a version mismatch. This is stupid. Spring Boot Maven and Gradle plugins let you expand build properties directly into your configuration files at compile time. No duplication.

With Maven, use @project.version@, @project.build.sourceEncoding@, or any Maven property. Spring Boot's spring-boot-starter-parent enables resource filtering by default. Add the placeholder in your properties file, and Maven replaces it during the process-resources phase.

If you don't use the parent POM, you must manually enable filtering in your pom.xml. Yes, it's boilerplate. Yes, it's worth it. The alternative is chasing configuration drift across three environments.

For Gradle, the spring-boot-gradle-plugin does the same with $ placeholders. Same rule: keep your build config as the single source of truth.

// io.thecodeforge — java tutorial

// application.properties — before build
app.version=@project.version@
app.build.timestamp=@timestamp@
app.java.version=@java.version@

// pom.xml — without spring-boot-starter-parent, you need this:
<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <filtering>true</filtering>
        </resource>
    </resources>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-resources-plugin</artifactId>
            <version>3.3.1</version>
        </plugin>
    </plugins>
</build>

// After build — application.properties contains:
app.version=2.5.1
app.build.timestamp=2024-09-28T10:30:00Z
app.java.version=17

Discover Built-in Options for External Properties — Because Guessing Isn't a Strategy

Spring Boot doesn't just read application.properties from your classpath and call it a day. It has a defined, overridable search path that spans multiple locations — and you need to know it before production eats your config. The default order starts at the classpath, then moves to the current directory's /config subdirectory, then the current directory root, then /config directly under the classpath root. Each subsequent location overrides the previous one. You can override this entirely with spring.config.location or append extra paths with spring.config.additional-location. Why does this matter? Because ops teams routinely drop overrides in /config/ outside the JAR. If you don't know the search order, you'll debug phantom values at 2 AM. The real power is combining this with spring.config.import — you can pull properties from HTTP URLs, Vault, or even Git. Spring Cloud Config? That's just a plugin. The core boot engine already supports external property sources out of the box. Stop hardcoding paths you'll regret later.

// io.thecodeforge — java tutorial
// Show how Spring Boot resolves config from multiple locations

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.core.env.Environment;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;

@SpringBootApplication
public class ExternalConfigDemo implements CommandLineRunner {

    @Autowired
    private Environment env;

    public static void main(String[] args) {
        // Override order: classpath, file:./config/, file:./
        SpringApplication app = new SpringApplication(ExternalConfigDemo.class);
        app.setDefaultProperties(java.util.Map.of("spring.config.name", "custom"));
        app.run();
    }

    @Override
    public void run(String... args) {
        String dbUrl = env.getProperty("database.url");
        System.out.println("Resolved database URL: " + dbUrl);
    }
}

Properties in Parent-Child Contexts — The Override You Didn't Know Was There

When you run a Spring Boot app that loads a parent context (like a traditional WAR in a servlet container, or a context hierarchy via Spring Cloud), properties don't flow the way you expect. The parent context's Environment is NOT visible to child beans by default. Child contexts have their own property sources. If you define a property in the parent's application.properties, don't assume your REST controller in the child sees it. This bites people migrating from monolithic Spring MVC apps to Boot with embedded containers. The fix: use spring.config.use-legacy-processing=false in the child? No — that's a boot 2.4+ change for file loading, but doesn't fix context isolation. The real solution is to pass properties manually or use a shared PropertySourcesPlaceholderConfigurer that bridges contexts. Or better, avoid parent-child entirely: Boot's convention is single-context. If you must nest, inject the parent's Environment into the child via a factory bean. Otherwise, you'll waste hours wondering why @Value("${my.property}") returns null in a child context while it works in the parent.

// io.thecodeforge — java tutorial
// Bridge parent properties to child context

import org.springframework.beans.factory.config.PropertyPlaceholderConfigurer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.io.ClassPathResource;

@Configuration
public class ParentChildConfigFix {

    @Bean
    public static PropertyPlaceholderConfigurer childProps(Environment parentEnv) {
        PropertyPlaceholderConfigurer ppc = new PropertyPlaceholderConfigurer();
        ppc.setLocation(new ClassPathResource("application.properties"));
        // Fallback to parent env for unresolvable properties
        ppc.setProperties(parentEnv.getSystemProperties());
        ppc.setIgnoreUnresolvablePlaceholders(true);
        return ppc;
    }
}