Spring Boot Profiles

1. What is a Spring Profile?

A profile is a named environment or configuration mode.

For example:

• dev → local database
• qa → QA database
• production → production database

The same Spring Boot application can activate different profiles depending on where it is running.

2. Why Do We Need Profiles?

Imagine this application:

Environment	Database	Logging	External API
Development	localhost	DEBUG	Sandbox
QA	QA DB	INFO	QA API
Production	Production DB	WARN/INFO	Production API

Without profiles, developers often end up changing configuration manually before each deployment.

3. The @Profile Annotation

You can mark a @Component, @Configuration, or @ConfigurationProperties with @Profile to control when it is loaded.

import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

@Configuration(proxyBeanMethods = false)
@Profile("production")
public class ProductionConfiguration {

    // Production-only configuration
}

This configuration is loaded only when the production profile is active.

Simple mental model

If production is not active, this configuration is not loaded.

4. @Profile on Components

You can use profiles on regular Spring components as well.

@Component
@Profile("dev")
public class DevEmailService implements EmailService {

    @Override
    public void send(String message) {
        System.out.println("DEV EMAIL: " + message);
    }
}

@Component
@Profile("production")
public class ProductionEmailService implements EmailService {

    @Override
    public void send(String message) {
        // Send a real email
    }
}

Now:

Active profile	Bean available
dev	DevEmailService
production	ProductionEmailService

5. @Profile on @Configuration

A very common pattern is to put several related beans inside a profile-specific configuration class.

@Configuration
@Profile("dev")
public class DevConfig {

    @Bean
    public PaymentClient paymentClient() {
        return new FakePaymentClient();
    }

    @Bean
    public EmailClient emailClient() {
        return new ConsoleEmailClient();
    }
}

@Configuration
@Profile("production")
public class ProductionConfig {

    @Bean
    public PaymentClient paymentClient() {
        return new RealPaymentClient();
    }

    @Bean
    public EmailClient emailClient() {
        return new RealEmailClient();
    }
}

6. Activating a Profile

Spring Boot uses the spring.profiles.active property to specify active profiles.

application.properties

spring.profiles.active=dev

application.yaml

spring:
  profiles:
    active: "dev"

Command line

java -jar app.jar --spring.profiles.active=dev

You can activate more than one profile:

spring.profiles.active=dev,hsqldb

This means both dev and hsqldb are active.

7. Command Line Can Override application.properties

Suppose your file contains:

spring.profiles.active=dev

But you start the application with:

java -jar app.jar --spring.profiles.active=production

The command-line value wins because spring.profiles.active follows the normal property-source ordering rules. The highest-precedence source wins.

8. Default Profile

If no profile is active, Spring Boot enables a default profile.

The default profile name is:

default

You can change it:

spring.profiles.default=local

Now, when no explicit profile is active, local becomes the default profile.

Disable the default profile

spring.profiles.default=none

This means no default profile is automatically activated.

9. Active vs Default Profile

Property	Meaning
spring.profiles.active	Explicitly chooses profiles to activate.
spring.profiles.default	Defines what profile is used when no profile is active.

10. Important Rule: Where active/default Can Be Used

spring.profiles.active and spring.profiles.default can only be used in non-profile-specific documents. They cannot be placed inside profile-specific files or documents activated using spring.config.activate.on-profile.

Invalid example

spring.profiles.active=prod

#---

spring.config.activate.on-profile=prod
spring.profiles.active=metrics

The second document is invalid because it attempts to activate profiles from a profile-activated document.

11. Profile-Specific Configuration Files

You can create separate configuration files for each profile.

application.properties
application-dev.properties
application-qa.properties
application-prod.properties

Example base configuration:

spring.application.name=my-api
server.port=8080

app.message=Default message

Development:

app.message=Development message
app.database-url=jdbc:postgresql://localhost/dev

Production:

app.message=Production message
app.database-url=jdbc:postgresql://prod-db/myapp

12. How Profile-Specific Files Work

Suppose:

application.properties
application-prod.properties

And:

spring.profiles.active=prod

Properties from the profile-specific configuration can override corresponding values from the base configuration.

13. Multiple Active Profiles

You can activate multiple profiles:

spring.profiles.active=prod,metrics

This can be useful when profiles represent separate concerns.

14. Adding Profiles Instead of Replacing Them

Sometimes you do not want to replace active profiles. You want to add more profiles.

Use:

spring.profiles.include[0]=common
spring.profiles.include[1]=local

YAML:

spring:
  profiles:
    include:
      - "common"
      - "local"

Included profiles are added before the profiles activated by spring.profiles.active.

15. active vs include

Property	What it does
spring.profiles.active	Defines the active profiles.
spring.profiles.include	Adds additional profiles on top of active profiles.

Example

spring.profiles.active=production

spring.profiles.include[0]=common
spring.profiles.include[1]=metrics

The effective profile set includes:

16. include Has the Same Placement Rule

Like spring.profiles.active, spring.profiles.include can only be used in non-profile-specific documents.

17. Profile Groups

Sometimes profiles become too fine-grained.

For example:

• proddb → production database
• prodmq → production messaging

Instead of activating both manually, create a profile group:

spring.profiles.group.production[0]=proddb
spring.profiles.group.production[1]=prodmq

YAML:

spring:
  profiles:
    group:
      production:
        - "proddb"
        - "prodmq"

18. Why Profile Groups Are Useful

Now you can simply run:

java -jar app.jar --spring.profiles.active=production

and Spring Boot activates:

19. Profile Groups Example

spring:
  profiles:
    group:
      production:
        - proddb
        - prodmq
      development:
        - devdb
        - devtools

Now:

Active profile	Profiles activated
production	production + proddb + prodmq
development	development + devdb + devtools

20. Profile Groups Placement Rule

spring.profiles.group can only be used in non-profile-specific documents. It cannot be defined inside a profile-specific file or a document activated by spring.config.activate.on-profile.

21. Programmatically Setting Profiles

You can programmatically add profiles before the application runs.

SpringApplication application =
        new SpringApplication(MyApplication.class);

application.setAdditionalProfiles("metrics", "local");

application.run(args);

The official documentation also notes that profiles can be activated through Spring's ConfigurableEnvironment interface.

22. @Profile with ConfigurationProperties

@ConfigurationProperties has a specific profile-related rule.

If configuration properties are scanned automatically, @Profile can be placed directly on the @ConfigurationProperties class.

@ConfigurationProperties("app")
@Profile("production")
public class ProductionProperties {

    // ...
}

But if the properties bean is registered through @EnableConfigurationProperties, put @Profile on the configuration class containing @EnableConfigurationProperties.

Example with @EnableConfigurationProperties

@Configuration
@Profile("production")
@EnableConfigurationProperties(ProductionProperties.class)
public class ProductionConfig {
}

23. Profile Validation

Spring Boot validates profile names by default.

Permitted profile names can contain letters, numbers, and characters such as:

They must start and end with a letter or number.

If you need more flexible profile names, you can disable validation:

spring.profiles.validate=false

YAML:

spring:
  profiles:
    validate: false

This behavior is documented in the current Spring Boot Profiles documentation.

24. Profile Files vs @Profile

These two concepts are related but different.

Feature	Purpose	Example
Profile-specific file	Change property values by environment.	application-prod.properties
@Profile	Choose which beans/configuration classes are created.	@Profile("prod")

25. Dev / QA / Production Example

application.properties

spring.application.name=my-api
app.timeout=30s

application-dev.properties

app.database-url=jdbc:postgresql://localhost/dev
app.logging-level=DEBUG

application-qa.properties

app.database-url=jdbc:postgresql://qa-db/myapp
app.logging-level=INFO

application-prod.properties

app.database-url=jdbc:postgresql://prod-db/myapp
app.logging-level=WARN

Run development:

java -jar app.jar --spring.profiles.active=dev

Run QA:

java -jar app.jar --spring.profiles.active=qa

Run production:

java -jar app.jar --spring.profiles.active=prod

26. Real-World Bean Switching

Suppose your application sends notifications.

Development

@Component
@Profile("dev")
public class ConsoleNotificationService
        implements NotificationService {

    public void send(String message) {
        System.out.println(message);
    }
}

Production

@Component
@Profile("prod")
public class EmailNotificationService
        implements NotificationService {

    public void send(String message) {
        // Send real email
    }
}

Now the application can use the same interface while the implementation changes according to the active profile.

27. Combining Profiles with Externalized Configuration

Profiles become especially powerful when combined with externalized configuration.

For example:

application.properties
application-prod.properties
Environment variable
Command-line argument

The final value is determined by Spring Boot's property-source precedence rules.

28. Common Mistakes

Mistake	Correct understanding
Putting spring.profiles.active inside application-prod.properties.	Active/default profile properties belong in non-profile-specific documents.
Thinking include replaces active profiles.	include adds profiles.
Manually activating every fine-grained profile.	Use a profile group.
Using a profile only for property values when bean implementations must change.	Use @Profile on components/configuration.
Assuming the default profile runs even when another profile is active.	The default profile is used when no profile is active.
Ignoring property precedence.	Higher-precedence sources can replace active profile configuration.
Putting @Profile on the wrong configuration-properties registration point.	Placement depends on whether scanning or @EnableConfigurationProperties is used.

29. Best Practices

1. Use clear names: dev, qa, staging, prod.
2. Keep common configuration in the base file.
3. Put environment-specific values in profile-specific files.
4. Use @Profile when bean implementations should change.
5. Use profile groups when multiple low-level profiles always travel together.
6. Use include when common additional profiles should always be added.
7. Do not put secrets in profile files committed to Git.
8. Use externalized configuration and environment variables for deployment-specific secrets.
9. Understand precedence before debugging profile behavior.

30. Quick Decision Guide

Requirement	Use
Different property values for dev/prod	Profile-specific files
Different bean implementation for dev/prod	@Profile
Always add common configuration	spring.profiles.include
Group several profiles under one logical name	spring.profiles.group
Choose active environment	spring.profiles.active
Choose fallback profile	spring.profiles.default
Add profiles from Java	setAdditionalProfiles()
Need custom profile-name syntax	spring.profiles.validate=false

31. Interview Questions

1. What is a Spring Profile?
2. Why do we use profiles in Spring Boot?
3. What does @Profile do?
4. Where can @Profile be used?
5. How do you activate a profile?
6. What is spring.profiles.active?
7. What happens if no profile is active?
8. What is spring.profiles.default?
9. How can you disable the default profile?
10. Can spring.profiles.active be placed inside a profile-specific file?
11. What is the difference between active and include?
12. What is a profile group?
13. Why would you use spring.profiles.group?
14. How do you activate profiles programmatically?
15. What is the difference between application-prod.properties and @Profile("prod")?
16. How does property precedence affect active profiles?
17. How does @Profile work with @ConfigurationProperties?
18. What is profile validation?

32. Practice Exercises

33. Cheat Sheet

Concept	Example
Activate profile	spring.profiles.active=prod
Command-line activation	--spring.profiles.active=prod
Default profile	spring.profiles.default=local
No default profile	spring.profiles.default=none
Add profiles	spring.profiles.include
Group profiles	spring.profiles.group
Profile-specific properties	application-prod.properties
Profile-specific bean	@Profile("prod")
Programmatic profiles	setAdditionalProfiles()
Disable profile-name validation	spring.profiles.validate=false

34. Memory Map

35. Final Takeaway