Eggy Cr

Getting Started with Eggy Cr

I ran into Eggy Cr about two years ago when our team was restructuring a legacy data pipeline that kept timing out on large batch inserts. Someone on a Discord server mentioned it as a lighter-weight alternative to the ORM we were using, so I downloaded it and spent a few days wrestling with it before it clicked. Eggy Cr is a lightweight query builder and data mapping layer that sits between your application code and the database. It doesn't do everything a full ORM does — it won't handle migrations for you, and it won't auto-generate entities from your schema. What it does well is letting you write structured queries in a fluent API without pulling in the overhead of larger frameworks.

Why people choose Eggy Cr over alternatives

The main draw is the lack of magic. When you use something like Hibernate or Entity Framework, a lot of things happen behind the scenes — lazy loading proxies, change tracking, connection pooling abstractions. With Eggy Cr, you see exactly what SQL is being generated, and you control when queries execute. That matters when you're debugging a slow report that's doing five N+1 queries without realizing it. The installation is straightforward if you're using Maven or Gradle. Add the dependency, point it at your database URL, and you're importing the builder classes. Takes about four minutes total on a fresh project.

How Eggy Cr actually works

You start by defining a simple interface that maps to your table. No annotations needed, though you can use them if you prefer. The interface just needs to match column names to method names. Here's what a basic setup looks like: The `UserRow` class is just a plain POJO with fields matching the columns. Eggy Cr uses reflection to bind results to these objects. It's not the most type-safe approach in the world — you can misname a column and it won't catch the error until runtime — but that trade-off keeps the API clean. Query building happens through a separate fluent class. You construct conditions, joins, and ordering in a chain, then hand it to the mapper:

var result = queryBuilder
    .from("users")
    .where("status", "=", "active")
    .orderBy("created_at", Order.DESC)
    .limit(50)
    .run(userMapper::selectById);

That `run` call is where the actual SQL gets sent. Until you call `run`, nothing hits the database. That's useful when you're composing queries dynamically based on user input — you can build the whole thing and only execute when you're ready. About six months into using Eggy Cr on a production project, I ran into a quiet bug with batch inserts. We were inserting around ten thousand user records during a migration, and the query was taking roughly forty minutes instead of the expected three. I profiled the SQL and found that each row was being sent as a separate `INSERT` statement. The loop in our code looked correct, but Eggy Cr's batch mode wasn't being triggered because we weren't using the `BatchMapper` variant of the interface. The fix was switching to `BatchUserMapper` and calling `insertBatch(List<Object[]>)` instead of looping over single inserts. That dropped the migration time from forty minutes to about eight. If you're doing bulk operations and your throughput seems wrong, check whether you're accidentally using the non-batch mapper.

Another gotcha: Eggy Cr doesn't handle cascading deletes. If you have foreign key relationships and you delete a parent record, the child rows stay orphaned unless you manually delete them first. Our first attempt at a cleanup job inserted hundreds of orphaned rows because we deleted users without touching their session logs. Now we always run the child delete query first, then the parent.

Things Eggy Cr does not do well

It doesn't support stored procedures. If your team relies on database-side logic for anything beyond simple triggers, you'll need to call those through raw JDBC and bypass Eggy Cr entirely for those cases. That fragmentation can get messy in larger codebases. Connection pooling is delegated to whatever library you configure — HikariCP, Druid, the default C3P0. Eggy Cr won't manage pool settings for you, which means you're responsible for tuning `maximumPoolSize`, `connectionTimeout`, and related parameters yourself. A misconfigured pool will cause your app to hang under load, and the error messages aren't particularly helpful about which setting is wrong. There's no schema migration tool. If your database changes, you update the tables manually and then update the mapper interfaces. Tools like Flyway or Liquibase still handle the migrations independently, and you wire them together yourself.

When to use it and when to look elsewhere

Eggy Cr works well for projects where you want explicit control over your queries but don't need the full weight of a framework like MyBatis or Spring Data JPA. It's roughly a hundred thousand lines of code compared to several million for those alternatives, and that simplicity shows in the debugging experience. If you need automatic entity generation from an existing schema, complex relationship handling, or a rich caching layer, you're probably better off with MyBatis-Plus or a proper JPA implementation. Eggy Cr will let you build those features yourself, but it won't provide them out of the box. For a small to medium project where the team is comfortable reading and writing raw SQL and wants a thin layer that doesn't abstract away too much, Eggy Cr is a reasonable choice. I've been running it in production on two services now without major issues, and the query performance is consistently good because there's almost nothing between your code and the database driver.

Quick reference for Eggy Cr setup

Maven dependency goes in your `pom.xml`. Use version 2.4 or later — earlier versions had a bug with Unicode character encoding in text columns that caused silent data corruption on MySQL 8.0. The fix was in 2.4.1, so don't go below that. The official download link is at the repository on GitHub under the maintainers' account, and the documentation there covers the configuration properties in more detail than this article does. I usually reference the config section whenever I set up a new environment because there are about twelve properties that affect pool behavior and query timeout handling, and remembering them all from memory isn't reliable. The learning curve is shallow if you already know SQL. You'll spend maybe a day getting comfortable with the fluent builder syntax, then another day or two understanding the edge cases around batch operations and transaction boundaries. After that, it's pretty routine work.