Crate joydb

JSON/CSV file database and ORM for quick prototyping.

Joydb is a Rust library that acts like a database and ORM at the same time and provides a simple way to store and retrieve data in JSON, CSV or any other format.

Getting started

Install prerequisites:

cargo install serde --features derive
cargo install joydb --features json

use joydb::{Joydb, adapters::JsonAdapter, Model};
use serde::{Serialize, Deserialize};

// Define your model
#[derive(Debug, Clone, Serialize, Deserialize, Model)]
struct User {
    // id is mandatory field for every model.
    // We use integer here, but most likely you will want to use Uuid.
    id: u32,
    username: String,
}

// Define the state
joydb::state! {
    AppState,
    models: [User],
}

// Define the database (combination of state and adapter)
type Db = Joydb<AppState, JsonAdapter>;

// Create a new database or open an existing one
let db = Db::open("data.json").unwrap();

let alice = User {
   id: 1,
   username: "Alice".to_string(),
};

// Insert a new user
db.insert(&alice).unwrap();

// Get the user by ID
let user = db.get::<User>(&1).unwrap().unwrap();
assert_eq!(user.username, "Alice");

CRUD operations

Operation	Methods
Create	insert, upsert
Read	get, get_all, get_all_by, count
Update	update, upsert
Delete	delete, delete_all_by

Please refer to Joydb for more details.

Adapters

There are 2 types of adapters:

• Unified - uses a single file to store the state. It writes and reads the entire state at once. Usually requires a file path.
• Partitioned - uses multiple files to store the state. It writes and reads each relation separately. Usually requires directory path.

The following adapters are implemented out of the box and can be used with the corresponding feature flag enabled.

Adapter	Format	Type	Feature flag
JsonAdapter	JSON	Unified	json
JsonPartitionedAdapter	JSON	Partitioned	json
RonAdapter	RON	Unified	ron
RonPartitionedAdapter	RON	Partitioned	ron
CsvAdapter	CSV	Paritioned	csv

Sync policy

Sync policy defines when exactly the data must be written to the file system.

Please see SyncPolicy for more details.

Motivation

While prototyping new projects, I often needed some form of persistent storage. However, setting up a full-fledged database and ORM felt like overkill for the project’s scope. So I’d occasionally fall back to a simple JSON file. As this pattern repeated, I decided to solve the problem once and for all by building Joydb.

Limitation

Joydb is designed in the way that it writes the entire database state to a file system at once. This means that it is not suitable for high performance applications or for domains where the data is too large to fit in memory.

It’s highly recommended to switch to a proper database like PostgreSQL before Joydb turns into Paindb.

License

MIT © Serhii Potapov

Modules

adapters

Common place for adapter abstractions and a few implementations.

Macros

state

A macro to define a state struct that holds relations of models.

Structs

Joydb

A struct that represents a database. It’s thread-safe and can be shared between multiple threads.

JoydbConfig

Relation

A relation is a collection of records of a particular model and some metadata. associated with the relation.

Enums

JoydbError

Joydb error type.

JoydbMode

The mode of the database. This is used to specify how the database should be opened.

SyncPolicy

Specifies how and when the database should be synchronized with the file system.

Traits

GetRelation

A utility trait that implemented by a state that can store a relation of a model.

Model

An identifiable model that can be stored in a database.

State

A trait that represents a state that can be (de)serialized to/from JSON or any other format supported by an adapter.

Derive Macros

Model

A macro to derive the Model trait for a struct. A struct must have a field named id, which is the primary key.