DEV Community: Rahkel Pekins

My Tests Were Green on the Wrong Database — Moving to Real PostgreSQL with Flyway

Rahkel Pekins — Sun, 25 Oct 2026 18:55:28 +0000

In Part 1 I ended with a question I was genuinely sitting with: REST controllers first, or persistence first?

Persistence won — in the project's own ROADMAP order. And it turned out to be the right call, because it exposed something uncomfortable: my repository tests were green, but they were green on the wrong database.

The problem: H2 was hiding the truth

Up to this point, the app's tests ran against H2, an in-memory stand-in. That's fine for fast unit tests. It's not fine as proof that your schema works, because the database your app will actually run on is PostgreSQL — different engine, different constraint behavior, different failure modes.

A test passing on H2 only proves the code works in a world that doesn't exist. So Phase 3 had one job: make the persistence layer real, reproducible, and proven on the real engine.

Shipped: four PRs, one evening

PR #13 — ROADMAP close-out, and one docs-vs-code call: my ROADMAP listed a POOR book condition that my enum didn't have, so I changed the code, not the doc. POOR was appended to BookCondition after FAIR.
PR #14 — Flyway plus the baseline migration.
PR #15 — Environment-based database config and documentation.
PR #16 — Repository tests on real PostgreSQL, plus a matching CI service.
48 tests when the evening ended.

Flyway owns the schema now

The baseline migration, V1_initial_schema.sql, creates all five tables and mirrors the JPA entities exactly — including named constraints, so a failure message points at a real, findable thing instead of an anonymous auto-generated name:

CREATE TABLE book_copies (
id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
barcode VARCHAR(255) NOT NULL,
is_available BOOLEAN NOT NULL,
times_borrowed INTEGER NOT NULL,
condition VARCHAR(255) NOT NULL,
acquired_date DATE NOT NULL,
book_id BIGINT NOT NULL REFERENCES books (id),
owner_id BIGINT NOT NULL REFERENCES library_members (id),
visibility VARCHAR(255) NOT NULL,
CONSTRAINT book_copy_barcode UNIQUE (barcode)
);

That owner_id foreign key is the ownership work from Part 1, now real in the database — a copy cannot exist without a member who owns it. The other tables follow the same pattern: library_members with a named library_member_email unique constraint, books with book_isbn, and borrowings linking book, copy, and borrower.

The key decision is in the profile that runs against it:

spring.datasource.url=${DB_URL:jdbc:postgresql://localhost:5432/library}
spring.datasource.username=${DB_USERNAME:library}
spring.datasource.password=${DB_PASSWORD:}
spring.datasource.driver-class-name=org.postgresql.Driver
spring.flyway.enabled=true
spring.jpa.hibernate.ddl-auto=validate

ddl-auto=validate is the whole philosophy in one line. Hibernate no longer creates or updates the schema — Flyway applies the migration, and Hibernate checks the entities agree with it, refusing to start if they don't. The migration is the source of truth. Never edit an applied migration; schema changes ship as new V2_..., V3_... files.

Config that doesn't leak secrets

Database settings moved to environment variables with a .env.example in the repo, and the README gained a "Database Setup (PostgreSQL)" section so anyone cloning the project can reproduce the setup from scratch. No credentials live in the code.

One honest detail: there's no Docker on my machine, so the usual Testcontainers route was out. PostgreSQL 17 runs natively on my machine instead. Not the fashionable path — the path that actually works in my setup. The CI side still gets the standard treatment: a postgres:17 service with a health check, matching the test setup.

The test that finally proves something

Only one test class moved off H2 — BookCopyRepositoryTest. The other 45 tests stay where they are; this was never about moving everything, it was about proving the repository layer against the real engine.

The gotcha that would have silently undone the whole thing: @DataJpaTest swaps in an embedded database by default. Without one annotation, my "PostgreSQL test" would have been an H2 test wearing a PostgreSQL costume:

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@TestPropertySource(locations = "classpath:application-pgtest.properties")
class BookCopyRepositoryTest {

Replace.NONE is the line that makes it real. The test profile points at a dedicated library_test database, with Flyway on and ddl-auto=validate — so the test schema is built by the same migration the app uses, not by Hibernate improvising one.

And the test I'm proudest of is a failure. Saving a second copy with a duplicate barcode throws a PersistenceException whose root cause names the real book_copy_barcode unique constraint. That's proof the constraint exists on the real engine — not just in an annotation, not just in H2's approximation of it.

What I learned

An in-memory database is a stand-in, not a substitute. It's great for speed, dangerous as proof.
Named constraints are documentation. When a test fails, it should tell you exactly which rule broke.
validate beats create-drop once a schema exists. Letting the ORM silently rebuild your schema hides drift between your entities and your migrations — the exact drift that breaks you in production.
The unglamorous work is the platform. Nobody demos a migration file. But without it, every feature built on top is sitting on a schema nobody can reproduce.

What's next

Persistence is done: externalized config, reproducible migrations, integration tests on the real database. The next chapter is the REST API — controllers and global exception handling on top of the service layer, so this stops being a library only other code can use and starts becoming a platform members can actually call.

I'm working on that today, and it gets its own post next week — after it's actually finished, not before. That's the rule for this series: shipped first, posted second.

If you've moved a project from H2 (or SQLite, or any in-memory stand-in) to a real database, what broke first — the schema, the tests, or your assumptions? I'd genuinely like to hear it.

Code, if you want to follow along or tell me what you'd do differently:
GitHub - github.com/Pekins1/LibraryManagementSystem

— Rahkel

I'm Building a Peer-to-Peer Library Platform in Public — From a Legacy Java Monolith to Spring Boot

Rahkel Pekins — Sun, 18 Oct 2026 18:13:50 +0000

Hi, I'm Rahkel. I'm a backend developer, and I'm building a software project solo, in public.

This series is the log of that build — twice a week, what I shipped, the design decisions behind it, what broke, and what's next. No highlight reel. If a test fails on a Saturday and I have to leave for work before I can fix it, that goes in the log too. (That has already happened. More than once.)

The idea

I'm turning my old Library Management System into a peer-to-peer library platform.

Instead of one library owning every book, individuals catalog their own personal collections. Other members can discover those books and borrow the copies the owners choose to make public. Owners will also be able to give books away to interested members, or donate them to an actual library. And libraries and organizations can run the same lending functionality for their own patrons.
That's the destination. This series is about the unglamorous part: rebuilding the foundation so that destination is actually possible.

Where it started

Honestly? I cringe a little looking at the original code — and I've learned to take that as a good sign. It means my standards moved.

🔴 Before:

A console app built around one massive Library class
Borrowing, duplicates, genres, and limits all handled in the same place
Books tracked in in-memory lists and maps — close the app, lose the state
No separation between a book title and the physical copies of it
It worked as a learning project. It could never work as a platform where real people lend each other real books.

Where it is now

🟢 Now:

Rebuilt on Java 21 + Spring Boot, and the app actually boots and runs
A layered architecture: dedicated services (BookService, BorrowService, LibraryMemberService), Spring Data JPA repositories, DTOs for requests, and @Transactional workflows
Books modeled as titles with multiple physical copies, each tracked on its own
Tests at every step — 47 and counting

The part I just finished: ownership and visibility

Here's something I didn't appreciate until I started building it: a peer-to-peer library is impossible until the code knows who owns what.
When I started this phase, my book copies belonged to nobody and were effectively visible to everybody — exactly backwards for a platform where people lend out their own collections. So the most recent chapter of the build (Step 2, just completed) was:

A new LibraryMember entity — the platform member who owns book copies, with a MemberType of INDIVIDUAL or ORGANIZATION, because a person and a library won't use this the same way
A member-creation path with proper validation and a case-insensitive email lookup
CopyVisibility on every copy:
public enum CopyVisibility {
PRIVATE,
PUBLIC
}
PRIVATE is the default — owner only, cannot be borrowed. PUBLIC means other members can discover the copy and borrow it. Privacy first, sharing by choice.

A discovery query that only ever surfaces available PUBLIC copies — private copies don't just fail to borrow, they don't show up at all

One design decision I made on purpose, and would defend: the owner is not the existing Borrower entity. A member owns and lends copies. A borrower is an external patron of a library — a different job. Collapsing those two into one entity would have been faster for a week and messier forever.

What happens in this series

Every post follows the same simple shape:
Shipped: what actually landed in the code, with the PR to prove it
Decided: one design call, and why I made it
Next: what I'm building next

I'm doing this for three reasons: to hold my own standards up where people can see them, to find a community of developers building similar things, and because I'm open to collaborations — feedback on the design is genuinely welcome, especially when you think I got a call wrong.

What's next

Ownership and visibility were groundwork. The platform layer they were groundwork for — exposing this as a real API with real persistence, so members can actually use it — is the next chapter, and I'm deciding the exact order of that work right now.

So I'll end with the question I'm actually sitting with:

If you were building this, would you put the REST controllers on top of the current service layer first, or lock down the persistence/database layer first — and why?

Follow the series if you want to watch a legacy monolith become a platform, one decision at a time.

Code, if you want to follow along or tell me what you'd do differently: github.com/Pekins1/LibraryManagementSystem