# Nitrite Database

Nitrite database is a serverless, embedded, and self-contained Java NoSQL database. It is an open-source project that provides a simple API for persistent data storage. Nitrite database is designed to be lightweight, fast, and easy to use.

# Creating a Database

Nitrite database can be created in-memory or on-disk. By default, Nitrite database is created in-memory. To create a database on-disk, you need to add a storage module dependency to your project. More details about storage modules can be found here.

To create a database, you need to use nitrite() function. It is a builder function that returns an instance of Nitrite.

var db = nitrite {
    // database configuration
}

# In-memory Database

If you don't load any on-disk storage module, then Nitrite will create an in-memory database. The below code snippet shows how to create a database in-memory.

var db = nitrite()

# On-disk Database

The below code snippet shows how to create a database on-disk.

# MVStore Backed Database

val storeModule = MVStoreModule.withConfig()
    .filePath("/path/to/my.db")
    .build()

var db = nitrite {
    loadModule(storeModule)
}

More details about MVStore configuration can be found here.

# RocksDB Backed Database

val storeModule = RocksDBModule.withConfig()
    .filePath("/path/to/my.db")
    .build()

var db = nitrite {
    loadModule(storeModule)
}

More details about RocksDB configuration can be found here.

# Securing a Database

To secure a database, you need to pass a username and password to the nitrite() function. The below code snippet shows how to secure a database.

var db = nitrite("user", "password") {
    // database configuration
}

# Registering an EntityConverter

Nitrite database uses a mapper to map Kotlin/Java entities to Nitrite documents and vice-versa. By default, Nitrite uses SimpleNitriteMapper as its mapper. This mapper uses EntityConverters to map entities to Nitrite documents and vice-versa. To register an EntityConverter, you need to call registerEntityConverter() method on Builder instance.

var db = nitrite {
    registerEntityConverter(MyEntityConverter())
}

More details about EntityConverter can be found here.

# Loading a Nitrite Module

Nitrite database is modular in nature. It provides a set of modules to extend its functionality. To load a module, you need to call loadModule() method on Builder instance.

var db = nitrite {
    loadModule(MyModule())
}

More details about Nitrite modules can be found here.

# Loading a Storage Module

var db = nitrite {
    loadModule(MVStoreModule.withConfig()
        .filePath("/path/to/my.db")
        .build())
}

More details about storage modules can be found here.

# Adding Migration Steps

Nitrite database supports migration from one version to another. To add a migration step, you need to call addMigration() method on Builder instance.

var db = nitrite {
    addMigration(object : Migration(Constants.INITIAL_SCHEMA_VERSION, 2) {
        override fun migrate(instruction: InstructionSet) {
            instruction.forDatabase()
                .dropCollection("test")
        }
    })
    loadModule(MVStoreModule(fileName))
    schemaVersion = 2
}

More details about schema migration can be found here.

# Current Schema Version

To configure the current schema version, you need to set the schemaVersion property on Builder instance.

var db = nitrite {
    schemaVersion = 2
}

# Field Separator Character

Nitrite database uses . as the field separator character. It is used to separate nested fields in a document. For example, if you have a document like below:

{
    "firstName": "John",
    "lastName": "Doe",
    "address": {
        "street": "123 Main Street",
        "city": "New York",
        "state": "NY",
        "zip": "10001"
    }
}

Then you can access the firstName field like below:

val firstName = document["firstName"]

And you can access the street field like below:

val street = document["address.street"]

To configure the field separator character, you need to set the fieldSeparator property on Builder instance.

var db = nitrite {
    fieldSeparator = '.'
}