Nitrite Database
NOsql Object ( NO 2 a.k.a Nitrite) database is an open source nosql embedded document store written in Java. It has MongoDB like API. It supports both in-memory and single file based persistent store powered by MVStore engine of h2 database.
Nitrite is a server-less embedded database ideal for desktop, mobile or small web applications.
It features:
-
Embedded key-value/document and object store
-
In-memory or single data file
-
Very fast and lightweight MongoDB like API
-
Indexing
-
Full text search capability
-
Full Android compatibility
-
Observable store
-
Both way replication via Nitrite DataGate server
Getting Started
How To Install
To use Nitrite in any Java application, just add the below dependency:
Maven
<dependency>
<groupId>org.dizitart</groupId>
<artifactId>nitrite</artifactId>
<version>{
version
}
</version> </dependency>Gradle
compile 'org.dizitart:nitrite:{
version
}
'Quick Examples
Initialize Database
//java initialization Nitrite db = Nitrite.builder()
.compressed()
.filePath("/tmp/test.db")
.openOrCreate("user", "password");
//android initialization Nitrite db = Nitrite.builder()
.compressed()
.filePath(getFilesDir().getPath() + "/test.db")
.openOrCreate("user", "password");
Create a Collection
// Create a Nitrite Collection NitriteCollection collection = db.getCollection("test");
// Create an Object Repository ObjectRepository<Employee> repository = db.getRepository(Employee.class);
Annotations for POJO
// provides index information for ObjectRepository @Indices({
@Index(field = "joinDate", type = IndexType.NonUnique),
@Index(field = "name", type = IndexType.Unique)
}
) 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 name;
private String address;
// ... public getters and setters
}
CRUD Operations
// create a document to populate data Document doc = createDocument("firstName", "John")
.put("lastName", "Doe")
.put("birthDay", new Date())
.put("data", new byte[] {
1, 2, 3
}
)
.put("fruits", new ArrayList<String>() {
{
add("apple");
add("orange");
add("banana");
}
}
)
.put("note", "a quick brown fox jump over the lazy dog");
// insert the document collection.insert(doc);
// update the document collection.update(eq("firstName", "John"), createDocument("lastName", "Wick"));
// remove the document collection.remove(doc);
// insert an object Employee emp = new Employee();
emp.setEmpId(124589);
emp.setFirstName("John");
emp.setLastName("Doe");
repository.insert(emp);
Create Indices
// create document index collection.createIndex("firstName", indexOptions(IndexType.NonUnique));
collection.createIndex("note", indexOptions(IndexType.Fulltext));
// create object index. It can also be provided via annotation repository.createIndex("firstName", indexOptions(IndexType.NonUnique));
Query a Collection
Cursor cursor = collection.find(
// and clause
and(
// firstName == John
eq("firstName", "John"),
// elements of data array is less than 4
elemMatch("data", lt("$", 4)),
// elements of fruits list has one element matching orange
elemMatch("fruits", regex("$", "orange")),
// note field contains string 'quick' using full-text index
text("note", "quick")
)
);
for (Document document : cursor) {
// process the document
}
// create document by id Document document = collection.getById(nitriteId);
// query an object repository and create the first result Employee emp = repository.find(eq("firstName", "John"))
.firstOrDefault();
Automatic Replication
// connect to a DataGate server running at localhost 9090 port DataGateClient dataGateClient = new DataGateClient("http://localhost:9090")
.withAuth("userId", "password");
DataGateSyncTemplate syncTemplate
= new DataGateSyncTemplate(dataGateClient, "remote-collection@userId");
// create sync handle SyncHandle syncHandle = Replicator.of(db)
.forLocal(collection)
// a DataGate sync template implementation
.withSyncTemplate(syncTemplate)
// replication attempt delay of 1 sec
.delay(timeSpan(1, TimeUnit.SECONDS))
// both-way replication
.ofType(ReplicationType.BOTH_WAY)
// sync event listener
.withListener(new SyncEventListener() {
@Override
public void onSyncEvent(SyncEventData eventInfo) {
}
}
)
.configure();
// start sync in the background using handle syncHandle.startSync();
Import/Export Data
// Export data to a file Exporter exporter = Exporter.of(db);
exporter.exportTo(schemaFile);
//Import data from the file Importer importer = Importer.of(db);
importer.importFrom(schemaFile);
More details are available in the reference document.
Release Notes
Release notes are available here.
Build
To build and test Nitrite
$ git clone https://github.com/dizitart/nitrite-database.git $ cd nitrite-database $ ./gradlew buildThe test suite requires mongod to be running on localhost, listening on the default port. MongoDb is required to test replication using the DataGate server. Please run the below command to create the test user in mongo.
db.getSiblingDB('benchmark').createUser({
user: 'bench', pwd: 'bench', roles: [{
role: 'readWrite', db: 'benchmark'
}
, {
role: 'dbAdmin', db: 'benchmark'
}
]
}
)The test suite also requires android sdk 24.4.1 to be installed and ANDROID_HOME environment variable to be setup properly to test the android example.
Support / Feedback
For issues with, questions about, or feedback talk to us at Gitter.
Bugs / Feature Requests
Think you’ve found a bug? Want to see a new feature in the Nitrite? Please open an issue here. But before you file an issue please check if it is already existing or not.
Maintainers
-
Anindya Chatterjee