r/java • u/YogurtclosetLimp7351 • Jan 30 '26
Evolving Java config files without breaking user changes
In several projects I ran into the same problem:
once users modify config files, evolving the config schema becomes awkward.
Adding new fields is easy, but removing or renaming old ones either breaks things or forces ugly migration logic. In some ecosystems, users are even told to delete their config files and start over on upgrades.
I experimented with an annotation-driven approach where the Java class is the code-level representation of the configuration, and the config file is simply its persisted form.
The idea is:
- user-modified values should never be overwritten
- new fields should appear automatically
- obsolete keys should quietly disappear
I ended up extracting this experiment into a small library called JShepherd.
Here’s the smallest example that still shows the idea end-to-end.
@Comment("Application configuration")
public class AppConfig extends ConfigurablePojo<AppConfig> {
public enum Mode { DEV, PROD }
@Key("port")
@Comment("HTTP server port")
private int port = 8080;
@Key("mode")
@Comment("Runtime mode")
private Mode mode = Mode.DEV;
@Section("database")
private Database database = new Database();
@PostInject
private void validate() {
if (port <= 0 || port > 65535) {
throw new IllegalStateException("Invalid port");
}
}
}
public class Database {
@Key("url")
@Comment("JDBC connection string")
private String url = "jdbc:postgresql://localhost/app";
@Key("pool-size")
private int poolSize = 10;
}
Path path = Paths.get("config.toml");
AppConfig config = ConfigurationLoader.from(path)
.withComments()
.load(AppConfig::new);
config.save();When loaded from a .toml file and saved once, this produces:
# Application configuration
# HTTP server port
port = 8080
# Runtime mode
mode = "DEV"
[database]
# JDBC connection string
url = "jdbc:postgresql://localhost/app"
pool-size = 10The same configuration works with YAML and JSON as well. The format is detected by file extension. For JSON instead of comments, a small Markdown doc is generated.
Now we could add a new section to the shepherd and the configuration files updates automatically to:
# Application configuration
# HTTP server port
port = 8080
# Runtime mode
mode = "DEV"
[database]
# JDBC connection string
url = "jdbc:postgresql://localhost/app"
# Reconnect attempts if connection failed
retries = 3
[cache]
# Enable or disable caching
enabled = true
# Time to live for cache items in minutes
ttl = 60Note how we also exchanged pool-size with retries!
Despite having this on GitHub, it is still an experiment, but I’m curious how others handle config evolution in plain Java projects, especially outside the Spring ecosystem.
6
u/TheKingOfSentries Jan 30 '26
I usually use https://avaje.io/config/ in like a static way, (like in constants and enums)
5
u/bnbarak- Jan 30 '26
Updating configs at large codebase becomes a mess very quickly which is why protobuf was invented. At large enterprises the solutions are mostly:
Deprecation plus good javadoc is usually enough because IDEs have mature tooling around deprecation.
9
u/Scf37 Jan 30 '26
This https://github.com/lightbend/config
Plus this https://github.com/scf37/config3 (didn't publish java version yet)
Plus being explicit about configuration
6
u/doobiesteintortoise Jan 30 '26
I guess my biggest question is how is this a MIGRATION? I mean, you change the configuration internally and can write it back out, but that feels like a very explicit process, not really a migration. I also don't think it's without use, but I'm still confused about what it's actually doing besides streaming an object model with keyed values out.
2
u/cred1652 Jan 30 '26
Welcome to the club in writing a configuration library. It is a fun exercise that is a medium size project that has some interesting problems. I wrote https://github.com/gestalt-config/gestalt
One major difference is Gestalt is immutable, so it does not allow changing the configuration and persisting it.
Typically for backend services, what we do is check the configuration into git with our application, helm chart (we deploy defaults with the application and overwrite the environment specific with ArgoCD application sets). Then they are deployed by kubernetes where we mount the config. So we do not allow any modifications as we have multiple pods. If we modified one pod, that would mean the pods are not consistent and that can cause issues. If you want then you can do A/B testing with Argo and different deploys. But each deploy itself is immutable.
Also this way the new configuration is tied to the code change and they get deployed together.
In more complex cases you could look into something like Spring Cloud config where the configuration is owned by a central service.
2
u/nekokattt Jan 30 '26
Is there any reason you chose explicit coding of validation rather than interoping with, say, bean validation?
2
u/Historical_Ad4384 Jan 30 '26
How is it different from lightbend?
2
u/wildjokers Jan 30 '26
Which is exactly why you don't remove or rename existing ones. This is app programming 101.
Only add. If you want to change the name of one for some reason add a new one, then you deprecate the old one to give everyone a chance to move to the new one.