DEV Community: Axelix Labs

Axelix goes GA. A journey of a thousand miles begins with a single step

Sergei Cherkasov — Tue, 11 Aug 2026 12:39:57 +0000

On behalf of the core Axelix team, and everybody who has contributed to the community, I want to declare: we finally did it.

Axelix, finally, goes GA (Generally Available)!

For those who do not know - Axelix is a product with an Open Source core, that allows you to discover the common problems, pitfalls and inefficiencies in Java applications at large scale.

We're available on GitHub (btw - give us a star!).

In this post, I want to share the story and the motivation behind the product overall. I hope you find it interesting.

The Story. Big "Why" Behind Axelix

Java is quite an interesting language and ecosystem in general. I think a lot of people will not argue that it is quite old, and it was one of the first so-called "Object-Oriented" languages, that actually gained massive adoption. It both was, and it still is the backbone of modern enterprise.

For anyone who claims that Java is dead - I recommend checking the JetBrains State of Developer Ecosystem survey or even the Stack Overflow survey for 2025 (and Stack Overflow has, sadly, become a part of history). It is clear that Java as a language and the "ecosystem" around it (including Kotlin) is still relatively popular, and it remains true.

Ecosystems around Languages

The experienced developer knows that today's ecosystems that evolve around languages are typically very diverse. For example, let's talk about JavaScript. If we decide to run JavaScript on the server, then we're probably going to work with a database of some sort. Therefore, we're also going to need a framework, a library to work with the database, e.g. an ORM (I know that we may work without it but let's leave that aside).

And in JavaScript, we have quite a lot of options:

Prisma
TypeORM
DrizzleORM
Kysely and so on.

We can pretty safely state that Prisma ORM is probably the most used ORM on JavaScript. But notice that it is far from being the definitive JavaScript ORM.

It is not like Prisma is the default choice and is by far the most popular ORM - it is just not the case. I want to emphasize - even by Prisma's own assessment of its popularity, it is not far ahead of its competitors. They are all very close. So, the way people work with the database in JavaScript may differ heavily from team-to-team.

The defining trait of Java Ecosystem

In Java, if we're going to take the same problem (working with the database), then we will quickly realize, that the industry is heavily concentrated.

We generally can state that Spring Data JPA as a solution around Hibernate occupies above 50% of all the data access solutions, let alone ORMs. I remember some time ago Josh Long, the much-loved Developer Advocate for Spring, posted a survey on X (formerly Twitter) about the data access technologies usage:

// Detect dark theme var iframe = document.getElementById('tweet-1528655715933597697-592'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1528655715933597697&theme=dark" }

We must of course acknowledge that there are fast-growing alternative solutions to JPA that are explored, such as jOOQ, but Spring Data JPA dominates the field. So, the way we work with the database in Java (at least on the server side) is relatively well-defined and revolves around Spring Data JPA.

But there is more to it, it is not just the ORMs or data-access libraries. It's something bigger.

Spring Framework as the Phenomenon

We cannot talk about Java ecosystem and not talk about Spring Framework. If we're going to look in the aforementioned Developer Ecosystem State report from JetBrains, we're going to get the following insights. I have assembled them carefully for you - share them freely as you want. Also note that the respondents had multiple choices:

Framework	Users	Share of framework users
Spring Framework	3,042	87.8%
Ktor	362	10.5%
Quarkus	287	8.3%
Other	210	6.1%
Vaadin	104	3.0%
Micronaut	95	2.7%
Grails	61	1.8%
Helidon	36	1.0%

This is (at least AFAIK) one of the most recent and most trusted data we have. Many thanks to JetBrains for publishing it.

So, yes, although other ecosystems are also growing, e.g. Quarkus along with its Quarkiverse, but they still have a very, very long way to catch up with Spring Framework. So at the end of 2025 (I wager that even today) we can safely state:

The most common Java app, which by far represents more than half of Java server side deployments is a Spring Framework app.

Again, it is just data, you can download it and check yourself.

But even if we consider different ecosystems: Spring Framework, Quarkus or Micronaut etc - we're going to quickly realize that these are not just "libraries" or "frameworks" in a traditional sense. They are themselves large frameworks that build an entire sub-ecosystem around them. For example, are you working with Data? Well, you have

Spring Data in Spring
Jakarta Data in Quarkus
Micronaut Data in Micronaut

Oh, you want to send an HTTP request? The most common thing on the backend! Well, we have:

Spring Cloud Exchange/OpenFeign in Spring
RestClients in Quarkus
Declarative HTTP Clients in Micronaut

Notice that every framework has its own solution.

In other ecosystems, e.g. in JavaScript on the server side, we may use:

ExpressJS for web server
Axios for sending requests
Prisma as an ORM

And these are all just individual choices made by the team. We may use Axios or we may use Got. We may use Prisma or we may use TypeORM. Some solutions are more popular than others, but they are all independent - they exist outside of a single umbrella, like Spring Framework, for example.

To put it simply:

In the Java world, if we have any kind of problem, most likely, we do NOT need to seek the solution on GitHub, find some fork that does what you want (which is a common JavaScript practice btw). There is almost 100% chance that Spring Framework has a solution for us already.

Why am I telling you about this?

Because it is important to understand, that since Java Ecosystem is so solidified around the Spring Framework technological stack, it often suffers the same problems in production.

What are these problems? Well, there are a lot of them. And we know all of them with our very own butts:

Our connection pool leaks
Our API endpoints are performing slow (maybe the problem is in the database?)
We accidentally expose /actuator/env in production and leak secrets
Our applications consume too much memory and start very slowly...

And so on. And the industry, throughout decades of Java experience in production, has developed a set of recommendations, best-practices, "solutions", guidelines. And these guidelines exist on different levels of the application, e.g:

Guidelines for Hibernate/ORM

and so on. Guidelines for Spring performance:

Disable OSIV
Use Spring Test Profiler! (many thanks to Philip Riecks for such a tool)
Use Spring smart context caching! (Sergey Chernov, a highly experienced Engineer and a buddy of mine, developed the tool)!
Do not set spring.jpa.show-sql=true or other dangerous properties in production!

and so on. Guidelines for even our beloved Java!

For Christ’s sake, use Project Leyden!
Use Compact Object Headers (Project Lilliput)
Configure the logging of GC in production!

And so on and on and on. Because we have that solidified ecosystem we generally know "what is right and what is wrong". And for the long time there was no such tool.

But we thought that this is wrong. And we probably should have one. And this tool is called Axelix (The source code).

In 1.0.0, we do not support the detection of all the issues that I outlined above (most, but not all). And the above is just an example. There is a lot (really, a lot) of knowledge that we as a Java community have accumulated throughout these years that we're going to put inside Axelix, so it can serve you well.

I hope, at that point, the motivation behind the tool is clear, and now, I want to answer a couple of questions that we already have received many times over during Milestones.

Q: Is it free?

Yes, it is. We're going to follow the Open Core model. This is the Open Source software development model that underpins projects that we all love and care about:

Grafana
Keycloak
Vaadin

And so on. It is generally considered to be the most reliable model for the OSS development, and that is why industry leaders choose, and that is why we choose it.

Q: Is the project ready for use and deploy?

Yes, it is ready for use free of charge. We have processed the feedback from literally tens of teams that have installed Axelix milestone releases and shared their insights with us.

Q: Is it safe to deploy in production?

It is designed for production, so the answer is yes. But since this is the first 1.0.0 GA release, the general recommendation is to first install it on development environments, and then for production.

That said, we do have teams that deployed Axelix in production already to get insights about their @Transactional methods behavior and properties resolution.

Bottom Line: The core stays Open Source always, and it always will be free of charge, and it already provides value for the teams.

Where Are We Headed?

The team behind Axelix has many years of experience writing and optimizing Spring Boot applications. We have a lot of work to do ahead of us, and we still have a lot of things to incorporate into Axelix.

For those who want to know how the project is installed & configured, please, visit our website and also our documentation. In case of any questions or difficulties, you can always reach out to the team at: hello@axelix.io We, the maintainers, are happy to answer your questions and assist you during the installation.

We're also going to stay committed to Open Source, and committed to our values, which are making sure that your Java applications are as secure, performant and efficient as they can be.

Thank you all. Mikhail.

Taming Hibernate in Tests

Sergei Cherkasov — Sat, 08 Aug 2026 07:51:22 +0000

Hi everyone! This is Mikhail Polivakha, the technical lead of the Open Source Axelix project (a project dedicated to helping you identify common problems in Java server-side applications, including while working with Hibernate).

In this article, I want to address the question that I think is pretty common amongst the advanced Hibernate users:

"Is there a verify Hibernate behavior in tests (like Junit for example)?"

Here it's really important not to hand you a "fish", but to teach you how to fish - that is, to give you a framework of what's worth keeping in mind when working with Hibernate.

Controlling Hibernate during tests. Overview.

If I asked you: guys, which problems in Hibernate annoy you the most? You'd mention things like the sneaky N + 1, In Memory Pagination (when explicitly specifying setMaxResult or a Pageable), a Cartesian Product loaded into the application's memory, or, say, some baffling swarm of SELECTs followed by UPDATEs/DELETEs under the hood, and so on.

Everything I listed above, and really all "problems" with Hibernate, can be split into 2 categories. Let's break them down.

1. Problems at the ORM level

There are situations that both we (the end users) and Hibernate identify as problems. For example, up until Hibernate 7.4, the query below would perform pagination entirely in memory. This is fairly well known:

@Transactional
@Query(
    value = "SELECT o FROM Owner o JOIN FETCH o.pets",
    countQuery = "SELECT COUNT(o) FROM Owner o")
Page<Owner> findAllWithPets(Pageable pageable);

In version 7.4 Hibernate learned to do pagination within a sub-select. But nevertheless, if you, for example, work on Spring Boot 3, you have Hibernate 6, and in the case of queries like the one above there will be a warning in stdout:

HHH90003004: firstResult/maxResults specified with collection fetch; applying in memory

And it's there because Hibernate itself understands that its actions may blow up your heap. There's even a property that we at Axelix recommend setting for new microservices that don't use 7.4 yet (and there are still many of those):

spring.jpa.properties.hibernate.query.fail_on_pagination_over_collection_fetch=true

If you set it, Hibernate will simply throw an exception where it would previously do In Memory Pagination.

In short, what I want to say is that the problem above is understood by Hibernate as a real problem. It recognizes and admits it. That's one layer of problems.

But oddly enough, these are quite hard to track. Hibernate rarely provides any means to hook into it (although there are some nuances, read below). For instance, at Axelix, to detect In Memory Pagination (if it happens), we simply literally catch an ILoggingEvent and inspect the code within it. Because there are no other acceptable ways (at least none that we're aware of)!

2. Second. Problems at the application level

There's a conceptually different layer of problems. N + 1, for example, belongs to it.

Let's think for a second: what is N + 1?. Try right now, without looking anywhere, to clearly formulate the definition in your head. Done? Here's how I'd formulate it (informally):

It's a situation in which you iterate over a collection loaded by Hibernate, sequentially accessing some lazy field within each individual entity of the collection, thereby triggering "N" additional SELECT queries.

That is, if you think about it a little, it becomes obvious that for Hibernate this is just Lazy Loading. The notion of N + 1 as a problem exists at the application level, not at the ORM level. That is, the problem is not lazy loading itself, but the semantics of lazy loading (what does this particular lazy loading mean? Is it just lazy loading, or lazy loading within an N + 1?).

In such a situation it's obviously pointless to rely on Hibernate, since the N + 1 phenomenon happens at the application level, and the ORM is completely unaware of it — it's not its area of responsibility. You can't get by without fairly strong tooling around Hibernate. Can it be written, and if so, how?

If we're talking specifically about N + 1, then the answer is generally - yes, you can, and we did it at Axelix in Open Source. Let me tell you how exactly we did it. The source code is open, take a look if you're interested.

The General Approach to N + 1 Detection

Hibernate doesn't know what N + 1 is, but it does know what a Lazy Loading association is, and that moment can already be caught. For example, here's how we do it in NPlusOneCollectionLoadListener:

    @Override
    public void onInitializeCollection(InitializeCollectionEvent event) {
        try {
            PersistentCollection persistentCollection = event.getCollection();
            EventSource eventSource = event.getSession();
            CollectionPersister collectionPersister = eventSource
                    .getPersistenceContextInternal()
                    .getCollectionEntry(persistentCollection)
                    .getLoadedPersister();

            LazyLoadingTarget lazyLoadingTarget = parseLazyLoadingTarget(collectionPersister.getRole());

            if (lazyLoadingTarget != null) {
                transactionAccessor.recordLazyLoading(lazyLoadingTarget);
            }
        } catch (Exception ignored) {
        }
    }

    // The general "role" format is expected to look like this: com.example.Order.items
    public static @Nullable LazyLoadingTarget parseLazyLoadingTarget(String role) {
        try {
            int separatorIndex = role.lastIndexOf(".");
            Class<?> ownerEntityClass = Class.forName(role.substring(0, separatorIndex));
            String propertyName = role.substring(separatorIndex + 1);
            return new LazyLoadingTarget(ownerEntityClass, propertyName);
        } catch (ClassNotFoundException | IndexOutOfBoundsException e) {
            log.warn(
                    "Unexpected propertyPath format '{}'. Axelix cannot recognize that, so lazy loading and potential N + 1 is not going to be tracked for this property",
                    role);
            return null; // it means that the role format is not the one that we expect
        }
    }

Here, through a series of manipulations, we can figure out which association was loaded lazily and on which collection. What do we then do with this information?

Axelix, for example, currently makes the following decision: If we noticed that within a transaction there were several lazy loadings of the same association, then we consider this to be an N + 1.

Is that always correct? Well, this is debatable, because, for instance, in this code example, if we assume that Order.items were loaded lazily — we, seemingly, don't have an N + 1:

public void compareOrders(Long previousId, Long currentId) {
    var previous = orderRepository.findById(previousId).orElseThrow();
    var current = orderRepository.findById(currentId).orElseThrow();

    // Two lazy accesses to Order.items, but there's no collection of orders here -
    // we're just comparing two specific versions of the same order
    if (previous.getItems().size() != current.getItems().size()) {
        throw new IllegalStateException("The order contents have changed");
    }
}

Or do we? And what if I change this example to something like this:

public void compareOrders(Long previousId, Long currentId) {
    var orders = orderRepository.findAllById(List.of(previousId, currentId));

    var previous = orders.get(0);
    // Exactly the same comparison as above, but now within an iteration
    // over a loaded collection of orders: at each step there's again a lazy
    // access to Order.items on both previous and current
    for (var current : orders) {
        if (previous.getItems().size() != current.getItems().size()) {
            throw new IllegalStateException("The order contents have changed");
        }
        previous = current;
    }
}

Does it look like N + 1 now? It does.

So, in short, what I want to say is that here you need to clearly fix the definition of N + 1 at the application level. We at Axelix deliberately decided that this case is nonetheless worth treating as an N + 1, so, in the UI, it will be reported to you:

P.S: Among other things, there's a small nuance here: N + 1, strictly speaking, can also happen without an open transaction when OSIV is enabled. That's a separate case which we're not considering for now, since it would complicate the picture.

Micro-Conclusion

I'd like to draw a small micro-conclusion here. In general, detecting some complex phenomena that occur at the application level while working with Hibernate:

N + 1
Blocking calls inside transactions, and so on.

This can be done. It just requires you to write a fairly large and non-trivial amount of tooling. Using N + 1 as an example, I hope you've roughly understood what such things will look like.

General Hibernate Problems

As a separate section, I'd like to address general Hibernate problems. Quite often people have some conditional hot-path for saving or updating data. And devs simply want to make sure that
Hibernate doesn't "sabotage" the entire process undercover. Sounds familiar, right?

Here you need to take a step back and ask: and what do we mean by "sabotage"?

Having talked with people, we'll discover that most often people want roughly the following: to have confidence that a person wrote repository.save(), and that it will execute specifically an INSERT into the table and nothing more.

For example, having this piece of code:

@Service
public class OwnerService {

    private final OwnerRepository ownerRepository;

    public OwnerService(OwnerRepository ownerRepository) {
        this.ownerRepository = ownerRepository;
    }

    @Transactional
    public Owner registerOwner(String firstName, String lastName) {
        var owner = new Owner(firstName, lastName);
        return ownerRepository.save(owner);
    }
}

The person wants to be sure that there won't be any hidden SELECTs and so on there. I think some people recognized themselves. Can this be done?

The answer: generally yes, it can. Hibernate has a Statistics API, which on the one hand isn't part of the JPA standard, and on the other hand can give us some details about query execution within a session. For example, for the code above you can write a test like this:

// Requires hibernate.generate_statistics=true
@SpringBootTest
class OwnerServiceTest {

    @Autowired
    private OwnerService ownerService;

    @Autowired
    private EntityManagerFactory entityManagerFactory;

    @Test
    @Transactional
    void registerOwner_issuesExactlyOneInsert() {
        // given
        Statistics statistics = entityManagerFactory
                .unwrap(SessionFactory.class)
                .getStatistics();
        statistics.clear();

        // when
        ownerService.registerOwner("John", "Doe");

        // then
        assertThat(statistics.getEntityInsertCount()).isEqualTo(1);
        assertThat(statistics.getEntityUpdateCount()).isZero();
        assertThat(statistics.getEntityDeleteCount()).isZero();
    }
}

This API lets you verify that only one INSERT was executed within the method. It works based on the fact that in the test I opened a transaction (Spring Boot Test of course recognizes this and opens a transaction that will have to roll back at the end),
thereby opening a Hibernate Session - this is the default behavior, so I think there are no surprises here.

Since the Statistics API collects statistics at the SessionFactory level, not at the level of individual Sessions, in each test we have to access the SessionFactory in order to first clear all its statistics.
And only then can we make the checks we're interested in (Strictly speaking, some telemetry is also collected at the Session level, but it's rather scarce and in practice can help you little).

Overall, the telemetry collected (the number of INSERT, UPDATE, DELETE statements, and so on) will be enough for you to make some basic checks.

Conclusions

In practice, the answer to the question:

"Is there a verify Hibernate behavior in tests (like Junit for example)?"

Strongly depends on what exactly you want to detect. Some tooling can be written — for example, Axelix can detect both In Memory Pagination, and N + 1, and a number of other problems. In some situations tests will help you a lot.
In general, first of all it's better to ask yourself — what problem exactly are we trying to solve here. And only then build a solution: is it possible (considering what I wrote above) to write an effective test,
is it possible to delegate this to external tooling, or maybe (the ideal case) the problem doesn't need to be solved in the first place.

Best of luck to everyone!

Natural IDs in your database. I am telling you the last time!

Mikhail Polivakha — Fri, 24 Jul 2026 10:42:21 +0000

Hi everyone! This is Mikhail Polivakha, tech lead of the Axelix project (btw, give us a star!). In my experience consulting teams that build enterprise applications, I keep getting asked:

What about natural keys in the database? Say I have a column that lets me explicitly identify a record, should I use it as the Primary Key?

And over my years of designing enterprise systems, and over the time spent designing Axelix, I've come to a conclusion: just never use natural keys, ever. When you feel the urge to do it, step outside, take a walk, get some fresh air, and it'll pass.

I understand this answer is categorical, so I'll add a couple of clarifications about what to do if you do happen to have a unique discriminating column that, as it seems to you, lets you uniquely identify a record in a database table. The full, nuanced answer is of course more complicated, but if I have to give you a straight TL;DR:

When designing new systems, in my opinion, you should always use surrogate primary keys.

Now let's get into why I think so.

Rules Written in Blood

Rules like the one above are usually born out of getting burned on real projects several times. I have an absolutely perfect story straight from Open Source Axelix. The source code is on GitHub, so if you feel like it, go and check for yourself. I won't go too deep into the details, but so that you grasp the depth of the problem, I'll give you a bit of context. In some places I'll also deliberately simplify the parts I consider non-essential to understanding the problem.

At its core, Axelix consists of two components. The first is Master, a standalone application that acts as the "brain" of the system. It's deployed either in a K8S cluster, or launched as a separate Docker container, or even just run as a plain JAR.

Master aggregates information from your Spring Boot services and stores it in its database. This information is later used to understand the "maturity" of your ecosystem, the distribution of versions of key components (for example, Spring Boot or Java versions), tracking known tech-debt issues, and so on.

If we picture a typical company, they usually have a K8S/OpenShift cluster where their production runs. Almost always, a given application is deployed to production not as a single copy, but as a set of Instances (a K8S Deployment + a configured HPA, and so on). So in practice we have one logical application that is physically a set of different containers.

Now I think we have enough context to discuss the problem.

The Beginning. Natural Keys: Sure, Why Not!

As I said, Axelix stores data in its database to understand the overall state of your application. Let's call this table "Application" (in reality this abstraction is named differently in Axelix, but again, I'm simplifying heavily). This is where application-level data lives.

Master can collect data from Spring Boot microservices via both a push and a pull model, but regardless of the model, it collects data at the Instance level, not at the Application level, i.e. not for the whole application. So Master polls each Instance, and it's then Master's job to somehow figure out that all those Instances belong to the same application.

The question is: How is Master supposed to do that?

How does it figure out that these Instances belong to the same application? (Don't forget: Axelix isn't always deployed in K8S. Relying on ClusterIP services and the like is not an option.)

Actually, if you think about it a little, the solution is right on the surface: we can just aggregate information at the level of the GroupID/ArtifactID pair from the GAV coordinates (the standard format of a Maven distribution). After all, all the Instances are required to have the same GroupID/ArtifactID, right?

Broadly speaking, yes, that's true. Some might think we could key off other things, for example spring.application.name or similar, but unfortunately that won't work, for a number of reasons. That's another story, though, and it's not important right now.

So imagine we're designing such a relation in the database. Here's my question for you: what primary key would you want for a table like this? When we designed the "Application" entity, it seemed right to make the {groupId/artifactId} pair the primary key, i.e. a Natural Composite Key.

And it's so convenient! When information about some Instance arrives in Axelix Master (whether via the push or the pull model):

We can update the data with a simple ANSI SQL MERGE or INSERT ... ON CONFLICT DO ..., because artifactId/groupId is the primary key! Spring Data JDBC (which we use as the ORM in Axelix Master) in 4.1 finally learned how to do UPSERTs on the primary key, and now we can just do this via JdbcAggregateTemplate:

@Transactional
public void reloadCurrentState(BasicRegistrationMetadata metadata) {

    Application application = converter.currentSnapshot(metadata);

    jdbcAggregateTemplate.upsert(application);
}

And how nicely it works out for the front-end! And here we arrive at the fact that a natural key carries business meaning by itself! That, by the way, is one of the genuinely nice properties of natural keys. What do I mean? For example, in a situation where we just need to display the name of our "Application", and the name alone is enough, we can use the artifactId, i.e. a part of the composite natural key. No need to "fetch anything extra", and so on.

So where's the problem? Given everything I've said so far, is this problem really so critical that I claim you shouldn't use natural keys at all? Yes, it's that serious. And here's why.

So What's the Deal? A Bit of Philosophy

The older a person gets, the more prone they are to doubting various things (for example, my claim in this article! And that's okay!). This is because people accumulate experience.

People who have been doing engineering for a good while accumulate experience and come to understand just how much everything changes, and how much they still don't know (experienced engineers understand me 100% right now). A vendor comes and goes. So does an employee. The uniqueness of a natural key...

Ray Dalio (an amazing person and macro investor, I highly recommend reading him) wrote in his book "Principles":

Sincerely believe that you might not know the best possible path and recognize that your ability to deal well with "not knowing" is more important than whatever it is you do know.

This is incredible wisdom. The idea is to accept the fact that your knowledge of the outside world is limited, and it will always be many times smaller than the set of things you don't know but which nonetheless affect your life/system/etc. And the most important thing in such a situation is to be able to work WITH YOUR OWN NOT-KNOWING of something, to hedge risks.

How does this relate to natural keys?

Very simply: if some discriminator seems like an obvious key in the moment, just remember that the scope of your knowledge is incomparably small next to what you don't know. And that "invariant" you're pinning your hopes on, the one you think will be unique: it can very easily stop being unique half a year later.

What's more, the scope of your knowledge will keep growing. Over time, you (yes, you, my friend) grow as an engineer. After a while you'll look at this code, or at the design of this system, and say:

How on earth!? How could I have done this? This crap is just awful, it was obvious this key would break uniqueness in case X!

And it'll be obvious to you. But later. When you become wiser. By the way, if you don't have these moments of "enlightenment" in your career, where you scold yourself for your own past decisions, that's a very strong warning sign that you've stopped growing as a specialist.

Back to Engineering

Let's get back a bit closer to the technical side.

The main point of the previous section is that what seems like the uniqueness of a natural key today can easily stop being uniqueness later. Now let's think like engineers: how bad is that, really? How bad is it that we'll be wrong about our natural key (composite or not, doesn't matter right now) turning out not to be unique?

The truth is that a record's primary key must always (!) have (among others) the following two distinguishing properties:

1. It must be immutable

When we assign a record some key by which we identify it, we then have no right to change it. Why? Because the outside world that depends on our system stores exactly this ID, this primary key, to identify the record. It stores a reference, not the record itself.

For example, imagine you have a third-party service that stores user profiles: user-service. And there they decided to use email as the natural key. You write a service that orchestrates users' subscriptions to various services within the ecosystem. And now you need to fetch a user's profile from that user-service system for your operations. How will you fetch it? By email, of course! It's the "unique key", after all.

And now imagine that the Product Owner comes along and says:

In our service we want to let a user change the email tied to their account.

That is, effectively, an already-existing record in the database will have its identity changed. By changing a record's ID in this user-service, any other system, including yours, can no longer find the profile it needs. That would be a mass incident. That's why an ID must be immutable always.

2. It must uniquely identify a record at any moment in time

Now imagine that, all of a sudden, the folks from the team that develops user-service get a requirement. They're told:

Hey, we sometimes run into a situation where a user once created an account and tied their email to it. And now they want to somehow delete the old account (which they created some 10 years ago) and create a new one, and attach the same email to it. We wouldn't want to delete the old account (in enterprise, for various reasons, hard deletes are rarely done). So, shall we do it?

Here the problem is even more obvious. Not only can your system, which depends on user-service, no longer find the right user profile (there could be several of them now!), all existing contracts break, and to "fix" them you'll have to "re-define" the ID (it's no longer unique, and you can't rely on the ID alone anymore). And if we have to change the ID, then see the section above.

Cause of Death: Natural Id

Mistakes come in varying degrees of severity. There are mistakes that have a local effect and can be fixed relatively quickly and easily.

But keys that identify data in distributed systems are something that spreads across the entire distributed system into its most varied corners. So the moment you suddenly realize with horror that the natural id is no longer unique, the so-called blast radius will be fantastic. Especially in modern microservice architecture.

So, friends, people die of different causes. Someone died of cancer, someone died of heart failure. And someone simply chose a Natural Id as their primary key, and then received an email in their inbox, or suddenly heard at a daily standup that the uniqueness assumption of this key was about to be shaken.

I suggest a moment of silence before reading on, in memory of those engineers who paid the price for choosing Natural ID as their primary key…

Thank you.

The Axelix Case

Let's get back to the real case we had at Axelix.

We haven't hit GA yet (it'll ship this summer, 2026, we're actively working on it), but we already have several Milestone releases. We embed with various companies to gather feedback, potential bugs, problems, and so on.

And one company tells us:

You know, it just so happens that we essentially have two services: service A and service B. They're basically identical, just deployed in different network segments. They have the same groupId and artifactId. Nevertheless, service A is maintained by this team, and service B by that team.

I've simplified all the details, but this is the general message. So, we have a problem in this case - we can no longer identify an application the way we wanted, via the artifactId/groupId pair. This is exactly what typically
happens after a while, when the system is already deployed in production.

Remember Ray Dalio!

... What exists within the area of "not knowing" is so much greater and more exciting than anything any one of us knows.

It's precisely because of situation like this that you need to ask users to provide Axelix with the information about what the unique ID of a given application is themselves (for example, in application.yaml).

But Natural IDs Do Have Advantages...

In my experience, the fact that a Natural ID carries business meaning that can be used somewhere (for example, displaying an application's name on the UI as the artifactId, as I already showed with the Axelix example) - this is solved simply by designing your API.

In other words, even with surrogate keys, you can design your API so that you don't have to fetch extra data from the backend; it's not a big problem (for example, get some metadata, put it into the state manager on the front-end, and so on; there are plenty of ways).

What's really important about natural keys is that they force you to think about the invariants of your data. That is, for example, logically, if your email is unique, then it makes sense to create an index on it (which is, for instance, what Postgres does when you ask it to create a Primary Key). And to avoid having two different indexes, why not make email the primary key, since in that case there would be just one index, only on email?

That's a broadly valid argument, but I'll put it this way: it's not worth it. If you don't use email as a Natural ID, then whether or not to create a unique index on email is a decision to make case by case. I'd say that for 95%+ of cases the answer is definitely yes, and there won't be any problems with it. That said, for large write-heavy systems with a lot of data, this may create a certain overhead, but again, usually negligible at the scale of the system.

And finally, regarding MERGE / INSERT ON CONFLICT operations. You can perfectly well do them not on the primary key, but on any constraint, for example, on a UNIQUE constraint that you explicitly define in a migration.

Conclusions

Based on my experience, I can tell you one thing: remember that the scope of your not-knowing is by nature far larger than the scope of your "knowing". That's why it's very dangerous to build an assumption that a Natural ID, which seems unique to you for a given record in the moment, will make a good Primary Key.

That said, it's worth acknowledging that the main advantage of a Natural ID is that it forces you to think about what invariants your data has in general. And these invariants should give you insights into how to model your data access and storage patterns, for example, defining unique b+tree indexes for the email column.

Remember: indexes and things like that can later be removed without consequences for the whole system. Changing primary keys, on the other hand, is a dead end.