Migrating from Spring Data JPA to Spring Data JDBC: A Comprehensive Guide

Migrating from Spring Data JPA to Spring Data JDBC requires identifying aggregates, simplifying references, and writing converters for a seamless transition.

### Migrating from Spring Data JPA to Spring Data JDBC: A Comprehensive Guide
* 🏗 Before we start with the actual migration, we have to **settle down some foundations**.
* 📝 "Don't start any kind of migration without a **serious set of tests**."
* 👶 "Walk with baby steps: make the **smallest possible change**, run all your tests, and **commit**."
* 🔗 "Use the Mikado method: **create a big refactoring goal**, **break it down into small steps**, and **undo changes that can't be completed yet**."
* "Spring Data JDBC is strongly based on the concepts of **Aggregates** from Domain-Driven Design."
* 🔄 "Decide whether to go **breadth-first** (applying the same step to all Aggregates) or **depth-first** (completely migrating one Aggregate at a time)."
* 🔍 "The first step is to identify your Aggregates and **remove all extra repositories that don't belong to an Aggregate**."

[Music]: Okay, um, welcome to my talk and, uh, thanks for having me in Barcelona. Um, looks like a really nice place to visit. Um, guess I should have brought a little more time, but anyway, at least the view outside the windows is nice. I'm going to talk about how to migrate from Spring Data JPA to Spring Data JDBC. I guess that is not a surprise for you, although I do have a couple of questions. Like the first question is, who actually read the abstract? Okay, and nobody thought it might be worth telling someone that it's totally bogus. For those that didn't read the abstract, uh, it's actually what should have gone under my or into my speaker bio. Something got mixed up there, but I guess the title kind of speaks of itself. More questions, um, I would like to understand who I'm talking to. Who likes JPA? Quite a few hands. Okay, there's no shame in that. That's okay. Who of you have actually used Spring Data JDBC, at least in like a little toy project, a demo? Most of you. That's good.

because I try not to explain too much about Spring Data JDBC itself. But who has used it in production? That, I'd say, a little more than the people that actually like JPA. So that's good. Although the A might be biased. And who is actually migrating or considering migrating? There are a few hands. Honest question: Why? No, no, really. Like you're doing a big change to your code. Why do you want to migrate? PDon come. I get a little louder. More control. More control. I think that's in general a valid, valid reason. Um, but we'll see like how you think about these reasons after the talk. Um, to be very clear, I created Spring Data JDBC. I love it. I consider it my third child. But um, as with the other two Childs and everybody that is honest about his or her child. Childs aren't perfect. And also just replacing someone with your own child. Um, isn't always that easy. Before we start with the actual migration, we have to like settle down.

some foundations um we are doing a talk of 50 minutes well actually I guess I lost two minutes um for a late start um but all this has to be considered in the context of a serious project. Like I have a little Deo demo project that I use to go through this process myself um that's basically it plus a little demo service that actually uses this domain model and the repositories. Your projects are probably much bigger or if you have some serious micro uh projects or microservices they might like a single service might look like that but then you probably have dozens of it so whatever I show you here or what I discuss um yeah that looks easy for a small project but remember in a serious context you might have to do that dozens maybe hundreds in some some cases thousands of times and partly for that reason before you start any kind of migration doesn't matter what you migrate from or to you don't start before you have a serious set of tests so test question who is comfortable to like replace your

persistence layer and be sufficiently secure that if there's something fatally wrong with a persistence layer, your test will tell you hands up. Okay, great to see that there are many hands up. Um, for all others, you know what you have to do first. And then there's something very well, really not very technical. Walk with baby steps. That's a term I learned at a conference, like, I don't know, uh, 10 years ago. And the meaning is do really, really small steps. Actually, try doing incredibly small, uh, steps because the problem is that you easily get to in really in any kind of development, but especially with refactorings. Is you think like, I'm going to solve this little problem and do a code change, and then you notice, oh no, something over here is broken. I'm going to fix that. Oh, now three things over here are broken. Am I going to start to fix those? Um, then suddenly all my project is readed. Um, two weeks have passed, uh, since the last time my code compiled, let alone all my tests run.

that's not a good state to be in, because now you have no idea how much time you need until you actually get back to a stab uh state. So always try to make the smallest possible change, run all your tests, and commit. And we can do that nowadays. I'm an old guy, I remember stuff like ACS, CVS, and srn. I think um where doing a commit was lengthy operation, and well if it worked at all. Nowadays we can do that in like it's just in the in the Shell. One Step Up in the history and return. And basically a no-brain use that and even go one step further, use the Mikado method. Who knows the Mikado method? Yeah, I was afraid of that um it's a it's a great tool. I'm not going to into much detail. The basic idea is you have a big refactoring that you want to achieve and you start by taking a probably big piece of paper and writing that goal on that piece of paper and making a circle around it. Then you think about like what could

the first small step be to get to that goal. And before you hit your keyboard, you write that little step on your PC or paper. Make a circle around it and draw an arrow from the first circle to the second. This arrow means to reach this goal, I have to do this other thing. And then you actually try to do the other thing. And then we are back to baby steps. Does it work? Does it compile? Do all your tests pass? If yes, great, you can cross out that circle on your little diagram and find the next baby step. But more likely, it doesn't work. Something turns red, a test, the compiler complains. This teaches you something. It shows you a place where you need to change something first before you can do the thing that you try to do. So what you do is you draw a new circle on your piece of paper and again connect the second circle to the third circle with an arrow, knowing, okay, now I have to do this other thing before I can do this thing. And then comes the really really

important step of the Mikado method. You undo your changes and then from all the circles that don't have any dependencies. Yet in my little examples, there's only one Circle. You try that one and maybe you find more circles. There are two benefits to this approach. One is you're doing baby steps. Like every few minutes, you're back to a stable code base that you can commit. That you can merge with your main branch. Or merge the main branch into you or rebase or however you want to work with that. And you have a good visual representation of what you still have to do. And if you plan like two weeks for refactoring and after one week, your graph hardly fits on the biggest whiteboard on your office and is still growing. You know this is not going to work in two weeks. And that is important information that you can then act on. So all this was pretty much technology independent. But there's one thing that comes from Spring data jdbc itself. Spring data jdbc is strongly based on the concepts of aggregates.

from domain-driven design who is familiar with the concept of Aggregates. Okay, more than the Mado method, still not enough. Aggregates are again a concept from domain-driven design, and an aggregate is basically a bunch of classes, typically not very many. Many Aggregates are a single class; sometimes they are two classes. If you have an aggregate that consists of five classes, it's probably too big. And the important thing about an aggregate is twofold. It is always transactionally consistent, so whatever you do to an aggregate, you always do it all or nothing. And the other thing is, whatever is inside the aggregate only gets controlled by the so-called aggregate root, which is the single class that knows about all the others. And if you want to manipulate them, these inner classes, you always do that through the aggregate root. And Spring Data JDBC uses that in a very important way. The aggregate is the unit that Spring Data JDBC uses for persisting and loading data. In JPA, you have all this cascading and different fetch

strategies. And if you aren't careful, you trigger different selects when you just access a geta or you load the whole database into memory just when you load one little entity. This is very obviously obvious in Spring Data JDBC. If you load an aggregate, it will load everything that is referenced by that aggregate by normal Java reference. And the boundaries of the Aggregates are actually defined by well not using references anymore. Instead, you basically use an ID to reference a different Aggregate. And like understanding these Aggregates is really important. At the end of the slides, I have a link to a little article I wrote. You can read up on that. That's a really important concept. And then there's one final thing you have to think about or you probably should think about before starting your migration project is, do you want to go breadth first or depth first? Basically, the steps that I'm going to show you, you have to apply them to basically every aggregate in your project if you want to do a complete

migration and it's probably like if you look at the total time you used it's probably faster. If you do the same step for all the Aggregates that are out there because then you're like in the process. Okay, I know this. I have to do this kind of stuff and then you just do it over and over and over which might become boring but very efficient. But then you have a lot of Aggregates like in the middle of a migration. If there is a chance that you don't migrate the whole project, I would recommend go depth first meaning pick an aggregate completely migrated or migrated as far as you want to and then pick the next aggregate. So let's get started. What do you think should be the first thing to do when migrating a project from JPA or Spring Data JPA to Spring Data JDBC? Any ideas run your chest. Well, yeah. Okay, good point. I don't have that on the slides. Um, no but specific to the migration what ia did I just talked about Aggregates and the

problem is Spring Data really always is based on Aggregates. But JPA kind of breaks that. And also for many stores, it's not that important, especially JPA. It's like nothing bad happens if you ignore that, at least not in the short run. So what you have to do is actually identify your Aggregates. And for those that know how Aggregates work in this diagram, what do you think are the aggregates? Yeah, almost actually all the light green boxes are entities, and the dark greens are the repositories. And in many cases, the entities and Aggregates are actually identical, but there's one case where this isn't the case in this example, and that's the shipment. The thought process here is like, can these things exist independently? I can imagine a shipment that doesn't have a customer. I can't really ship that probably, but I can do a lot of things. I can validate it. I can start picking that stuff. I can't just really ship it. But the relationship between shipment

and the items inside the shipment. That's like a shipment without any items is kind of useless. And items that don't belong to a shipment. What is even the meaning of that? So these are probably um one one Aggregate. And um that's something I have to to First realize for the next step, which is remove all the extra repositories that you most likely if you never thought about aggregates have in your code base. Because again, I said um an aggregate should be handled as one unit, should be persisted as one. So it doesn't make sense to have a repository for an entity that is inside an aggregate. So we have a Superfluous repository here, which is the item repository that needs to go away. And that, of course, it's easy in a diagram like this, um in code, um that's also easy, um we just delete it. If you don't notice this has like light greenish hint, which is the in my configurations of intellig, um how it displays like this thing is gone in this commit. But of course, if I have that repository, I probably used it.

um, so I need to change some places in my code. Um, in this case, um, I have this uh service method. They don't make too much sense. They are really created just to, to demonstrate the kind of issues, um, you will find in your code. Um, it accesses directly, um, an item by ID and then changes the quantity. And now I have to access that item in a different way. And again, I said in the beginning about Aggregates. Everything inside an aggregate gets only accessed through the aggregate route. And I do in this little code change the kind of a minimal version of that. I still access it from the outside, but at least I load the, um, the shipment and then find inside the shipment the correct item and then manipulate it if I want to do the full thing, um, like in the real beautiful domain-driven design, uh, style. All this logic should actually go into the shipment class, but that is kind of not necessary for the migration. So you can do that whenever it fits you, and it doesn't really appear, um, in the

slides, but it triggers another change because you now use a method in the item um, no, in the shipment repository that wasn't there before yet, so you have to create that method, which in this case is a simpler simple find uh method that you can just add. It might actually mean that you have to write custom SQL or JPQL, um, whatever it uh, it might involve that depends obviously heavily on your project, and I can't really do much of an advice here, but this is a good uh place to revisit the Mikado method because with a Mikado method, I would actually do this kind of in the reverse order. I would start, okay, I just delete the item repository, then notice, oh, that doesn't work. I first have to get rid of this invo invocation of the item method. Then when I tried to do that, I noticed, well, I need need a new method in the shipment repository again, undo all my changes, implement the method for the shipment repositories with tests, obviously, then um, refactor this method.

to use only that and no longer the item repository. And then the final step is I can actually delete the item repository. And does that sound complicated and kind of convoluted? Yes, it does. But if you work work with a code base with dozens of or hundreds of entities that might exist already for 10 or 20 years long before you Jo uh joined the project, it's helpful, trust me. The next thing to do is make all the safe statements explicit. JPA has this great feat feure, or I should say feature, that it POS it saves everything in the um in the persistence context. And that can create funny results sometimes if you're not aware of that and it um often um uh results in the effect that calling the safe method of a JPA repository isn't really necessary. One example is here um in this example. I load a product and then manipulate it and then nothing but all this runs inside a transaction. So JPA automatically possess all this stuff. Spring Data JDBC will not do that for you.

if you load an entity with Spring Data JDBC, it's totally disconnected from Spring Data JDBC. It's just a plain class, nothing special about it, not a proxy, just the class how you implemented it, and it has no way of knowing that you actually change the data and might want to persist that. So you have to add a save method. There are other cases, um, where, uh, this happens, which is when you have Cascade annotations. In this example, I have a shipment and I might create a customer, and then at the end, I only save the shipment, but the customer that I created here gets, again, due to some, um, Cascade annotations on the shipment, gets persisted as well. In order to make this work properly when we finally switch to Spring Data JDBC, we have to actually add a save, um, call over there. Can you actually see the colors of the diff like that? This is colored and this is color, kind of. I'm not able to change it, sorry, lesson learned for me. Once you have done that, you can actually get rid of all the Cascade data in your repositories.

crosses. Aggregates because again. Aggregates are kind of autonomous. If you have if you work on two Aggregates at the same times. Domain-driven design hardcores might actually consider that a smell in the first place but at least you. You shouldn't cause saving one aggregate to um have an A another aggregate saved as well. That's basically a big no no once you're here the next step I would propose is simplifying our references in jpa. It's very common to have bidirectional references meaning you have two classes A and B and a references B and B references a and and they are basically the same relationship and spring data jdbc can't do that which might be a surprise if you get started with it but the fun thing is it doesn't need it. You'll see why so if you look at our um little diagram again there are multiple places where we have these bir directional references and for each each one of those we now need to decide like which direction should they really

go first one customer to shipment and like one thing that can help deciding um which direction you should keep is what should come first. That's the one that gets referenced and normally you first have a customer before you try to ship something to them, so the shipment should reference the customer, not the other way around. The next case is within Aggregates. There, the rule is really simple: reference always go from the root to the entities contained in the aggregate, because again we always reference the root in the first place. So, what other way would be to reach all the internal stuff? And in product and category, I guess one could it do both sides, like but having categories reference products kind of feels weird to me. I'm honest. I'm not able to formulate a hard rule at this place, but I think product to category is the right way to go. And in code, this can be as simple as removing the reference, but then again you all of course have in a real-world scenario tons of places where you reference or where you use that.

reference and for those you have basically a similar process as with an item repository. Um, you need new repository methods for that. So, if somebody used to like this, this thing comes from the customer. If there was a code, uh, place where somebody navigated from customer to shipment, you now have to call the shipment repository and say, Okay, give me the shipments for this customer. New method and use the Mado method. Same process. It gets a little more complicated for M2N joints or M2N relation tables. Um, JPA normally hides them from you. Like in this diagram, there is actually an M to N relationship. Um, you might be able to guess products can belong to multiple categories. And of course, each category probably has multiple products that belong to it. So, in your database schema, there is this join table in between, but it doesn't appear in your entity classes. Spring Data JDBC needs this class explicitly. And so now you have another aggregate that actually consists of two classes. And again, in code, the first part

is well you need this um reference entity this joining entity which basically oh you can't see my pointer here which really just consists of two references marked as ID and all. The jpa annotation to have the the right column names and everything and of course everywhere where I use this I now have to use this new class product category. Once I'm at this place I have only one: M or M to n relationships and they are all non bidirectional and at this this place I now can change all these references across Aggregates and replace them with IDs. So again our model all the reference that cross aggregate boundaries that are these kind of dissolve they are semantically there but they are not Java references anymore instead of a customer I'm going to uh reference a customer ID so this is exactly what happens in this case um for the item that happens uh reference the product it now references a product ID and the this might feel like a degradation in in kind of usability of your domain model but really it gives you a clear

structure it defines your Aggregates now really and and these are boundaries where your application kind of breaks into little pieces like a bar of chocolate and the keyn note this morning we heard about modular modulus this is exactly one tool to to break these apart to have to not have a huge um modulith that has no clear structure but well a clear structure where you can can move pieces around and we did all this without using spring data jdbc in any way so you can do this or parts of this in your jpa project and decide not to use spring data jdbc and at least in my opinion it improves your source code the maintainability the understandability you you better see where are the boundaries but of course we are here and actually want to migrate to Spring data jdbc so first thing actually added to your project as a dependency and I guess most of you are using spring boot nowadays and that means you just add the spring boot starter for spring data jdbc and um that's it it like in a

simple project. It will pick up the data source and use it and live right next to JPA just fine without any problem. Of course, if you have a more complex setup, maybe multiple data sources or fun stuff like that, of course, your setup for Spring Data JDBC will be more complicated as well. One thing you probably have to do is you have to create an ID generator, one or multiple. In my little project, I used um, well, when I set up the project, I really used the simple stuff that I um could think of while making all the stuff that I consider not so smart um so I have something to show you and um it turned out um JPA used sequences but Spring Data JDBC by default expects that the database will um create the ID and return it when I insert um a data set. If I don't have that, I have to explicitly generate an ID in a listener or basically a um a call back, uh before convert call back that has a simple method. It gets um one entity of the type that is

given up there you can use object then you have to check what kind of entity you have inside the method and it just checks is this uh does this have a null ID. If that is the case, it obtains an ID using just a JDBC template and sets the ID. If you want to use different strategies to create IDs, feel free, same same principle and um do whatever you want. And if you do something interesting making an open source project, the next thing you probably have to do in a real-world project is write a bunch of converters. There's like all the basic data types get um persisted and loaded just fine, but if you have more complex stuff, you have to write converters. I didn't present a converter because well converter again basically two methods, one converting from your domain type to whatever is persistable in the database, the other one converting it back. Um, I'm not saying that it's trivial or not much work, but there's really not much I can show you. And once you have those, that you need.

for all your Aggregates, you can take an Aggregate and then actually convert it. Like replace all the map information from JPA to Spring Data JDBC. And that's the one thing that you can't really break down into smaller steps because you can't, I guess it's obviously not have an entity that is 50% JPA and 50% Spring Data JDBC. I can't even imagine how that is would be supposed to work. And um, an important thing is, um, unfold your import statements because there are quite some, uh, annotations that exist in both worlds. Like JPA has a Table annotation and um, JPA and Spring Data JDBC both have an ID annotation. And um, another example is the Query annotation exists for both, uh, modules but are different classes. And you have to replace one with the other. And there is still a lot of work. You probably have to create custom cruies, um, uh, Spring Data JPA is more feature, especially, um, regarding Cy Generation. Um, but yeah, there's like this is the part where I only have a few slides.

doesn't mean there's a little work for you to do conclusion. It's a lot of work. I don't know if that is a surprise or if anybody came here and thought like, well, they, I'm sure they have like some AI thing generating open rewrite recipes. Um, it's something I'm thinking about, but um, didn't get beyond the thinking about stage. Um, a lot of that work can be broken down into small steps, which is a good thing and an important thing. Don't try to do everything at once. That won't work and can cost you a lot of time, and time is money, quite literally. Most of the stuff is untangling structures that we are kind of. They are not really caused by JPA because I just demonstrated you can undo them while staying well within JPA world, but JPA allows them to do that, and I think that's an architectural choice, possibly mistake. Um, Fielding described architecture as the decision like what not to do, and JPA in that sense comes with very little architecture. JPA

basically says, yeah, give me your model, give me your schema, and one way or the other I'm mapping one to the other. Spring Data JDBC is way more strict in that regard. It says, I have a way to map a model to the database. And yes, you can tweak things like table and column names and stuff, and you can add converters, but there's a very strong, I'd say, concept that you have to fit in, and it gives the application a nice, clean, upright posture that is nice to look at. So if all that is too much work for you and you think, like, okay, making my application easier to understand, is it worth all that work? Maybe you have a big application with 100 entities, and in the last two years, you're really only working with this cluster of 12 entities. Well, you can decide to only use Spring Data JDBC for new stuff. You can say, okay, whenever we touch something, then we are going to migrate it to Spring Data JDBC. The two can exist in the same

project, and I'm not going to say without problem. I'd say without problem from the Spring Data JDBC design because JPA has some problems if you actually use SQL against the database. But again, we are separating our application first into Aggregates and then decide, Okay, I'm going to use Spring Data JDBC for this Aggregate and Spring Data for JPA for this Aggregate, and that should work fine without a problem. I promised a couple of links and some I didn't promise all the screenshots of the code. In this GitHub repository, there are actually two branches, like the main branch and basically a branch further below. You can say as basically set up at this Branch. Okay, I have a working JPA application, and then in small steps, I went up until I have migrated everything to Spring Data JDBC. You can play with that. Then I mentioned the Mado method a couple of times. If you do any kind of refactorings, no matter if related to Spring Data JDBC or not, do yourself a favor and get this book and read through.

it. I have actually never read the book, but I read it when it still was a PDF and available for free. Um, you probably have to pay a few bucks, but you're software developers. I think you can. You will be able to pay for that. And um, for those that are really new to Spring Data JDBC, there's an article where I try to explain this Aggregates and reference stuff. Um, that's probably helpful in understanding why we did all these things that I just explained. And with that, I'm done and open for questions if you want. [Applause]

Migrating from (Spring Data) JPA to Spring Data JDBC by Jens Schauder @ Spring I/O 2024

Spring I/O

Migrating from Spring Data JPA to Spring Data JDBC

The speaker discusses the audience's experience with JPA and Spring Data JDBC.

He emphasizes the need for a solid set of tests before starting any migration.

The speaker also advises taking small, incremental steps during the migration process to avoid breaking the entire project.

The Efficiency of the Mikado Method in Software Development

The Mikado method emphasizes making small, stable changes and continuously running tests before committing, allowing for a visual representation of the remaining tasks.

This approach provides crucial information about the feasibility of the project timeline.

Spring Data JDBC is strongly based on the concept of Aggregates from domain-driven design, ensuring transactional consistency and a controlled manipulation process.

Migrating from JPA to Spring Data JDBC: Key Steps

Identify the Aggregates in the project, which are crucial in Spring Data JDBC and may differ from JPA's approach.

Remove any unnecessary repositories for entities inside an aggregate, as each aggregate should be treated and persisted as a single unit.

Consider whether to approach the migration breadth-first or depth-first, applying the steps to each aggregate in the project for a more efficient process.

Refactoring Code to Follow Aggregate Routes

The service method is being updated to access the item within the shipment, following the aggregate route.

This code migration also requires adding a new method to the shipment repository for finding the item, and making all save statements explicit when using Spring Data JDBC to ensure proper data persistence.

This refactoring process, while complex, is beneficial when working with a long-standing codebase and transitioning to Spring Data JDBC.

Best Practices for Managing Aggregates and References in Domain-Driven Design

Aggregates should be treated as autonomous units, and saving one should not trigger the saving of another.

When dealing with bidirectional references, it's important to decide the direction based on what comes first in the relationship.

In domain-driven design, references within aggregates should always go from the root to the entities contained in the aggregate, and when dealing with a many-to-many relationship, the join table needs to be explicitly represented as an aggregate in the code.

Restructuring Aggregates and Migrating to Spring Data JDBC

A new "Product Category" joining entity is introduced, replacing the previous references and establishing clear boundaries for Aggregates.

Migrating to Spring Data JDBC from JPA requires adding the Spring Boot starter for Spring Data JDBC and may involve more complex setup for multiple data sources.

In Spring Data JDBC, the default ID generation expects the database to create and return the ID during data insertion, requiring explicit ID generation if not supported by the database.

Managing Entity IDs and Converters in Spring Data JPA and JDBC

The method checks for a null ID and obtains one using JDBC template if necessary.

In a real-world project, writing converters for complex data types is essential for persistence.

Managing import statements and replacing annotations between JPA and Spring Data JDBC is crucial when working with both modules.

The Strict Mapping Approach of Spring Data JDBC

Spring Data JDBC offers a strict way to map a model to the database, providing a clean and upright posture for the application.

It allows for coexisting with JPA, making it possible to migrate to Spring Data JDBC gradually.

The speaker also recommends a book for refactoring and provides a GitHub repository for reference in migrating from JPA to Spring Data JDBC.