https://github.com/tuannh982/phantom
Simple, fast Key-Value storage. Inspired by HaloDB
https://github.com/tuannh982/phantom
database from-scratch hash-indexes java key-value key-value-database
Last synced: about 2 months ago
JSON representation
Simple, fast Key-Value storage. Inspired by HaloDB
- Host: GitHub
- URL: https://github.com/tuannh982/phantom
- Owner: tuannh982
- License: mit
- Created: 2021-07-11T12:01:40.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2022-01-11T03:02:42.000Z (over 3 years ago)
- Last Synced: 2025-03-25T04:26:46.635Z (2 months ago)
- Topics: database, from-scratch, hash-indexes, java, key-value, key-value-database
- Language: Java
- Homepage:
- Size: 293 KB
- Stars: 13
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Phantom
======
[](https://github.com/tuannh982/phantom/blob/master/LICENSE)
[](https://lgtm.com/projects/g/tuannh982/phantom/alerts)
[](https://lgtm.com/projects/g/tuannh982/phantom/context:java)
## Introduction
Phantom is an embedded key-value store, provides extreme high write throughput while maintains low latency data access.
Phantom was inspired by HaloDB, the name "Phantom" (belongs to the darkness) was derived from
the name "Halo" (belongs to the light) from HaloDB.
The design principles of Phantom is old and simple. It uses log-structured data files and hash index (like HaloDB) to
achieve the high write workload yet still maintain low latency access with the cost of no range scan support.
## Usage
### Installation (PRE-RELEASE version)
Add dependency to pom.xml (Maven)
```xml
io.github.tuannh982
phantom
```
or build.gralde (Gradle)
```groovy
implementation 'io.github.tuannh982:phantom:+'
```
### Create DB instance
```java
String path = "/path/to/your/db/dir";
DB db = new PhantomDB(
new File(path),
PhantomDBOptions.builder()
.numberOfIndexingThread(2 * Runtime.getRuntime().availableProcessors())
.compactionThreshold(0.5f)
.dataFlushThreshold(8 * 1024 * 1024)
.maxKeySize(8)
.maxFileSize(32 * 1024 * 1024)
.maxTombstoneFileSize(8 * 1024 * 1024)
.offHeapHashTable(true)
.estimatedMaxKeyCount(16)
.memoryChunkSize(4 * 1024 * 1024)
.build()
);
```
### Basic operations
#### get
```java
byte[] key = new byte[] {...};
GetResult result = db.get(key);
byte[] read = result.getValue();
```
#### put
```java
byte[] key = new byte[] {...};
byte[] value = new byte[] {...};
ModifyResult result = db.put(key, value);
boolean success = result.isSuccess();
```
#### putIfAbsent
```java
byte[] key = new byte[] {...};
byte[] value = new byte[] {...};
ModifyResult result = db.putIfAbsent(key, value);
boolean success = result.isSuccess();
```
#### replace
```java
byte[] key = new byte[] {...};
byte[] value = new byte[] {...};
ModifyResult result = db.replace(key, value);
boolean success = result.isSuccess();
```
#### delete
```java
byte[] key = new byte[] {...};
ModifyResult result = db.delete(key, value);
boolean success = result.isSuccess();
```
#### advanced write operation
```java
byte[] key = new byte[] {...};
WriteOps ops = WriteOps.PUT;
WritePolicy policy = WritePolicy.builder()
.sequenceNumberPolicy(WritePolicy.SequenceNumberPolicy.NONE)
.recordExistsAction(WritePolicy.RecordExistsAction.CREATE_ONLY)
.build();
ModifyResult result = db.write(ops, policy, key, value);
boolean success = result.isSuccess();
```
### Close DB instance
```java
db.close();
```
## Notes
This project still in development, so there are lots of bugs exist.
Please don't use the pre-release version as they contain a lot of bugs,
use directly from master branch since it's always up-to-date and maybe contains bug fixed.
## TODOs
- Testing
- Unit test
- Performance test
- Benchmark report
- Guide
- Tuning guide
- Development guide
- Support distributed mode
- WAL (in consideration)
- Replication manager