TOONDB

TOONDB is a lightweight document database engine with a production-ready HTTP service layer.

Repository:

• github.com/lythelab/toondb

It is designed for:

• single-tenant containerized DB instances
• SaaS multi-instance deployment patterns
• simple URL + username + password access from apps

Highlights

• Document storage with schema validation
• Indexed equality lookups
• TOON + JSON support
• WAL-based durability and recovery
• Tenant-isolated storage layout
• Bridge-compatible action API

Related Packages

JavaScript SDK:

npm install toondb

Quick Start (Local)

1) Run with Docker Compose (recommended)

From this repository root:

docker compose up -d --build

Default service endpoint:

• http://localhost:6767

Default compose environment is in:

• docker-compose.yml

Set these before production use:

• TOONDB_USERNAME
• TOONDB_PASSWORD
• TOONDB_TENANT

2) Verify health

$u = "replace_me_user"
$p = "replace_me_password"
$auth = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("$u`:$p"))
curl -H "Authorization: Basic $auth" http://127.0.0.1:6767/health

Cloud Setup (toondb.io)

If using managed TOONDB cloud (toondb.io):

1. Create a DB instance in the cloud dashboard.
2. Copy instance URL, username, and password.
3. Use the SDK or direct HTTP API.

SDK usage:

npm install toondb

import { ToonDBClient } from "toondb";

const client = new ToonDBClient({
  baseUrl: "https://your-instance.toondb.io",
  username: "your-user",
  password: "your-pass",
});

Service Endpoints

All endpoints require HTTP Basic Auth.

Core REST API

• GET /health
• POST /v1/collections/{collection}/create
• POST /v1/collections/{collection}/schema/update
• POST /v1/collections/{collection}/insert
• POST /v1/collections/{collection}/find
• POST /v1/collections/{collection}/update
• POST /v1/collections/{collection}/delete
• GET /v1/collections/{collection}/dump

Bridge-Compatible API

• POST /v1/bridge

Supported bridge actions:

• create_collection
• insert
• update
• update_schema
• find
• delete
• dump
• shutdown

Service Configuration

Environment variables:

• TOONDB_HOST (default: 0.0.0.0)
• TOONDB_PORT (default: 6767)
• PORT (fallback for cloud platforms like Railway)
• TOONDB_DATA_DIR (default: ./data-go)
• TOONDB_TENANT (default: default)
• TOONDB_USERNAME (optional; generated if empty)
• TOONDB_PASSWORD (optional; generated if empty)

If credentials are not provided, TOONDB auto-generates:

• username: 2 random lowercase words concatenated
• password: random 24-character secret

Run Without Docker

go run ./cmd/toondb-service -host 127.0.0.1 -port 6767 -tenant acme -data-dir ./data-go

Data Layout

<dataDir>/tenants/<tenantId>/
  collections.meta.json
  <collection>.toon
  <collection>.idx
  <collection>.wal

With Docker, keep volume mapping enabled for persistence.

Local Development

Run tests

go test ./...

Detailed test guide

• TESTING.md

Distribution

Release and distribution guidance:

• DISTRIBUTION.md