The No-Nonsense Guide to Spring Profiles (Plus a Simple Way to Merge Them)

If you’ve ever accidentally connected your local laptop to the production database, you know why Spring Profiles exist.

It’s a rite of passage for Java developers. You’re coding away, everything is working perfectly on localhost, and then you deploy. Suddenly, your application is trying to connect to a database that doesn’t exist, using credentials that are wrong, and sending emails to real customers.

The problem isn’t your code’s logic; it’s your application’s environment.

An application running on your dev machine needs different settings than the same application running on a QA server or in production. Hardcoding these settings is a recipe for disaster.

This is where Spring Boot Profiles come to the rescue. They are the standard, built-in way to tell your application: “Hey, look around. If you’re on a developer’s laptop, use these settings. If you’re on the live server, use those settings.”

In this guide, we’ll break down exactly how Spring Profiles work, how to set them up without getting a headache, and—most importantly—how to handle the messy reality of managing multiple configuration files at once. We’ll even look at a handy spring profile merge tool to make your life easier.

What Are Spring Profiles, Really?

Think of a profile as a “label” for a specific runtime environment.

• dev: For your local development work.
• qa or test: For the testing team’s server.
• prod: For the live, customer-facing environment.

By default, Spring Boot looks for a file named application.properties (or application.yml). This is your “base” configuration. It holds settings that are true everywhere, like your application’s name or maybe some default timeout values.

When you activate a profile, Spring Boot gets smarter. If you activate the dev profile, it will look for application.properties AND application-dev.properties.

Here’s the magic part: The profile-specific file wins.

If application.properties says the database URL is localhost, but application-dev.properties says it’s dev-db-server, Spring will use dev-db-server when the dev profile is active.

This simple mechanism allows you to keep one main codebase but have it behave differently depending on where it’s running.

How to Set Up Your First Profile

Let’s say we have a standard Spring Boot project. Our goal is to have different database settings for development and production.

Step 1: Create Your Base Config

In your src/main/resources folder, you have your standard application.properties file. Let’s put common settings here.

# application.properties (The base config)
spring.application.name=MyAwesomeApp
server.port=8080
logging.level.root=INFO

Step 2: Create Your “Dev” Config

Now, create a new file right next to it called application-dev.properties. The naming convention application-{profile_name}.properties is vital.

# application-dev.properties (Only for local dev work)
spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.username=sa
spring.datasource.password=
logging.level.org.springframework.web=DEBUG

We’re using an in-memory H2 database here because it’s fast and doesn’t require setup. Perfect for development.

Step 3: Create Your “Prod” Config

Create another file called application-prod.properties.

# application-prod.properties (The serious stuff)
spring.datasource.url=jdbc:mysql://prod-db-server:3306/myapp
spring.datasource.username=prod_user
# Ideally, don't put real passwords in plain text files! Use environment variables.
spring.datasource.password=${PROD_DB_PASSWORD}
logging.level.root=WARN

Step 4: Activate a Profile

Now you need to tell Spring which one to use. You have a few ways to do this.

Method A: In your IDE (IntelliJ, Eclipse) When running your application locally, you can add a “VM option” in your run configuration: -Dspring.profiles.active=dev

Method B: In application.properties itself You can set a default profile in your main file. This is useful so other developers on your team don’t have to configure anything to get started. spring.profiles.active=dev

Method C: Command line argument (For deployment) This is the most common way for servers. When you run your JAR file, you pass the argument: java -jar myapp.jar --spring.profiles.active=prod

When you run with prod, Spring loads application.properties first, then loads application-prod.properties right on top of it, overriding any conflicting values.

The Messy Reality: Properties vs. YAML

So far, I’ve used .properties files because they are simple. But let’s be honest, in the real world, most Spring Boot projects use YAML (.yml).

YAML is cleaner to read, especially when you have deeply nested structures like this:

spring:
  datasource:
    url: jdbc:mysql://localhost/db
    username: user
    password: pass
  jpa:
    hibernate:
      ddl-auto: update

It just looks better than the equivalent properties file.

But here is where things get tricky. You will often find yourself on a project that uses a mix of both. Or maybe you are migrating an older project from properties to YAML.

You end up with an application.properties file and you want to convert it to application-dev.yml to keep things consistent. Doing this manually is tedious and error-prone. One missed indent in YAML breaks everything.

The Challenge of Merging Profiles

Let’s look at a common scenario that trips people up. You want to see exactly what the final configuration looks like for a specific profile.

Imagine you have a giant base application.yml and a complex application-prod.yml. Your boss asks, “Hey, what’s the final set of properties that will go live?”

You can’t just send them the two files. They need the combined, final result.

To merge spring profiles manually, you have to open both files side-by-side. You copy the base file, then go through the profile file line-by-line, updating the values in your copy. It’s slow, boring work.

And what if you have a format mismatch?

You have a base application.properties but your new team standard is YAML. You need to take the base properties, convert them to YAML, take your application-dev.properties, convert that to YAML, and then merge them to see the final state.

A Simple Spring Profile Merge Tool

This is such a common problem that we built a tool to handle it.

Instead of manually converting and copy-pasting to see your final configuration, you can use an online converter to do the heavy lifting.

Let’s say you have your base properties and you want to merge it with a dev profile, and get the final result in YAML.

1. Take your application.properties content.
2. Take your application-dev.properties content.
3. Paste them both into a tool that can handle the conversion.

Our online profile merge tool at Toolshref.com is designed exactly for this. It’s primarily a Properties-to-YAML converter, but because of how it works, it acts as a perfect merge tool.

You simply paste your base properties first, and then paste your profile-specific properties right below it in the same input box.

Because Spring Boot works by “last one wins,” pasting them in this order mimics exactly what Spring Boot does at startup. The tool then converts the whole combined mess into clean, perfectly formatted YAML.

Example:

You paste this into the input:

# --- From application.properties ---
server.port=8080
app.name=BaseApp

# --- From application-dev.properties ---
server.port=9090
app.debug=true

The tool will instantly give you the merged YAML:

server:
  port: 9090
app:
  name: BaseApp
  debug: true

See? The server.port correctly became 9090. You now have a single, clean YAML block that represents your entire effective development configuration. You can copy this, save it as a reference, or send it to a colleague.

Summary

Spring Profiles are an essential part of any serious Spring Boot application. They allow you to write your code once and run it anywhere.

• Use application.properties for base settings.
• Use application-{profile}.properties for environment-specific overrides.
• Activate profiles using -Dspring.profiles.active=dev or command line arguments.

When you need to visualize the final result or migrate between formats, don’t waste time doing it by hand. Use a spring profile merge tool to combine your files and convert them to YAML in seconds. It’s one of those small utilities that saves a surprising amount of frustration.

Frequently Asked Questions

How do I merge Spring Boot profiles effectively? Spring Boot merges profiles automatically at runtime using a strategy where “specific overrides general.” This means your application-dev.properties will override values in your standard application.properties. However, if you need to physically combine these files—for example, to debug a configuration issue or migrate to a new format—you can use our Spring Profile Merge Tool. Simply paste your base config followed by your profile config into the converter to get a single, merged result.

Which configuration file takes priority? Spring Boot uses a “last-one-wins” logic. Profile-specific files (like application-prod.properties) always override the default application.properties. Furthermore, if you are using both YAML and Properties files in the same project (not recommended!), the .properties files generally take precedence over .yml files.

How do I activate a specific Spring profile? You can activate a profile in three main ways depending on your environment:

1. Local Development: Add -Dspring.profiles.active=dev to your IDE’s VM options.
2. Deployment (JAR): Use the command line argument java -jar app.jar --spring.profiles.active=prod.
3. Default: Set spring.profiles.active=dev directly inside your application.properties file to make it the default for everyone.

Can I convert Spring Properties to YAML automatically? Yes. While you can do it manually, YAML requires strict indentation which is easy to mess up. It is much faster and safer to use an automated Properties to YAML converter to transform your flat properties list into a valid, nested YAML structure instantly.