Permazen is a ground-up rethink of Java persistence. It has been in production use in commercial software since 2015.
Permazen is:
Got five minutes? Read Persistence Programming: Are We Doing This Right? in the Jan/Feb 2022 issue of ACM Queue magazine for an overview of the Permazen “story”.
Persistence is central to most applications. But there are many challenges involved in persistence programming that lie outside of the domain of simply storing the data.
Mainstream Java solutions such as JDBC, JPA and JDO were designed simply to give Java programmers access to existing database functionality. They address the “storage” problem, but leave many other important issues that are inherent to persistence programming poorly addressed, or not addressed at all.
Permazen is a completely different way of looking at persistence programming. Instead of starting from the storage technology side, it starts from the programming language side, asking the simple question, “What are the issues that are inherent to persistence programming, regardless of programming language or database storage technology, and how can they be addressed at the language level in the simplest, most correct, and most language-natural way?”
With Permazen, not only are many issues inherent to persistence programming solved more easily and naturally than before, but also many issues that traditional solutions don’t address at all are solved, and some entirely new, useful functionality is added.
Permazen was inspired by years of frustration with existing persistence solutions, in particular JPA. Compared to using JPA, building an application with Permazen is a refreshingly straightforward experience.
Ask these questions of your persistence solution:
Permazen attempts to address all of these issues. It does so by treating the database as just a sorted key/value store and implementing everything else in Java:
Permazen also adds several new features that traditional databases don’t provide. For example, you can define your own basic types and then index them however you want.
Permazen redefines the “line of demarcation” between a Java application and its supporting database. However, this has some implications:
For an equivalent query, Permazen will perform more frequent, but smaller, database accesses. As a result, in situations where the code and the data are separated by a high latency network, Permazen will probably be too slow. Permazen is best suited for scenarios where the code and the data are running on the same machine or in close proximity.
You have to learn something new. Persistence programming with Permazen requires a different way of thinking. For example, a “DAO” layer is often no longer necessary, and you may have to think harder about how to query your data efficiently, instead of crossing your fingers and hoping the database figures it out for you, because there is no query planner (you are the query planner).
More flexible type hiearchies are possible, but it’s also easy to make a mess. JPA has support for class inheritance and only partial support for generics. Permazen supports interface inheritance (including Java’s equivalent of “mix-ins”) and fully supports generic types. The restrictions imposed by JPA tend to force model classes to stay simpler. With Permazen, implementing an interface (directly or indirectly) can mean that a model class inherits a bunch of new persistent fields.
Key/Value Layer
KVStore
- A thing that contains key/value pairsKVDatabase
- A thing that persists key/value pairsKVTransaction
- A transaction for a KVDatabase
RaftKVDatabase
- A distributed KVDatabase
based on the Raft consensus algorithm.Java Layer
Permazen
- A Permazen database instancePermazenTransaction
- A Permazen database transactionFieldType
- How all simple database types are definedPermazenObject
- Interface implemented by runtime-generated concrete model classes@PermazenType
- Annotation identifying your database classes@PermazenField
- Annotation configuring your database fieldsOther
@OnChange
- How change notifications are deliveredReferencePath
- Describes a path between objects that hops through one or more forward and/or inverse references@OnVersionChange
- How schema update “fixups” are definedPermazenObjectHttpMessageConverter
- For sending/receiving versioned graphs of objects over the network using SpringSee LAYOUT.md
.
Persistence Programming: Are We Doing This Right? appears in the Jan/Feb 2022 issue of ACM Queue magazine. This gives a good overview of how Permazen tries to improve the persistence programming experience.
For a quick overview, check out these slides from a JSimpleDB talk at a local Java user’s group (Permazen was previously named JSimpleDB).
For a deeper understanding of the motivation and design decisions behind Permazen, read Permazen: Language-Driven Persistence for Java.
Abstract:
Most software applications require durable persistence of data. From a programmer’s point of view, persistence has its own set of inherent issues, e.g., how to manage schema changes, yet such issues are rarely addressed in the programming language itself. Instead, how we program for persistence has traditionally been driven by the storage technology side, resulting in incomplete and/or technology-specific support for managing those issues.
In Java, the mainstream solution for basic persistence is the Java Persistence API (JPA). While popular, it also measures poorly on how well it addresses many of these inherent issues. We identify several examples, and generalize them into criteria for evaluating how well any solution serves the programmer’s persistence needs, in any language. We introduce Permazen, a persistence layer for ordered key/value stores that, by integrating the data encoding, query, and indexing functions, provides a more complete, type-safe, and language-driven framework for managing persistence in Java, and addresses all of the issues we identify.
Permazen is available from [Maven Central](http://search.maven.org/#search | ga | 1 | g%3Aio.permazen): |
<dependency>
<groupId>io.permazen</groupId>
<artifactId>permazen-main</artifactId>
</dependency>
You should also add the key/value store module(s) for whatever key/value store(s) you want to use, e.g.:
<dependency>
<groupId>io.permazen</groupId>
<artifactId>permazen-kv-sqlite</artifactId>
</dependency>
There is a [demo distribution ZIP file](http://search.maven.org/#search | ga | 1 | permazen-demo) that lets you play with the Permazen command line and GUI, using a simple database of the solar system. |
Documentation and links: