Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 36 ยท Config and Profiles

Configuration Properties and Profiles

Read settings in Quarkus with @ConfigProperty and application.properties, switch values with the %dev, %test and %prod profiles, and learn the source order.

Almost every service needs settings that change between your laptop, the test run and production: a database URL, a greeting, a timeout, a feature switch. Quarkus does not invent its own system for this. It uses SmallRye Config, an implementation of the MicroProfile Config specification, and one file, src/main/resources/application.properties, is where most values live.

This lesson shows how to read a value, how to give it a default, how profiles let one file hold three environments, and in which order the different sources win. The next lesson, typed configuration mapping, builds on it.

The real Quarkus runtime cannot run on this site, so the real code below is read-only. The TryIts are small Java stand-ins that implement the same lookup rules, so you can see the logic run.

Reading a value

Inject a single property with @ConfigProperty. The name is the key in the configuration; defaultValue is used when no source defines it:

Java
import jakarta.enterprise.context.ApplicationScoped;
import org.eclipse.microprofile.config.inject.ConfigProperty;
import java.util.Optional;

@ApplicationScoped
public class GreetingService {

    @ConfigProperty(name = "greeting.message", defaultValue = "Hello")
    String message;

    @ConfigProperty(name = "greeting.suffix")
    Optional<String> suffix;

    public String greet(String name) {
        return message + ", " + name + suffix.orElse("");
    }
}
PROPERTIES
# src/main/resources/application.properties
greeting.message=Welcome

Three rules to remember:

  • A property with no default and no value makes the application fail at startup, not later at the first request. That is deliberate: a missing database URL should stop the deploy, not the first customer.
  • Wrap the type in Optional<T> when the value really is optional.
  • Conversion is automatic for primitives, wrappers, Duration, List<String>, enums, URI and more. greeting.timeout=30s can be injected into a Duration.

The injected fields can be package-private. You do not need private plus a getter, and Quarkus works better without private injected fields because it can skip reflection.

You can also read config programmatically, for example in a static helper:

Java
import org.eclipse.microprofile.config.ConfigProvider;

int port = ConfigProvider.getConfig()
        .getValue("quarkus.http.port", Integer.class);

Profiles

A profile is a named environment. Quarkus has three built in:

Profile Active when
dev You run quarkus dev or ./mvnw quarkus:dev
test Tests run with @QuarkusTest
prod Anything else, for example java -jar or a native binary

You put the profile in front of a key with a percent sign. A key without a prefix applies everywhere; a prefixed key applies only in that profile and overrides the unprefixed one:

PROPERTIES
greeting.message=Hello
%dev.greeting.message=Hello from dev mode
%test.greeting.message=Hello from a test

quarkus.log.level=INFO
%dev.quarkus.log.level=DEBUG

%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://db:5432/shop

You can create your own profile such as staging and activate it with -Dquarkus.profile=staging or the environment variable QUARKUS_PROFILE=staging. Several profiles can be active at once, separated by commas, and the one listed last wins.

There is also a file per profile: application-staging.properties is read when the staging profile is active, and it can omit the %staging. prefixes.

One file, three worlds

dev Live reload, debug logs, Dev Services.
test Fast, isolated, random HTTP port.
prod Packaged jar or native binary.

The same code runs in all three. Only the values change.

1 / 2

Where values can come from

A value can live in several places at once. SmallRye Config gives each source a number called its ordinal, and the highest ordinal wins:

Source Ordinal
System properties (-Dgreeting.message=Hi) 400
Environment variables 300
.env file in the working directory 295
application.properties in the working directory (config/) 260
application.properties in the classpath 250
META-INF/microprofile-config.properties 100

This is why you can ship one jar and override a single value on the server without a rebuild: set an environment variable and it beats the file packed inside the jar.

Environment variable names cannot contain dots or dashes, so Quarkus maps them: uppercase everything and replace every character that is not a letter or digit with an underscore. greeting.message is read from GREETING_MESSAGE, and quarkus.datasource.jdbc.url from QUARKUS_DATASOURCE_JDBC_URL.

Java Stand-in: ordinals and profiles

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that the environment variable, which has the higher ordinal, wins over %dev.greeting.message in the file. The profile prefix only decides between keys inside one source; the source ordinal decides first.

Expressions and defaults inside the file

Values can refer to other keys with ${...}, and you can give an inline default after a colon:

PROPERTIES
app.name=bookshop
app.home=/var/${app.name}
app.cache.dir=${app.home}/cache
app.region=${REGION:eu-central}

${REGION:eu-central} means "use the property or variable REGION, and fall back to eu-central". If a referenced key has no value and no default, startup fails with a clear message.

Java Stand-in: ${key:default} expansion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Quarkus's own settings

Everything Quarkus itself needs is configured the same way, under the quarkus. prefix: quarkus.http.port, quarkus.log.level, quarkus.datasource.jdbc.url. There is no special API; you use the same file and the same profiles. In dev mode the Dev UI, at http://localhost:8080/q/dev-ui, lists every known key with its current value.

Some values are build-time properties: they are read while the application is being built and then frozen. A runtime override of such a key is ignored, and Quarkus warns about it at startup. The configuration reference marks these with a padlock. How Quarkus works at build time explains why this split exists.

Common mistakes

  • Putting a secret such as a password into application.properties and committing it. Use an environment variable, a .env file kept out of version control, or a secret store (see secrets).
  • Forgetting the %prod. prefix on production-only values, then wondering why dev mode tries to connect to the production database.
  • Expecting %dev. keys to apply in tests. Tests use the test profile.
  • Using a field type that cannot convert the text, such as int for abc. That fails at startup, which is the correct behavior.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens at startup if a @ConfigProperty has no default and no configured value?

    Missing required configuration is detected during startup, so a bad deployment stops early instead of failing for users later.
  2. 2. Which source wins when the same key is in an environment variable and in the packaged application.properties?

    SmallRye Config sorts sources by ordinal and the highest one wins. That is what lets you override a value on the server without rebuilding.
  3. 3. Which environment variable name overrides quarkus.datasource.jdbc.url?

    Non-alphanumeric characters become underscores and the name is uppercased.
  4. 4. What does ${REGION:eu-central} do in a property value?

    The part after the colon is an inline default, used when the referenced key has no value.

Summary

  • @ConfigProperty injects one value; defaultValue or Optional makes it optional, otherwise it is required at startup.
  • Profiles dev, test and prod select values with %profile.key; you can add your own.
  • The source with the highest ordinal wins: system properties, then environment variables, then files.
  • ${key:default} expressions compose values inside the file.
  • Build-time properties are frozen at build and cannot be changed at runtime.

Next: Typed Configuration with @ConfigMapping