claude@clouddev1
b17148b467
- 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
70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
# 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:
|
||
|
||
1. **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.
|
||
2. **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.)
|