Files

T

claude@clouddev1 b17148b467 docs: scrub GitHub-specifics after Gitea migration; add tea issue conventions

- Cargo.toml: repository -> git.lazyeval.net/oli/rdbms-playground
- requirements.md: backlog now tracked as Gitea issues
- ADR-0001 Amendment 1: distribution channel reopened post-migration
  (Decision text preserved per supersede-don't-rewrite)
- CLAUDE.md: issue-tracking working method + Gitea/tea operational section

2026-06-09 20:07:40 +00:00

2.9 KiB

Raw Blame History

ADR-0001: Language and TUI framework

Status

Accepted

Context

RDBMS Playground is a cross-platform terminal application aimed at learners. It needs to feel fast, polished, and colourful, install cleanly on Linux, macOS, and Windows, and ship as a single binary with no runtime dependencies.

Beyond TUI rendering, the application has substantial SQL-handling needs: syntax highlighting, parsing user input to distinguish app DSL commands from SQL, rewriting simplified types into backend types, and analysing query plans for the teaching features.

Two stacks were realistic candidates:

Rust + Ratatui + Crossterm — strong cross-platform terminal support, single static binary, mature ecosystem. Crucially, sqlparser-rs is a high-quality dialect-aware SQL parser directly applicable to the parsing, highlighting, and query analysis features.
Go + Bubble Tea (Charm) — excellent default aesthetics, single static binary, easy distribution. Lacks an equivalent to sqlparser-rs; SQL parsing would need to be written from scratch or wrap a less suitable library.

Decision

Use Rust with Ratatui and Crossterm for the TUI, with sqlparser-rs for SQL parsing and rusqlite for the database layer. Distribute as prebuilt binaries via GitHub releases plus package managers (cargo binstall, Homebrew, Scoop, winget).

Consequences

Single static binary on all three target platforms.
Strong fit between SQL-heavy features and the Rust SQL ecosystem (sqlparser-rs, rusqlite).
Slightly steeper contributor on-ramp for developers unfamiliar with Rust compared to Go.
TUI styling will require explicit work to match the polish that Bubble Tea / Lipgloss give for free; budget for it in the design pass.

Amendment 1 — Distribution channel is open after the Gitea migration (2026-06-09)

The Decision block above assumed prebuilt binaries would ship "via GitHub releases plus package managers." Since then the repository has been migrated off GitHub to a self-hosted Gitea instance (git.lazyeval.net/oli/rdbms-playground), and tea is the forge CLI in use. The "GitHub releases" half of that sentence is therefore no longer a settled assumption.

This amendment does not pick a replacement. Binary distribution is not built yet (no release pipeline, no CI — requirements.md TT5/E* remain open), so the channel for prebuilt binaries is an open choice — Gitea releases, a GitHub mirror's releases, or both — to be settled by a dedicated ADR when distribution is actually implemented. The package-manager channels named in the Decision (cargo binstall, Homebrew, Scoop, winget) are independent of the forge and are unaffected.

(For the same supersede-don't-rewrite reason, the Decision block also still names sqlparser-rs, which ADRs 0030–0036 replaced with a hand-rolled grammar; that is recorded there, not by editing this ADR.)

2.9 KiB Raw Blame History Unescape Escape