Toge-DB ORM Documentation

Toge-DB is a lightweight JSON-based database with a simple ORM (Object-Relational Mapping) layer. It is specifically designed to be highly suitable for rapid prototyping and offline applications, such as those built with Electron or other JavaScript frameworks. This documentation explains how to define models, perform queries, and manage data using the TogeORM.

[WARNING] Disclaimer: AI-Generated Software This library is approximately 99.99% generated by artificial intelligence (AI). While it is designed to provide a lightweight database and ORM solution, we cannot guarantee its reliability or performance in all scenarios. Use this library at your own risk. We are not responsible for any issues or damages that may arise from its use in your application.

Table of Contents

• CLI Usage
• Initialization
• Defining Models
• Creating Data
• Querying Data
• Updating Data
• Deleting Data

CLI Usage

TogeDB comes with a raw CLI that supports SQL-like queries. After installing the library, you can easily start the CLI using npx:

npx toge-db

Or, if you are developing within the toge-db repository, you can run npm run toge-start.

Authentication

Please set the in .env file with the following credentials:

TOGE_DB_ADMIN_USER=your-username
TOGE_DB_ADMIN_PASSWORD=your-password

Supported SQL Commands

The CLI supports the following raw commands:

CREATE TABLE

CREATE TABLE users (username string PRIMARY KEY, email string, age int)

INSERT INTO

INSERT INTO users VALUES ('johndoe', '[email protected]', 30)

SELECT

Supports column selection, WHERE clause (simple col=val), and LIMIT.

SELECT * FROM users
SELECT username, email FROM users WHERE age=30
SELECT * FROM users LIMIT 5

UPDATE

UPDATE users SET age=31 WHERE username='johndoe'

DELETE

DELETE FROM users WHERE username='johndoe'

DROP TABLE

DROP TABLE users

ALTER TABLE

ALTER TABLE users ADD bio string

Initialization

To start using TogeDB ORM, initialize the TogeORM with a directory path where your data will be stored.

import { TogeORM } from 'toge-db';
const orm = new TogeORM('./data');

Defining Models

Use orm.define(modelName, schema) to create a new model. If no primary key is defined in the schema, an auto-incrementing id field will be added automatically.

Schema Options

• type: Data type (e.g., 'string', 'int').
• primaryKey: Boolean, marks the column as a primary key.
• autoIncrement: Boolean, enables auto-increment for the column.

const User = orm.define('user', {
    username: { type: 'string', primaryKey: true },
    email: { type: 'string' },
    age: { type: 'int' }
});

const Post = orm.define('post', {
    title: { type: 'string' },
    content: { type: 'string' }
}); // Automatically adds an 'id' primary key

Creating Data

There are two ways to create and persist data:

1. Using Model.create()

Directly creates and saves a new record.

const newUser = User.create({
    username: 'johndoe',
    email: '[email protected]',
    age: 30
});

2. Using new Model() and save()

Instantiate a model and save it later.

const post = new Post({
    title: 'Hello TogeDB',
    content: 'This is my first post.'
});
post.save();

Querying Data

TogeDB uses JavaScript functions as conditions for querying.

Find All

Model.find(condition) returns an array of model instances. If no condition is provided, it returns all records.

// Find all users
const allUsers = User.find();

// Find users older than 25
const seniors = User.find(user => user.age > 25);

Find One

Model.findOne(condition) returns the first matching model instance or null.

const user = User.findOne(u => u.username === 'johndoe');

Updating Data

1. Static Update

Update multiple records matching a condition.

User.update(
    user => user.username === 'johndoe',
    { age: 31 }
);

2. Instance Update

Modify an instance and call save(). This requires the model to have a primary key.

const user = User.findOne(u => u.username === 'johndoe');
if (user) {
    user.email = '[email protected]';
    user.save();
}

Deleting Data

Use Model.delete(condition) to remove records from the database.

// Delete a specific user
User.delete(user => user.username === 'johndoe');

// Delete all posts
Post.delete(() => true);