TomsDB

A fast, minimal, developer-first database engine inspired by modern SQL systems, built for simplicity and control.

Install via NPMView on GitHub
CREATE TABLE users {
  id INT REQUIRED,
  username STRING,
  email STRING
};

Core Features

Everything you need for modern database development

SQL-like Syntax

Familiar SQL syntax with modern extensions for developer productivity.

Schema-based Tables

Strongly typed schema definitions with runtime validation.

Fast Go Engine

Built in Go for high performance and minimal memory footprint.

WAL Persistence

Write-ahead logging ensures data durability and crash recovery.

CLI + Server Mode

Run as a standalone server or use the command-line interface.

Open Source

MIT licensed, extensible, and community-driven development.

Architecture

A clean execution pipeline designed for speed and reliability

Step 1

Client

Application layer sends SQL queries

Step 2

Parser

Validates and tokenizes SQL syntax

Step 3

Engine

Executes optimized query plans

Step 4

Storage

Manages data persistence layer

Step 5

WAL

Write-ahead logging for durability

High Performance

Optimized Go routines and connection pooling ensure minimal latency and maximum throughput for concurrent operations.

Data Integrity

WAL ensures data integrity and crash recovery with production-grade durability and ACID compliance.

Type Safety

Strong schema validation at runtime prevents data corruption and ensures query correctness.

Technical Highlights

Query Processing

  • •SQL tokenization and AST generation
  • •Query optimization and execution planning
  • •Index-based query acceleration

Storage Engine

  • •B-tree indexing for fast lookups
  • •Page-based storage management
  • •Efficient memory buffer pooling

Code Examples

Real commands you can run today

Create

CREATE TABLE users (
  id INT REQUIRED,
  username STRING,
  email STRING
);

Insert

INSERT INTO users 
  (id, username, email) 
VALUES 
  (1, "tom", "tom@mail.com");

Query

SELECT * FROM users 
WHERE username = "tom";

Get Started

Node.js client for TomsDB database server

Install

$ npm install tomsdb

Quick Start

const tomsdb = require('tomsdb');

const db = await tomsdb.createConnection({
  host: 'localhost',
  port: 5432,
  user: 'admin',
  password: 'admin123',
  database: 'myapp'
});

await db.query('CREATE TABLE users (id INT AUTO_INCREMENT, name STRING REQUIRED, age INT)');
await db.query('INSERT INTO users (name, age) VALUES ("Alice", 25)');

const result = await db.query('SELECT * FROM users');
console.log(result);

db.end();

API Reference

tomsdb.createConnection(options) → Promise<Connection>

Creates and returns a connected, authenticated connection.

const db = await tomsdb.createConnection({
  host: 'localhost',       // default: 'localhost'
  port: 5432,              // default: 5432
  user: 'admin',           // default: 'admin'
  password: 'admin123',    // default: 'admin123'
  database: 'myapp',       // optional, auto-runs USE <database>
  connectTimeout: 10000,   // ms, default: 10000
  queryTimeout: 30000      // ms, default: 30000
});

connection.query(sql) → Promise<string|object[]>

Execute a SQL statement.

await db.query('CREATE DATABASE shop');
await db.query('USE shop');
await db.query('CREATE TABLE products (id INT AUTO_INCREMENT, name STRING REQUIRED, price INT)');
await db.query('INSERT INTO products (name, price) VALUES ("Widget", 999)');

const rows = await db.query('SELECT * FROM products');
console.log(rows);

tomsdb.createPool(options) → Pool

Create a connection pool for concurrent usage.

const pool = tomsdb.createPool({
  host: 'localhost',
  port: 5432,
  user: 'admin',
  password: 'admin123',
  database: 'myapp',
  connectionLimit: 10,  // default: 10
  queueLimit: 0         // 0 = unlimited, default: 0
});

const result = await pool.query('SELECT * FROM users');

Response Formatting

The SDK automatically formats human-readable string responses from the server into structured JavaScript objects.

Command

SELECT * ...
SHOW DATABASES
SHOW TABLES
DESCRIBE table

Formatted Output

[{ id: '1', name: 'Alice' }...]
[{ name: 'watchup', current: true }...]
['users', 'posts']
{ table: 'users', schema: [...] }

Express Example

const express = require('express');
const tomsdb = require('tomsdb');

const app = express();
const pool = tomsdb.createPool({
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT) || 5432,
  user: process.env.DB_USER || 'admin',
  password: process.env.DB_PASS || 'admin123',
  database: 'myapp',
  connectionLimit: 20
});

app.get('/users', async (req, res) => {
  try {
    const result = await pool.query('SELECT * FROM users');
    res.json({ data: result });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.listen(3000, () => console.log('Server running on :3000'));

Open Source

Join the community and help shape the future of TomsDB

Star the ProjectContribute