Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nitrite/nitrite-java

NoSQL embedded document store for Java
https://github.com/nitrite/nitrite-java

android database documentdb embedded-database mobile-database nosql object-database object-storage

Last synced: 18 days ago
JSON representation

NoSQL embedded document store for Java

Awesome Lists containing this project

README 

        
# Nitrite Database



[![Build](https://github.com/nitrite/nitrite-java/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/nitrite/nitrite-java/actions/workflows/build.yml)

[![CodeQL](https://github.com/nitrite/nitrite-java/actions/workflows/codeql-analysis.yml/badge.svg?branch=main)](https://github.com/nitrite/nitrite-java/actions/workflows/codeql-analysis.yml)

[![codecov](https://codecov.io/gh/nitrite/nitrite-java/branch/main/graph/badge.svg)](https://codecov.io/gh/nitrite/nitrite-java)

[![javadoc](https://javadoc.io/badge2/org.dizitart/nitrite/javadoc.svg)](https://javadoc.io/doc/org.dizitart/nitrite) 

[![Discussion](https://img.shields.io/badge/chat-Discussion-blueviolet)](https://github.com/orgs/nitrite/discussions)





    nitrite logo




**NO**sql **O**bject (**NO2** a.k.a Nitrite) database is an open source nosql embedded

document store. It supports both in-memory and file based persistent store.



Nitrite is an embedded database ideal for desktop, mobile or small web applications.



**It features**:



- Embedded, serverless

- Simple API

- Document-oriented

- Schemaless document collection and object repository

- Extensible storage engines - mvstore, rocksdb

- Indexing and full-text search

- Simple query api

- In-memory and file-based store

- Transaction support

- Schema migration support

- Encryption support

- Android compatibility (API Level 24)



## Kotlin Extension



Nitrite has a kotlin extension called **Potassium Nitrite** for kotlin developers.

Visit [here](https://github.com/nitrite/nitrite-java/tree/main/potassium-nitrite) for more details.



## Flutter Version



If you are looking for Nitrite for Flutter/Dart, head over to [nitrite-flutter](https://github.com/nitrite/nitrite-flutter).



## Deprecation Notice



Nitrite DataGate and Nitrite Explorer is now deprecated and no longer maintained.



## Getting Started with Nitrite



**NOTE:** There are breaking api changes in version 4.x. So please read the [guide](https://nitrite.dizitart.com/java-sdk/getting-started/index.html) before upgrading from 3.x.x.



### How To Install



To use Nitrite in any Java application, first add the nitrite bill of materials, then add required dependencies:



**Maven**



```xml



    

        

            org.dizitart

            nitrite-bom

            [latest version]

            import

            pom

        

    



    

        org.dizitart

        nitrite

    



    

        org.dizitart

        nitrite-mvstore-adapter

    



```

    

**Gradle**



```groovy



implementation(platform("org.dizitart:nitrite-bom:[latest version]"))

    

implementation 'org.dizitart:nitrite'

implementation 'org.dizitart:nitrite-mvstore-adapter'



```

    

## Examples



A Todo android application is available [here](https://github.com/nitrite/nitrite-android-demo) to demonstrate the usage of Nitrite in android.



### Quick Examples



**Initialize Database**



```java

// create a mvstore backed storage module

MVStoreModule storeModule = MVStoreModule.withConfig()

    .filePath("/tmp/test.db") 

    .compress(true)

    .build();



// or a rocksdb based storage module

RocksDBModule storeModule = RocksDBModule.withConfig()

    .filePath("/tmp/test.db")

    .build();



// initialization using builder

Nitrite db = Nitrite.builder()

        .loadModule(storeModule)

        .loadModule(new JacksonMapperModule())  // optional

        .openOrCreate("user", "password");



```



**Create a Collection**



```java

// Create a Nitrite Collection

NitriteCollection collection = db.getCollection("test");



// Create an Object Repository

ObjectRepository repository = db.getRepository(Employee.class);



```



**Annotations for POJO**



```java



@Entity(value = "retired-employee",     // entity name (optional), 

    indices = {

        @Index(value = "firstName", type = IndexType.NON_UNIQUE),

        @Index(value = "lastName", type = IndexType.NON_UNIQUE),

        @Index(value = "note", type = IndexType.FULL_TEXT),

})

public class Employee implements Serializable {

    // provides id field to uniquely identify an object inside an ObjectRepository

    @Id

    private long empId;

    private Date joinDate;

    private String firstName;

    private String lastName;

    private String note;



    // ... public getters and setters

}



```



**CRUD Operations**



```java



// create a document to populate data

Document doc = Document.createDocument("firstName", "John")

     .put("lastName", "Doe")

     .put("birthDay", new Date())

     .put("data", new byte[] {1, 2, 3})

     .put("fruits", new ArrayList() {{ add("apple"); add("orange"); add("banana"); }})

     .put("note", "a quick brown fox jump over the lazy dog");



// insert the document

collection.insert(doc);



// find a document

collection.find(where("firstName").eq("John").and(where("lastName").eq("Doe"));



// update the document

collection.update(where("firstName").eq("John"), createDocument("lastName", "Wick"));



// remove the document

collection.remove(doc);



// insert an object in repository

Employee emp = new Employee();

emp.setEmpId(124589);

emp.setFirstName("John");

emp.setLastName("Doe");



repository.insert(emp);



```



**Create Indices**



```java



// create document index

collection.createIndex(indexOptions(IndexType.NON_UNIQUE), "firstName", "lastName"); // compound index

collection.createIndex(indexOptions(IndexType.FULL_TEXT), "note"); // full-text index



// create object index. It can also be provided via annotation

repository.createIndex(indexOptions(IndexType.NON_UNIQUE), "firstName");



```



**Query a Collection**



```java



DocumentCursor cursor = collection.find(

    where("firstName").eq("John")               // firstName == John

    .and(

        where("data").elemMatch("$".lt(4))      // AND elements of data array is less than 4

            .and(

                where("note").text("quick")     // AND note field contains string 'quick' using full-text index

        )       

    )

);



for (Document document : cursor) {

    // process the document

}



// get document by id

Document document = collection.getById(nitriteId);



// query an object repository and create the first result

Cursor cursor = repository.find(where("firstName").eq("John"));

Employee employee = cursor.firstOrNull();



```



**Transaction**



```java

try (Session session = db.createSession()) {

    try (Transaction transaction = session.beginTransaction()) {

        NitriteCollection txCol = transaction.getCollection("test");



        Document document = createDocument("firstName", "John");

        txCol.insert(document);



        transaction.commit();

    } catch (TransactionException e) {

        transaction.rollback();

    }

}



```



**Schema Migration**



```java



Migration migration1 = new Migration(Constants.INITIAL_SCHEMA_VERSION, 2) {

    @Override

    public void migrate(InstructionSet instructions) {

        instructions.forDatabase()

            // make a non-secure db to secure db

            .addUser("test-user", "test-password");



        // create instructions for existing repository

        instructions.forRepository(OldClass.class, "demo1")



            // rename the repository (in case of entity name changes)

            .renameRepository("migrated", null)



            // change datatype of field empId from String to Long and convert the values

            .changeDataType("empId", (TypeConverter) Long::parseLong)



            // change id field from uuid to empId

            .changeIdField(Fields.withNames("uuid"), Fields.withNames("empId"))



            // delete uuid field

            .deleteField("uuid")

    

            // rename field from lastName to familyName

            .renameField("lastName", "familyName")



            // add new field fullName and add default value as - firstName + " " + lastName

            .addField("fullName", document -> document.get("firstName", String.class) + " "

                + document.get("familyName", String.class))



            // drop index on firstName

            .dropIndex("firstName")



            // drop index on embedded field literature.text

            .dropIndex("literature.text")



            // change data type of embedded field from float to integer and convert the values 

            .changeDataType("literature.ratings", (TypeConverter) Math::round);

    }

};



Migration migration2 = new Migration(2, 3) {

    @Override

    public void migrate(InstructionSet instructions) {

        instructions.forCollection("test")

            .addField("fullName", "Dummy Name");

    }

};



MVStoreModule storeModule = MVStoreModule.withConfig()

    .filePath("/temp/employee.db")

    .compressHigh(true)

    .build();



db = Nitrite.builder()

    .loadModule(storeModule)

    

    // schema versioning is must for migration

    .schemaVersion(2)



    // add defined migration paths

    .addMigrations(migration1, migration2)

    .openOrCreate();



```



**Import/Export Data**



```java

// Export data to json file



// create export options

ExportOptions exportOptions = new ExportOptions();

// set the nitrite factory

exportOptions.setNitriteFactory(() -> openDb("test.db"));

// set the collections to export

exportOptions.setCollections(List.of("first"));

// set the repositories to export

exportOptions.setRepositories(List.of("org.dizitart.no2.support.data.Employee", "org.dizitart.no2.support.data.Company"));

// set the keyed repositories to export

exportOptions.setKeyedRepositories(Map.of("key", Set.of("org.dizitart.no2.support.data.Employee")));

// create an exporter with export options

Exporter exporter = Exporter.withOptions(exportOptions);

exporter.exportTo("test.json");



// Import data from the file



// create import options

ImportOptions importOptions = new ImportOptions();

// set the nitrite factory

importOptions.setNitriteFactory(() -> openDb("new-test.db"));

// create an importer with import options

Importer importer = Importer.withOptions(importOptions);

importer.importFrom("test.json");



```



More details are available in the [guide](https://nitrite.dizitart.com/java-sdk/getting-started/index.html).



## Release Notes



Release notes are available [here](https://github.com/nitrite/nitrite-java/releases).



## Documentation



Reference

API



Document


JavaDoc



## Build



To build and test Nitrite, ensure you have JDK 11 (or higher) and Maven 3 installed.



```shell script



git clone https://github.com/nitrite/nitrite-java.git

cd nitrite-java

mvn clean install



```



## Support / Feedback



For issues with, questions about, or feedback create a [discussion](https://github.com/orgs/nitrite/discussions).



## Bugs / Feature Requests



Think you’ve found a bug? Want to see a new feature in the Nitrite? Please open an issue [here](https://github.com/nitrite/nitrite-java/issues). But

before you file an issue please check if it is already existing or not.



## Maintainers



-   Anindya Chatterjee



## Contributors



This project exists thanks to all the people who contribute. For more details please visit [CONTRIBUTING.md](https://github.com/nitrite/nitrite-java/blob/main/CONTRIBUTING.md).



## Sponsors



Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor](https://github.com/sponsors/anidotnet) for this project.



## Presentation & Talks



[Idan Sheinberg](https://github.com/sheinbergon) has given a talk on Nitrite at [**Kotlin Everywhere - TLV Edition**](https://www.meetup.com/KotlinTLV/events/265145254/) meetup on October 27, 2019. Please find his presentation [here](https://www.slideshare.net/IdanShinberg/nitrite-choosing-the-rite-embedded-database).



## Special Thanks







    JProfiler






    YourKit



   



    MacStadium