TinySQL

🎥 Demo

TinySQL is a lightweight, educational SQL database engine written in pure Go. It implements a comprehensive subset of SQL features using only Go's standard library, making it perfect for learning database internals and for applications that need a simple embedded SQL database.

Quick start

Install

go get github.com/SimonWaldherr/tinySQL@latest

Use the engine directly

package main

import (
    "context"
    "fmt"
    tsql "github.com/SimonWaldherr/tinySQL"
)

func main() {
    db := tsql.NewDB()

    p := tsql.NewParser(`CREATE TABLE users (id INT, name TEXT)`)
    st, _ := p.ParseStatement()
    tsql.Execute(context.Background(), db, "default", st)

    p = tsql.NewParser(`INSERT INTO users VALUES (1, 'Alice')`)
    st, _ = p.ParseStatement()
    tsql.Execute(context.Background(), db, "default", st)

    p = tsql.NewParser(`SELECT id, name FROM users`)
    st, _ = p.ParseStatement()
    rs, _ := tsql.Execute(context.Background(), db, "default", st)

    for _, row := range rs.Rows {
        fmt.Println(tsql.GetVal(row, "id"), tsql.GetVal(row, "name"))
    }
}

Use with database/sql

package main

import (
    "database/sql"
    "fmt"
    _ "github.com/SimonWaldherr/tinySQL/internal/driver"
)

func main() {
    db, _ := sql.Open("tinysql", "mem://?tenant=default")
    defer db.Close()

    db.Exec(`CREATE TABLE t (id INT, name TEXT)`)
    db.Exec(`INSERT INTO t VALUES (?, ?)`, 1, "Alice")

    row := db.QueryRow(`SELECT name FROM t WHERE id = ?`, 1)
    var name string
    _ = row.Scan(&name)
    fmt.Println(name)
}

Run tests

# no cache
go test ./... -count=1

# with coverage output
go test -coverprofile=coverage.out ./...

Goals (and non-goals)

• Lightweight, educational SQL engine in pure Go
• Useful for embeddings, demos, and learning database internals
• Not intended as a production-grade relational database

Requirements

• Go 1.25+ (see go.mod)

DSN (Data Source Name) Format

When using the database/sql driver:

• In-memory database: mem://?tenant=<tenant_name>
• File-based database: file:/path/to/db.dat?tenant=<tenant_name>&autosave=1

Parameters:

• tenant - Tenant name for multi-tenancy (required)
• autosave - Auto-save to file (optional, for file-based databases)

Limitations

TinySQL is designed for educational purposes

Testing

Run the test suite:

# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run tests multiple times to check consistency
go test -v -count=3 ./...

Contributing

This is an educational project. Contributions that improve code clarity, add comprehensive examples, or enhance the learning experience are welcome.

Educational Goals

TinySQL demonstrates:

• SQL parsing and AST construction
• Query execution and optimization basics
• Database storage concepts
• Go's database/sql driver interface
• 3-valued logic (NULL semantics)
• JSON data handling in SQL
• Multi-tenancy patterns

Perfect for computer science students, developers learning database internals, or anyone who wants to understand how SQL databases work under the hood.