toydb

toydb is a small SQL database written in Go. It is being built in incremental, testable slices. The current working path is an in-memory SQL database with an interactive REPL and script mode.

Current capabilities

• CREATE TABLE with INT and TEXT columns
• INSERT INTO ... VALUES ...
• SELECT projected columns from in-memory tables
• Tokenization, parsing, binding, catalog updates, and logical planning
• Syntax and semantic validation errors
• Interactive .exit and .quit commands
• SQL script execution with -f <file>
• Optional debug output for tokens, AST, bound AST, logical plan, catalog, storage, and query results

Disk persistence, filtering, full CRUD, indexes, transactions, recovery, and optimization are planned but not complete.

Quick start

Start the REPL:

make toydb

Or run it directly:

go run ./cmd/toydb

Try a session:

CREATE TABLE users (id INT, name TEXT);
INSERT INTO users VALUES (1, 'Akhilesh');
SELECT id, name FROM users;
.exit

Run the checked-in script:

go run ./cmd/toydb -f docs/script.sql

Script mode executes statements in order and stops at the first error.

Debug output

Debug output is enabled by default in DefaultConfig in config.go. Set Debug: false to show only normal errors and query results.

With debug enabled, the REPL prints stages in this order:

tokens → AST → bound AST → logical plan → catalog/storage → query results

The behavior is covered by the REPL tests and documented in the implementation slices.

Development commands

Command	Purpose
make test	Run all tests
make race	Run tests with the race detector
make fmt	Format Go packages
make lint	Run golangci-lint when installed
make build	Build the current API entrypoint to bin/api
make clean	Remove bin/ build artifacts

The API entrypoint is currently a scaffold. The SQL REPL is the primary executable path.

Project documentation

• project-specification.md — requirements and acceptance criteria
• docs/01.implementation-slices.md — roadmap, verification criteria, and completion status
• docs/02.repo-Structure.md — package layout and ownership boundaries
• docs/slices/ — detailed design for individual slices
• notes.md — concise lessons, bugs, decisions, and trade-offs
• agents.md — project references and documentation maintenance rules

Repository layout

cmd/toydb/       SQL REPL and script-mode executable
cmd/api/         HTTP entrypoint scaffold
internal/sql/    Tokens, tokenizer, AST, parser, and values
internal/repl/   Interactive and script input/output
internal/binder/ Name and type resolution
internal/catalog/Schema and metadata
internal/planner/Logical plan construction
internal/storage/In-memory rows and future disk storage
docs/            Project roadmap and slice documentation