Nitrite: How to Create an Embedded Database for Java and Android

Nitrite is an open-source NoSQL embedded document database for Java/Android with a MongoDB-like API. An introductory article about Nitrite has been published here. This article is the continuation of the previous one. Here, we will discuss various ways of initializing a Nitrite database.

Create/Open Database

A Nitrite database can only be created and opened by the NitriteBuilder utility using a fluent API.

NitriteBuilder builder = Nitrite.builder();

Once a database is opened, it acquires an exclusive lock on the data file. So, if a database is opened in a process, further attempts to open it from another process will fail. The proper closing of a database will release the file lock.

File-Based Database

If a file path is provided and the file does not exist, builder will create a new file-based database. If the file exists, the builder will try to open the existing database.

Nitrite db = Nitrite.builder()
        .filePath("/tmp/test.db")
        .openOrCreate();

Note: If the existing database file is corrupted while opening, Nitrite will try to recover from it by restoring the last known good version.

In-Memory Database

Nitrite also supports in-memory database. Creating is very easy. If no file path is provided, the builder will create an in-memory database.

Nitrite db = Nitrite.builder()
        .openOrCreate();

AutoCommit

By default, autocommit is enabled in Nitrite. If the unsaved changes exceed a predefined but configurable limit, it will flush the data to the disk. This behavior can be disabled while opening the database.

Nitrite db = Nitrite.builder()
        .filePath("/tmp/test.db")
        .disableAutoCommit()
        .openOrCreate();

If autocommit is not disabled, Nitrite will commit the changes if the size of unsaved changes is more than the write buffer size. By default, the buffer size is 1024 KB. But it can be customized also from builder.

Nitrite db = Nitrite.builder()
        .filePath("/tmp/test.db")
        .autoCommitBufferSize(2048) // size is 2048 KB now
        .openOrCreate();

AutoCompaction

Nitrite by default compacts the database file before close. If compaction is enabled, chunks will be moved next to each other. Disabling compaction will increase the performance during database closing.

Nitrite db = Nitrite.builder()
        .filePath("/tmp/test.db")
        .disableAutoCompact()
        .openOrCreate();

Readonly Mode

The builder can also open a database in readonly mode. While opened in readonly mode, Nitrite will not persist any changes.

Nitrite db = Nitrite.builder()
        .filePath("/tmp/test.db")
        .readOnly()
        .openOrCreate();

Note: While opened in readonly mode, options like autoCommitBufferSize(size), compressed() or disableAutoCommit() do not have any effect.

Compression

A Nitrite database can be compressed while saving the changes to the disk. The compression algorithm nitrite uses is LZF. This will save about 50% of the disk space, but it will slow down read and write operations slightly.

Nitrite db = Nitrite.builder()
        .filePath("/tmp/test.db")
        .compressed()
        .openOrCreate();

Security

A Nitrite database can be secured using a username/password pair. The username and password can be set only once while creating the database. Nitrite does not store raw password, so retrieval or change of password is not possible. Adding a new username password pair is also not possible for existing database.

Nitrite db = Nitrite.builder()
        .filePath("/tmp/test.db")
        .openOrCreate("username", "password");

Note: Nitrite does not support access control.

Other Options

Specify a Custom Full-Text Engine

Nitrite supports full-text indexing. Nitrite has its own full-text indexing engine, but there is a provision to supply third-party full-text engine implementation like Lucene.

Nitrite db = Nitrite.builder()
        .filePath("/tmp/test.db")
        .textIndexingService(new MyTextIndexingEngine())
        .openOrCreate();

Specify a Custom Text-Tokenizer

Nitrite’s own full-text index engine is for the English language only. But if anyone wants to use the same engine for languages other than English, a custom TextTokenizer implementation of that language should be configured in the builder.

Nitrite db = Nitrite.builder()
        .filePath("/tmp/test.db")
        .textTokenizer(new MyBengaliTextTokenizer())
        .openOrCreate();

Shutdown Hook

While opening the database, Nitrite registers itself to a JVM shutdown hook, which before exiting will close the database without persisting any unsaved changes to the disk. This shutdown hook protects the data file from corruption due to JVM shutdown before properly closing the database.

Further Reading

In the next article, we will discuss the collections. In the meantime, if you feel interested, head out to Nitrite's project page or GitHub repo. If you want to dig into Nitrite's capabilities in more details, please go to its documentation page, where you will find all the tiny details with lots of examples.