_.-````'-,_
                                            _,.,_ ,-'`           `'-.,_
                                          /)     (\                   '``-.
                                         ((      ) )                      `\
Y88b   d88P    d88888888888b. 888888b.    \)    (_/                        )\
 Y88b d88P    d88888888  "Y88b888  "88b    |       /)           '    ,'    / \
  Y88o88P    d88P888888    888888  .88P    `\    ^'            '     (    /  ))
   Y888P    d88P 888888    8888888888K.      |      _/\ ,     /    ,,`\   (  "`
    888    d88P  888888    888888  "Y88b      \Y,   |  \  \  | ````| / \_ \
    888   d88P   888888    888888    888        `)_/    \  \  )    ( >  ( >
    888  d8888888888888  .d88P888   d88P                 \( \(     |/   |/
    888 d88P     8888888888P" 8888888P"                 /_(/_(    /_(  /_(

YADB is a SQL database written in modern C++, built from scratch as an educational project. YADB is focused on being simple, functional, and correct. As a result, performance and scalability are intentionally not the top priorities—clarity and educational value come first.

⚠️ DISCLAIMER: YADB is in very early stages of development. Many features are incomplete, unstable, or missing entirely. This is an educational project and should not be used for production purposes. Expect bugs, breaking changes, and incomplete functionality.

---

Contents

• Blog Series
• Building
• Usage
• Architecture
• Supported SQL Syntax
• Roadmap

---

Blog Series

While I'm building YADB, I figured that it would be a good exercise to document my progress and share some of the design decisions I made along the way. You can check out the blog here.

Date	Post
14/03/2026	dev/3: liftoff
11/09/2025	dev/2: no tests, no failures
15/06/2025	dev/1: Page Buffer Manager and Asynchronous Disk I/O in YADB
02/06/2025	Database Internals: Page Buffers
29/05/2025	dev/0: Hello, World!

---

Building

1. Clone the repository and submodules:

git clone --recursive https://github.com/EricHayter/yadb

2. Build using CMake:

cd yadb
mkdir build
cd build
cmake ..
cmake --build .

---

Usage

After building, you can run the YADB shell:

# From the build/ directory
./src/shell/yadb-shell

Demo

Here's a quick demo of what YADB can currently do:

-- Create a table
CREATE TABLE users (name TEXT, age INTEGER);

-- Insert some data
INSERT INTO users VALUES (Alice, 30);
INSERT INTO users VALUES (Bob, 25);
INSERT INTO users VALUES (Charlie, 35);

-- Query the data
SELECT * FROM users;

Output:

┌─────────┬─────┐
│ name    │ age │
├─────────┼─────┤
│ Alice   │ 30  │
│ Bob     │ 25  │
│ Charlie │ 35  │
└─────────┴─────┘
3 rows in set

You can also select specific columns:

SELECT name FROM users;

Running Tests

Tests can be built and run for individual components:

# From the build/ directory
cmake --build . --target test

---

Architecture

YADB is organized into distinct layers handling parsing, query execution, storage, and result formatting. The diagram above shows the high-level architecture and relationships between major components:

• SQL Parsing Layer: Lexer and Parser (Flex/Bison) tokenize and parse SQL into an AST
• Executor: Dispatches SQL statements to appropriate handlers
• Core Components: Optimizer (iterator pipeline), Catalog (schema management), Table Manager, and Serialization
• Iterator Pipeline: Volcano-style query execution with FileScan, Selection, and Projection iterators
• Storage Layer: In-memory tables (default) and B+ tree infrastructure with disk management, buffering, and slotted page format

Note: For more detailed information about specific components, check the README files in the respective subdirectories (e.g., src/optimizer/README.md).

---

Supported SQL Syntax

YADB currently supports a subset of SQL. Here's what you can use:

CREATE TABLE

CREATE TABLE table_name (
    column1 TYPE,
    column2 TYPE,
    ...
);

Supported Types:

• INTEGER - 32-bit signed integer
• TEXT - Variable-length string

Example:

CREATE TABLE users (name TEXT, age INTEGER);

INSERT

INSERT INTO table_name VALUES (value1, value2, ...);

Notes:

• Values must match the column order and types from the table definition
• TEXT values do not require quotes

Example:

INSERT INTO users VALUES (Alice, 30);

SELECT

SELECT column1, column2, ... FROM table_name [WHERE condition];
SELECT * FROM table_name [WHERE condition];

Supported WHERE operators:

• = - Equality
• != - Inequality
• < - Less than
• > - Greater than
• <= - Less than or equal
• >= - Greater than or equal

Examples:

SELECT * FROM users;
SELECT name FROM users;
SELECT name, age FROM users WHERE age > 25;
SELECT * FROM users WHERE name = Alice;

---

Roadmap

• Set up blog
• Implement disk manager
• Implement disk scheduler
• Implement page buffer
• Implement slotted page interface
• Implement lexer and parser for SQL subset
• Implement shell interface
• Implement basic executor with type-safe operations
• Implement result printer with formatted table output
• Implement optimizer
  • Basic iterator-based query execution (Volcano model)
  • FileScanIterator and ProjectionIterator
  • SelectionIterator (WHERE clause filtering)
  • JoinIterator
  • Implement external sorting
  • Cost-based optimization
• Implement B+ tree storage engine
• Add transaction support
• Add concurrency control