Getting Started
Create your first database and learn the basics
Creating a Client
The client manages your database directory:
import { createClient } from "toollessdb";
const client = createClient({ path: "./data" });The path option specifies where all your databases will be stored. Each database becomes a
folder inside this directory.
Creating a Database
Get a database instance (created automatically if it doesn't exist):
const db = client.db("myapp");Working with Collections
Get a collection to store documents:
const users = db.collection("users");Inserting Documents
Insert a single document:
const result = await users.insertOne({
name: "Alice",
email: "alice@example.com",
age: 30,
});
console.log(result.insertedId);Auto-generated IDs
If you don't provide an _id field, Toolless generates a unique ObjectId automatically.
Insert multiple documents:
const result = await users.insertMany([
{ name: "Bob", email: "bob@example.com", age: 25 },
{ name: "Charlie", email: "charlie@example.com", age: 35 },
]);
console.log(result.insertedIds);Querying Documents
Find all documents:
const allUsers = await users.find({}).toArray();Find with filter:
const adults = await users.find({ age: { $gte: 18 } }).toArray();Find one document:
const alice = await users.findOne({ name: "Alice" });Updating Documents
Update one document:
await users.updateOne({ name: "Alice" }, { $set: { age: 31 } });Update many documents:
await users.updateMany({ age: { $lt: 30 } }, { $set: { category: "young" } });Update Operators Required
Always use update operators like $set, $inc, $push when updating. Passing a plain object
will replace the entire document.
Deleting Documents
Delete one document:
await users.deleteOne({ name: "Alice" });Delete many documents:
await users.deleteMany({ category: "inactive" });Complete Example
import { createClient } from "toollessdb";
async function main() {
const client = createClient({ path: "./data" });
const db = client.db("blog");
const posts = db.collection("posts");
// Create a post
const { insertedId } = await posts.insertOne({
title: "Hello World",
content: "This is my first post",
author: "Alice",
published: true,
createdAt: new Date().toISOString(),
});
// Find published posts
const published = await posts
.find({ published: true })
.sort({ createdAt: -1 })
.limit(10)
.toArray();
// Update post
await posts.updateOne({ _id: insertedId }, { $set: { title: "Hello Toolless" } });
// Count posts
const count = await posts.countDocuments({ author: "Alice" });
console.log(`Alice has ${count} posts`);
}
main();File Structure
After running, your data directory will look like:
data/
└── blog.tdb/
└── posts.tdbEach .tdb file contains one JSON document per line (JSON Lines format).
Human Readable
You can open .tdb files in any text editor to inspect your data. Each line is a complete JSON
document.