Skip to content

Latest commit

 

History

History
297 lines (214 loc) · 11 KB

README.md

File metadata and controls

297 lines (214 loc) · 11 KB
Raw
Built by @nomadiz

███████╗██████╗ ███╗   ███╗ █████╗ 
██╔════╝██╔══██╗████╗ ████║██╔══██╗
█████╗  ██║  ██║██╔████╔██║███████║
██╔══╝  ██║  ██║██║╚██╔╝██║██╔══██║
███████╗██████╔╝██║ ╚═╝ ██║██║  ██║
╚══════╝╚═════╝ ╚═╝     ╚═╝╚═╝  ╚═╝
-----------------------------------
Embedded Database Management for All

What is EDMA?

EDMA: Embedded Database Management for All is an open source project made to manage embedded key-value storages. EDMA is a TUI (Terminal User Interface) that is easy to install and configure. It allows engineer to traverse the embedded database and deserialize byte data with provided byte layout. This enhances the experience of working with low level database system like RocksDB or Redb.

Features

  • Multi embedded database supported: RocksDB, Redb, Sled
  • Cross-platform supported: Windows, Linux and MacOS
  • Custom byte layout deserialization
  • Execute database command directly in terminal
  • Interactive terminal interface with keyboard only control
  • Iterate key-value pairs from column family and table

Roadmap

  • NEW: Universal Key Value Storage support (UKV)
  • NEW: Sled support
  • NEW: LevelDB support
  • Adding consistent mode for editor view

Supported Storages

EDMA supports multiple databases with easy plug-to-play architecture. Please check below list for supported databases and its features:

Database name Description EDMA release Pull request
RocksDB Support both non-column and column byte data viewer (COLUMN) v0.1.0-beta.4 N/A
ReDB Support default database (Will add TABLE view) v0.1.0-beta.4 N/A
Sled Support both non-tree and tree byte data viewer (TREE) v0.1.0-beta.5 #8 Sled support

To create a PR for a database integration, please go to Issues > New Issue > Feature request

Getting Started

Installation

With Cargo (Linux, macOS, Windows)

If you already have a Rust environment set up, you can use the cargo install command:

cargo install --version 0.1.0-beta.3 edma

From binaries (Linux, macOS, Windows)

Set a config path

Configuration file is where you identify path to databases and EDMA byte templates. To set a config path, using a CLI command

$ edma --config-path [PATH_TO_FILE]

Please view EDMA Configuration file to learn more how configuration file works.

Usage

Run EDMA terminal application

$ edma

Set a config file path

$ edma --config-path [PATH]

Using help command

$ edma --help

edma 0.1.0
A cross-platform TUI database management tool written in Rust

USAGE:
    tui [OPTIONS]

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -c, --config-path <config-path>    Set the config file

Why use EDMA?

Compatible with multiple databases

EDMA is a very first database management tool designed for embedded databases. Applying adapter design pattern into database storage implementation, it makes integration with databases become easier. EDMA supports two databases by default: RocksDB and ReDB. To integrate with other embedded databases, you can add the implementation in EDMA storage layer

Interactive terminal UI

EDMA is built using Rust library tui-rs which makes it to be an app that can be run directly on your terminal. No startup time needed and it's extremely light weight. Run every where, every time, all at once

Template management for byte deserializer

Data in embedded database is different from data presented in relational databases. While relational databases label data with specific type and attributes when it is created, embedded database can't do that. The only data type that embedded database displays is byte array. For example, [0 0 0 1 50 32 20]. It is not human readable.

Using EDMA, byte data can be converted into human readable data using EDMA byte template system.

Instruction on how EDMA byte deserializer works: What is EDMA templates?

Command editor

Command editor is one core feature of EDMA, it allows you to manage byte data using advanced commands. The image below shows how a database column family can iterated using command editor

Keymap

Key Description
ENTER Enter focused section
ESC Escape from focused section
9, 0 Scroll up/down databases
h, j Scroll up/down key byte layout
k, l Scroll up/down value byte layout
←, →, ↑, ↓ Move focus to left/right/up/down
h, d, l Switch to home/databases/layouts
q Quit

EDMA Command

EDMA supports inline command to interact with embedded databases. The list of supported commands are

- COLUMN or TABLE

Iterate with defined column famility or table

Arguments

  • String: Column family name

- PREFIX or SUFFIX

Iterate filtered by prefix or suffix.

Note: This command is for key iteration not value iteration.

Arguments

  • String: Prefix value or suffix value

Configuration

Databases

Database name should be these two below

  • rocksdb: RocksDB
  • redb: Redb
  • sled: Sled

Database path should be String type

Templates

Byte template is an instruction combined by one or multiple byte layouts. It provides EDMA deserializer information about bytes data. To explain the use of byte template and byte layout, we have this example:

Original= edma2022github
Bytes= [65 64 6d 61 32 30 32 32 67 69 74 68 75 62]

Slicing data and labelling data as EDMA byte template, we have

[1]
original=edma
from=0
to=4
variant=String

[2]
original=2022
from=4
to=8
variant=Int32

[3]
original=github
from=8
to=13
variant=String

Example

Configuration file example

{
	"databases": [
		{
			"name": "rocksdb",
			"path": "/temp"
		},
		{
			"name": "sled",
			"path": "/temp/sled"
		}
	],
	"templates": [
		{
			"name": "Custom layout",
			"layouts": [
				{
					"name": "name",
					"from": 0,
					"to": 5,
					"variant": "String"
				},
				{
					"name": "id",
					"from": 5,
					"to": 10,
					"variant": "Int64"
				}
			]
		}
	]
}

Tribute

Without these awesome open source projects, EDMA can't be complete. Please share the spotlight with these repo below:gobang, tui-rs, spotify-tui and tui-re-tree-widget

How to contribute

Before committing to the tasks in the community, please skim through the guidelines below to grasp the overall idea of how the community works first. It does not take long but I believe it will give you a big picture of the vision and culture of TheLowLevelers.