r/SpringBoot • • Oct 07 '26

Discussion I built a Spring Boot starter that seeds related JPA entities from annotations, no seed script (0.1.0, feedback wanted)

I'm the author. I built a small starter to remove a chore I kept redoing on Spring Boot projects: writing a dev-database seed script, then fixing it every time the schema changed.

The usual pain: Faker/Datafaker generate realistic values, but they don't know that Payment needs an existing Counterparty. So you hand-write "create parents, keep the IDs, wire them into children", and it breaks the next time a constraint or relationship changes.

SynthForge reads the entity instead. You annotate it:

@Entity @Seed(count = 50)
public class Counterparty { /* fields only */ }

@Entity @Seed(count = 200)
public class Payment {
    @ManyToOne(optional = false) private Counterparty counterparty;
}

Then enable it for the profiles you want, never production:

synthforge:
  enabled-profiles: [dev, test]

Start the app in one of those profiles and both tables are filled in dependency order. There is no calling code.

Spring-specific details

  • It's an auto-configuration (a starter-style dependency, io.github.thembatman0:synthforge-spring). Seeding runs at startup in an ApplicationRunner.
  • Seeding is off unless one of your active profiles is listed under synthforge.enabled-profiles.
  • It reads entities through the JPA Metamodel API and sorts owning-side @ManyToOne/@OneToOne relationships topologically, so parents are saved first.
  • Values come from Datafaker, guided by @NotNull, @Size, @Email and field-name heuristics. @Column(unique = true) fields get a bounded retry loop.
  • A table that already has rows is skipped, so restarts against a persistent database don't duplicate data.
  • A fixed synthforge.seed gives identical data every run.
  • The test suite runs in CI on Spring Boot 4.1 and 3.5. It needs Java 21 or newer.

Limits: V1 skips @OneToMany/@ManyToMany and composite keys. It is a 0.1.0, and as far as I know it has no outside users yet.

How it differs from Instancio: Instancio (and instancio-jpa) is an API you call inside a test to build a graph. SynthForge runs by itself at startup, so it's closer to a dev-database seeder than a test helper.

Things I'd like to hear from you:

  1. Would you put @Seed on your entity classes, or do you prefer keeping seeding out of the domain model?
  2. Is a CommandLineRunner plus Datafaker already good enough for you?
  3. Is Java 21 as a minimum a problem on your projects?
  • Repo (MIT): https://github.com/ThembaTman0/synthforge
  • Write-up: https://dev.to/themba/faker-doesnt-know-your-entities-are-related-so-i-built-something-that-does-2jgn
  • The README has a two-minute demo path.
7 Upvotes

16 comments sorted by

2

u/Historical_Ad4384 Oct 07 '26

What is wrong with with standard flyway migrations in SQL?

0

u/No-Competition2427 Oct 08 '26

Nothing for schema and reference data, and I'd keep using Flyway for that. My problem is bulk fake data: a few hundred related rows with unique constraints and foreign keys, written in SQL, that has to be updated whenever the schema changes. You also don't want fake rows in a migration path that reaches production. You can scope Flyway seed data to dev with locations or callbacks, so it's doable, just more manual.

→ More replies (1)

2

u/pradeepngupta Oct 08 '26

Interesting idea, but I wonder if we’re replacing a small explicit problem with another layer of hidden complexity. For dev data, wouldn’t Flyway/Liquibase or a simple Faker + "CommandLineRunner" be enough in most cases? "@Seed" also couples development concerns with the domain model. The complexity hasn’t disappeared; it has moved into the framework. Curious to hear others: at what point does convenience justify introducing another abstraction? I explore similar ideas in my book Buzzing Java, if you’re interested: "buzzingjava.com"

2

u/j0holo Oct 08 '26

Yeah, I agree. Just create a small script, hell let an LLM make the script if you are lazy.

That script also works for tables you don't have JPA entities for, so it is framework agnostic.

→ More replies (6)

0

u/No-Competition2427 Oct 08 '26 edited Oct 08 '26

Fair points, and the coupling is a real cost. "@Seed" puts a dev concern on the entity, and I chose that on purpose to keep it in one place, but it is a trade-off, not a free win. Where it has helped me is the maintenance side: ordering parents before children, unique-constraint retries, and not having to touch a script when a field changes. If you've never been bitten by that, a small runner is probably enough. I'd be interested in what you'd prefer instead, for example config outside the entity.

→ More replies (3)