o o o-o o--o
|\ /| | \ | |
| O | o-o o-o o-o o o o-o o o | O O--o
| | |-' | | | | | | | | / | |
o o o-o o o-o o--o o o--O o-o o--o
|
o--o
We're on Maven Central! com.github.mercurydb:mercurydb
A non-persistent single-schema main-memory database, written in Java.
For the most up-to-date documentation, see the MercuryDB Wiki.
See our Changelog.
The goal is to provide a framework and interface for developers to interact with objects in their program through concepts and vocabulary inspired by a traditional, persistent NoSQL database, without having to configure and maintain a database solution, which is typically heavy-weight and difficult to deploy and maintain. With MercuryDB, a developer gains all the benefits of interacting with data in their programs without any of the complexity of maintaining a persistent datastore.
Additionally, applications which are built using MercuryDB are fully self-contained and do not require a database deployment or any similar setup on the client-side, thus opening up a lot of possibilities for developers who are looking to do complicated operations on data within their applications which would normally require a database.
There is one example in the weborders folder with a set of small tests. This project is built using Gradle. You can build HgDB and the example project by running gradle build from the root. You can test the example project by running gradle test inside the weborders project folder. The build.gradle file for the weborders example project can serve as a template for building other projects.
When developing Java applications, developers typically make use of a number of Java packages which are developed and maintained by a third party (which may be the same as the application developer). These packages are called dependencies of a Java application, and for the purposes of MercuryDB will be referred to as source packages.
As you are developing your application and you realize that you need the functionality offered by MercuryDB, adding it into your project will require some modifications to your build process and source code, but we intend to keep these as minimal as possible. These modifications are described below.
MercuryDB is provided to developers as an application, hgdb, which, given a source package, produces a mercury package (a modified version of the source package), and a mercury schema, which provides the API for interacting with objects from that package as database objects.
As part of the build process for an application using MercuryDB, hgdb produces mercury packages which have an altered namespace to prevent linking against the source package when a developer intends to link against the mercury package instead. The developer will have to update the relevant namespaces as described below in order to take advantage of the new functionality offered by MercuryDB.
A schema is produced by MercuryDB after running hgdb on a package and producing a mercury package. In practice this schema is a separate library which defines the API that can be used to interact with objects in the mercury package.
A library source package is typically given a namespace like com.developer.library. Main is the executable Java file responsible for the creation of the files in an HgDB database.
In order to interact with the database functionality provided by the modifications to the packages, we also provide an API in the namespace:
org.mercurydb.queryutils
Because MercuryDB performs static code generation based on the contents of a source package we benefit from a static schema -- that is, a schema which does not change during the runtime of an application. With a static schema we can highly optimize operations on objects (which function like rows in a database table) in a way that a traditional database can not do.
Because the database remains fully resident in memory while the application is running, we never have to go to disk to query objects in the database. This makes MercuryDB orders of magnitude faster than traditional databases whose objects remain resident on disk.
Unfortunately, not all libraries may be compatible with MercuryDB as written. We assume a certain code structure and some restrictions on how classes must be written in order to benefit from MercuryDB's features and achieve full correctness.
For instance, in order for database updates to propagate correctly, all fields which are intended to be queried against must be made public strictly through the use of public getters and setters, such that the return value of a getter is exactly what was changed by the corresponding setter. Additionally, all fields set by a constructor which are exposed as queryable fields must be set using these setters rather than setting the fields directly with this.
For open-source libraries, we will be able to patch and maintain modifications to their source code in order to make them compatible with MercuryDB, however for commercial libraries without source code available, this may be much more difficult. We are currently working on ways around these limitations and input from the community is welcome.
In a certain context, you can think of MercuryDB as a kind of jQuery for Java applications, where all objects created in the application are like the HTML entities on a web page. You can query objects by their properties and operate on them, just as you would do with JavaScript on a web page.
Given .class files, we use a utility library called javassist to update the class files and make certain kinds of changes. Not all modifications to the bytecode are possible, but one thing we really count on is inserting instructions at the beginning and end of methods and constructors.
See our wiki on GitHub to find out more about the technical workings of MercuryDB.