Getting Started with WebDB

Welcome to WebDB, an ultra-lean, browser-native relational database engine.

1. Installation

NOTE

WebDB is currently in active development. You can test the working vertical slice prototype directly from source.

bash

# Clone the repository
git clone https://github.com/ahmad-moussawi/webdb.git
cd webdb

# Install dependencies
npm install

# Build TypeScript output
npm run build

# Run test suite
npm test

2. Quickstart Example

Here is how to create a database, define a table, insert records, and execute queries:

typescript

import { WebDB } from '@webdb/core';

// 1. Open a database (in-memory or persistent IndexedDB)
const db = await WebDB.open({
  name: 'my_app_db',
  storage: 'idb', // 'memory' or 'idb'
});

// 2. Define schema (encoded directly onto Page 1 Binary Master Table)
await db.createTable('users', [
  { name: 'id', type: 'INT32', flags: { primaryKey: true, notNull: true } },
  { name: 'name', type: 'TEXT', flags: { notNull: true } },
  { name: 'age', type: 'INT32' },
  { name: 'salary', type: 'FLOAT64' },
]);

// 3. Insert records
await db.insert('users', { id: 1, name: 'Alice', age: 30, salary: 140000 });
await db.insert('users', { id: 2, name: 'Bob', age: 22, salary: 85000 });
await db.insert('users', { id: 3, name: 'Charlie', age: 35, salary: null });

// 4. Query with filters, ordering, and limits
const results = await db.from('users')
  .where('age', '>', 25)
  .whereNotNull('salary')
  .orderBy('salary', 'desc')
  .limit(10)
  .toArray();

console.table(results);

3. Query Plan Inspection (`.explain()`)

To inspect the VDBE bytecode generated by your query:

typescript

const explainInfo = await db.from('users')
  .where('age', '>', 25)
  .whereNotNull('salary')
  .explain();

console.log(explainInfo.assembly);

This outputs the disassembled bytecode with memory addresses, opcodes, registers, and comments:

ADDR     OPCODE             P1           P2                   P3         COMMENT
-----------------------------------------------------------------------------------------------
0x0000   OP_LOAD_INT        r[1]         25                              Load literal int 25 into r[1]
0x0006   OP_OPEN_CURSOR     c[0]         page=2                          Open cursor 0 on root page 2 ('users')
0x000c   OP_REWIND          c[0]         0x0028                          Rewind cursor to first row; jump to 0x0028 if empty
0x0010   OP_COLUMN_INT      c[0]         2 ('age')            r[0]       Read 'age' as INT into r[0]
0x0013   OP_GT              r[0]         r[1]                 0x001b     If r[0] > r[1] -> jump to 0x001b
0x0018   OP_JUMP            0x0021                                       Unconditional jump to 0x0021
0x001b   OP_IS_NULL         c[0]         3 ('salary')         0x0021     If 'salary' IS NULL -> jump to 0x0021
0x001f   OP_EMIT_ROW        c[0]                                         Row passed all filters -> emit to Output Result Buffer
0x0021   OP_NEXT_ROW        c[0]         0x0028                          Advance cursor to next row; jump to 0x0028 if EOF
0x0025   OP_JUMP            0x0010                                       Unconditional jump to 0x0010
0x0028   OP_HALT                                                         Halt VM execution (STATUS_DONE)

4. Interactive Browser Playground

To explore WebDB visually in your browser:

bash

npm run playground

Open http://localhost:3000/playground/index.html to run interactive queries, inspect live page slot allocations, and view the bytecode disassembler in real time.

5. Architectural Deep Dives

Explore our technical specifications:

Getting Started with WebDB ​

1. Installation ​

2. Quickstart Example ​

3. Query Plan Inspection (.explain()) ​

4. Interactive Browser Playground ​

5. Architectural Deep Dives ​